diagram: hand-drawn SVG · no images
System Map · End-to-End Architecture

Kvasir System Map

Every Lambda, every layer, every pipeline, every data store and every AI provider — laid out as one visual blueprint. Built entirely from inline HTML and SVG.

23
Lambda Functions
5
Shared Layers
4
Data Stores
6
AI Providers
3
Media Pipelines
2
Companion Agents
15+
AWS Services
20+
AI Models
// 01 · Request Flow

From browser to byte-stream

A single user request traverses the edge, the auth layer, a Lambda, the data plane, and (when needed) an AI provider — then the same path back.

EDGE AUTH SERVICE DATA AI Browser kvasir.pub / quizly.pub CloudFront CDN · static + API API Gateway REST · Cognito authorizer Cognito Google / Facebook OAuth layer_auth JWT verify · user lookup Lambda (kv2_*) Python 3.13 · Pydantic layer_db / layer_ai SQLDB · ai_requests MySQL (RDS) domain tables DynamoDB chats · embeddings OpenSearch vector + keyword S3 buckets media · system · prompts LLM APIs · OpenAI / Anthropic / DeepSeek External GPU · FLUX · Whisper · XTTS Runway Gen-4 · video
Edge / CDN Auth Lambda services Data plane AI providers
// 02 · Lambda Service Map

23 functions, six domains

Every Lambda from src/lambda_v2/template.yml, grouped by the business capability it owns.

Identity & Access
Who you are, what you can touch
kv2_user kv2_access

User CRUD, profile, Google/Facebook OAuth binding, ACL checks.

Content & Learning
Books, courses, scenes, search
kv2_course kv2_text kv2_scene kv2_image kv2_search kv2_media kv2_board

Editing pipelines, FB2 ingest, OpenSearch index, scene composer, media catalog, the global game board.

Commerce
Pay, capture, settle
kv2_paypal_create_order kv2_paypal_capture_order kv2_paypal_webhook kv2_money kv2_artifacts

PayPal order lifecycle, webhook ledger, internal credit accounting, collectible artifacts.

AI Surface
Where the LLMs reach the user
kv2_AI_chat kv2_AI_echo kv2_AI_main kv2_feedback

Multi-turn chat, anonymous echo previews, Telegram + admin pipelines, in-product feedback / moderation.

Async Media Jobs
Long-running render workers
kv2_job kv2_S3_job_AI kv2_S3_job_aux

Job orchestration, S3-event-driven post-processing for AI-generated assets and auxiliary uploads.

Platform / Ops
Tools that keep the lights on
kv2_system internal_sql

System bucket loaders, prompt registry, ad-hoc SQL bridge for internal automations.

// 03 · Shared Layers

Five layers, every Lambda depends on at least one

Lambda Layers carry the code that doesn't belong to any one service. Centralising them keeps function bundles small and behaviour identical across the fleet.

Shared Lambda Layers layer_auth JWT · Cognito · OAuth layer_db SQLDB · common_sql layer_ai ai_requests · routing layer_search OpenSearch client layer_requests HTTP retries · pooling kv2_user kv2_AI_chat kv2_AI_echo kv2_course kv2_text kv2_search kv2_scene kv2_image
// 04 · AI Request Router

One call site, many providers

layer_ai/ai_requests.py exposes a single llm_call() function. Model selection, credit accounting and provider fallbacks are decided behind the wall.

kv2_AI_chat kv2_AI_echo kv2_AI_main kv2_course / kv2_text layer_ai · ai_requests.py llm_call() · moderate() · CFG_MAIN model registry · token / credit accounting retries · fallbacks · provider keys OpenAI · GPT-5.x / mini / nano Anthropic · Sonnet 4.6 / Haiku 4.5 DeepSeek v4 Gemini (translation) OpenAI Embeddings BFL / FLUX · image Runway Gen-4 · video Whisper · XTTS · TTS
// 05 · Media Generation Pipelines

Three parallel render chains

Off-AWS, on a dedicated GPU host (kv2_AI_main/app/ scripts), the heavy media work runs as orchestrated pipelines. Each one writes back to the same S3 buckets the Lambdas read.

Image pipeline
flux_generator · bfl_cron
Detailed prompt → FLUX render → S3 → DB row. Avatar series, scene illustrations, course art.
Prompt LLM-detailed flux_permutator style + ratio matrix BFL · FLUX.1 / 2 async cron-polled flux_alter_image retouch · variants S3 kv-image-pool DB row MySQL
Voice pipeline
tts_voice · whisper_recording · AI_cron_tts
Text-to-speech, voice cloning, and audio transcoding for lectures, narrations, scene dialogue.
Script text lecture / dialog voice picker clone catalog · lang XTTS · Tortoise on-GPU synth ffmpeg_job mux · normalise S3 kv-audio Whisper QA loop
Video pipeline
kv2_scene · runway_client · pipeline1/2/3
Scene prompt → Runway Gen-4 → ffmpeg compose → S3, with a billing hook that decrements user credits.
Scene def prompt + style kv2_scene validation · credits runway_client Gen-4 · async poll AI_cron_ffmpeg cut · join · mux S3 kv-video billing kv2_money
// 06 · Data Layer

Where state lives

Each store is chosen for a specific access pattern, not as a default.

🗄️
MySQL · RDS
Domain · Transactional
  • users · authors · sessions
  • courses · components · lectures
  • contests · tags · orders
  • credits ledger · ACL
⚡
DynamoDB
Hot path · NoSQL
  • kv2-conversation (chat history)
  • kv2-contest (echo state)
  • user_profile_ext · feedback
  • embeddings cache
🔎
OpenSearch
Full-text · Vector
  • courses index
  • components index
  • vector embeddings (RAG)
  • cross-language search
🪣
S3
Object storage
  • kv-system · prompts & configs
  • kv-image-pool · generated art
  • kv-audio / kv-video · TTS & scenes
  • kv-courses · uploaded source
// 07 · Frontend

Two domains, one codebase

Static HTML served from S3 behind CloudFront. Same JS modules, different feature gates per host.

kvasir.pub
Creator surface
Editors enabled — books, courses, scenes, echo chats. Authoring tools, admin pages, monetisation.
readings-edit course-edit scene-contest echo-edit admin edit-prompts
quizly.pub
Reader surface
Read-only mirror. Welcome funnel, public echoes, contest browsing — optimised for cold traffic.
welcome echoes contests scene book / chat share
shared JS
Module set
Common utilities, API endpoints, search, notifications, board — i18n with 3 languages.
common.js welcome.js board.js analytics.js i18n: en · ru · he Tailwind
// 08 · Companion Agents (off-AWS)

Local Python agents that suggest, never act

Two Claude-powered scheduled agents, run by cron on the operator's host. Both are advisory: they prepare drafts and digests for human review.

Social Scanner
High-intent learning conversations

Reddit + X + YouTube scan → scoring → Claude-drafted native-tone replies. Stored in SQLite for human approval.

Reddit API Playwright Claude Sonnet Jinja2 cron
AI News Agent
Daily curated AI digest

RSS + arXiv + Medium + X → dedupe → Claude annotation → static HTML brief. Weekly X-influence graph builder runs in parallel.

feedparser arXiv readability-lxml Claude X Graph