Architecture

High-Level Overview

LearnPanta follows a durable, event-driven architecture. The core principle: every major AI operation is a persistent Temporal workflow that survives crashes and retries automatically.

Durable Workflows (Temporal)

Unlike standard CRUD apps, LearnPanta uses Temporal to manage exam session lifecycles:

Why Temporal?

Automatic Retry: If a worker crashes or AI times out, Temporal retries without losing progress
State Persistence: Exam state survives server restarts
Long-Running: Handles 2-6+ hour exam sessions reliably

Session Lifecycle

Workflow Timeline

Workflow Interaction Patterns

Signals (fire-and-forget): Frontend pushes data to workflow

# Backend receives metric, signals workflow
await workflow_handle.signal("add_metric", metric_data)

Queries (request-response): Frontend requests current state

# Get current session state
state = await workflow_handle.query("get_state")

Activities (durable execution): Workflow calls external services

# Workflow triggers AI analysis
result = await workflow.execute_activity(
    telemetry_analyzer_agent,
    input_data,
    start_to_close_timeout=timedelta(minutes=5)
)

AI Interaction Pattern

Every AI call follows a structured pattern:

Data Persistence

Data Type	Storage	Purpose
Users, Exams, Sessions, Questions	PostgreSQL (Cloud SQL)	Core relational data
Temporal Workflow History	PostgreSQL (Temporal DB)	Durable workflow state
Session Metrics	TimescaleDB + Temporal State	Historical analytics + per-session telemetry
Question Embeddings	Pinecone	Semantic search vectors

Database Schema

Key Tables:

Table	Purpose
`exams`	Certification catalog (584 exams)
`papers`	Exam instances/forms
`sections`	Logical groupings within papers
`questions`	Question bank with `domain`, `tags`, `options`
`section_questions`	Links questions to sections with ordering
`sessions`	Candidate attempts with `responses`, `feedback`
`stimuli`	Shared content (passages, images, case studies)
`assets`	Uploaded files (scratchpad images)
`enrollments`	Candidate-Exam subscriptions

Kubernetes Deployment

API Routes Summary

Route	Purpose
`POST /sessions`	Create exam session, start Temporal workflow
`POST /sessions/{id}/finalize`	Submit exam, trigger feedback synthesis
`WS /ws/stream/{id}`	Real-time telemetry streaming
`GET /academic/exams`	List available exams
`GET /academic/papers/{id}`	Get paper with sections and questions
`POST /debrief/orchestrate`	Generate beat-synced review script
`POST /debrief/brief`	Per-question paragraph (review sync)
`POST /debrief/tts`	Text-to-speech for debrief audio
`POST /curator/batch-curate`	Batch generate exam content

AI Debrief Flow

Temporal Workflow Flow

AI Review Tab Flow

Security

Auth: Firebase ID token (Authorization: Bearer <id_token>)
Guest Sessions: Short‑lived X-Guest-Token for diagnostics
CORS: Configured for production domains
Database: Private Cloud SQL with IAM auth
Secrets: Kubernetes secrets for credentials

Next Steps

AI Agents - How the agents work
Development - Local setup guide
Deployment - Deploy to GCP