# seoh0711/gemini-antigravity-study architecture

> Architecture diagram of the GitHub repository seoh0711/gemini-antigravity-study, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seoh0711/gemini-antigravity-study
- Repository: https://github.com/seoh0711/gemini-antigravity-study

## Overview

#### Purpose and Topology
This repository builds a curriculum-driven learning and exam-practice application. It contains a React learner UI, two alternative backend implementations, and a staged content-production workspace. The deployable primary stack appears to be a Cloudflare Worker API plus static frontend; a Python backend provides a parallel FastAPI-style implementation.

#### Application Entry Points
- Frontend bootstraps from `app/frontend/src/main.tsx`, renders application routing in `app/frontend/src/App.tsx`, and defines page routes in `app/frontend/src/router.tsx`.
- Cloudflare API entry is `app/worker/src/index.ts`, with application wiring in `app/worker/src/app.ts`.
- Python API entry is `app/backend/main.py`; database and seed bootstrapping reside in `app/backend/database.py` and `app/backend/seed.py`.
- Worker deployment/runtime settings are defined in `app/worker/wrangler.toml`.

#### Learner Frontend
The Vite/React TypeScript client implements public/authenticated learning, quizzes, challenges, notes, and progress views. It centralizes API communication and domain types under `app/frontend/src/api/client.ts` and `app/frontend/src/api/types.ts`; authentication state and route protection are handled by `app/frontend/src/auth/AuthContext.tsx` and `app/frontend/src/components/RequireAuth.tsx`.

Core user journeys are represented by pages:
- Learning syllabus/topic delivery: `app/frontend/src/pages/Learn.tsx`, `app/frontend/src/pages/LearnTopic.tsx`
- Quiz execution: `app/frontend/src/pages/Quiz.tsx`
- Challenge discovery/detail: `app/frontend/src/pages/Challenges.tsx`, `app/frontend/src/pages/ChallengeDetail.tsx`
- Aggregated learner progress: `app/frontend/src/pages/Stats.tsx`

#### API and Domain Boundary
The Worker API separates HTTP route handlers by learner domain: `app/worker/src/routes/content.ts`, `app/worker/src/routes/quiz.ts`, `app/worker/src/routes/progress.ts`, and `app/worker/src/routes/challenges.ts`. Authentication is implemented independently in `app/worker/src/auth.ts` and exposed through `app/worker/src/routes/auth.ts`.

The Python backend mirrors this domain partition—`app/backend/routers/content.py`, `app/backend/routers/quiz.py`, `app/backend/routers/progress.py`, and `app/backend/routers/auth.py`—with shared models, request/response schemas, and serializers in `app/backend/models.py`, `app/backend/schemas.py`, and `app/backend/serializers.py`. This duplication is an important implementation boundary: clients should target one deployed API contract, not combine both backends.

#### Assessment and Progress Flow
A learner requests content or a question set, submits answers to quiz/challenge endpoints, then receives grading and persistence-backed progress/statistics updates. Grading logic is explicit in `app/worker/src/grading.ts` and `app/backend/grading.py`; questions, quizzes, challenges, and progress each have dedicated routes. The frontend’s `app/frontend/src/pages/Quiz.tsx` and `app/frontend/src/components/QuestionCard.tsx` form the main answer-capture and feedback surface.

#### Data and Infrastructure
The Cloudflare Worker uses database access through `app/worker/src/db.ts`, with schema initialization in `app/worker/migrations/0001_init.sql`. Seed data is generated for that runtime by `app/worker/scripts/gen-seed.mjs`. The Python alternative has its own persistence layer at `app/backend/database.py`. Cloudflare deployment guidance is present in `DEPLOY.md` and `.claude/skills/cloudflare-deploy/SKILL.md`.

#### Curriculum Content Pipeline
`_workspace` is a staged authoring/validation pipeline rather than application runtime code:
- Curriculum structure and plans: `_workspace/00_architect/syllabus-tree.json`, `_workspace/00_architect/content-plan.md`
- Authored lessons: `_workspace/10_content/content.json`
- Questions and challenges: `_workspace/20_questions/questions.json`, `_workspace/20_questions/challenges.json`
- Content and integration QA outputs: `_workspace/30_qa/content-qa-report.md`, `_workspace/40_qa/integration-qa-report.md`

This pipeline produces structured curriculum and assessment assets intended to seed or populate the application’s content-serving and assessment domains.

Main entry points: [`app/frontend/src/App.tsx`](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/App.tsx) (App and routing), [`app/worker/src/db.ts`](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/db.ts) (Worker database access), [`app/frontend/src/api/client.ts`](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/api/client.ts) (API client and types), [`app/worker/src/index.ts`](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/index.ts) (Worker entry and app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Learner Frontend"]
  node_frontend_bootstrap["Frontend bootstrap<br/>React entry<br/>[main.tsx]"]
  node_frontend_app["App and routing<br/>React routes<br/>[App.tsx]"]
  node_frontend_auth["Auth guard<br/>auth state<br/>[AuthContext.tsx]"]
  node_frontend_api["API client and types<br/>API boundary<br/>[client.ts]"]
  node_frontend_learning["Learning views<br/>learner pages<br/>[Learn.tsx]"]
  node_frontend_quiz["Quiz interaction<br/>assessment UI<br/>[Quiz.tsx]"]
  node_frontend_progress["Progress views<br/>learner pages<br/>[Stats.tsx]"]
end

subgraph group_worker["Primary Worker API"]
  node_worker_entry{{"Worker entry and app<br/>HTTP application<br/>[index.ts]"}}
  node_worker_auth["Authentication<br/>auth routes<br/>[auth.ts]"]
  node_worker_domains["Content, quiz and progress routes<br/>domain routes<br/>[content.ts]"]
  node_worker_grading["Grading<br/>assessment logic<br/>[grading.ts]"]
  node_worker_db[("Worker database access<br/>persistence layer<br/>[db.ts]")]
  node_worker_schema["Database schema<br/>SQL migration<br/>[0001_init.sql]"]
end

subgraph group_python["Alternative Python API"]
  node_python_entry{{"Python API<br/>FastAPI entry<br/>[main.py]"}}
  node_python_domains["Mirrored domain routers<br/>API routes<br/>[content.py]"]
  node_python_grading["Python grading<br/>assessment logic<br/>[grading.py]"]
  node_python_db[("Python persistence<br/>database bootstrap<br/>[database.py]")]
end

subgraph group_pipeline["Curriculum Pipeline"]
  node_curriculum_plan["Curriculum plan<br/>syllabus assets<br/>[syllabus-tree.json]"]
  node_authored_content["Authored lessons<br/>content assets<br/>[content.json]"]
  node_assessment_assets["Questions and challenges<br/>assessment assets<br/>[questions.json]"]
  node_qa_reports["Content and integration QA<br/>validation outputs"]
end

node_frontend_bootstrap -->|"renders"| node_frontend_app
node_frontend_app -->|"protects routes"| node_frontend_auth
node_frontend_app -->|"routes to"| node_frontend_learning
node_frontend_app -->|"routes to"| node_frontend_quiz
node_frontend_app -->|"routes to"| node_frontend_progress
node_frontend_learning -->|"loads content"| node_frontend_api
node_frontend_quiz -->|"submits answers"| node_frontend_api
node_frontend_progress -->|"loads statistics"| node_frontend_api
node_frontend_api -->|"primary API contract"| node_worker_entry
node_worker_entry -->|"mounts"| node_worker_auth
node_worker_entry -->|"mounts"| node_worker_domains
node_worker_domains -->|"grades submissions"| node_worker_grading
node_worker_domains -->|"reads and writes"| node_worker_db
node_worker_grading -->|"persists outcomes"| node_worker_db
node_worker_schema -->|"initializes"| node_worker_db
node_python_entry -->|"mounts"| node_python_domains
node_python_domains -->|"grades submissions"| node_python_grading
node_python_domains -->|"reads and writes"| node_python_db
node_curriculum_plan -->|"guides"| node_authored_content
node_authored_content -->|"drives assessments"| node_assessment_assets
node_assessment_assets -->|"validated by"| node_qa_reports
node_authored_content -.->|"seeds content"| node_worker_db
node_assessment_assets -.->|"seeds assessments"| node_worker_db

click node_frontend_bootstrap "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/main.tsx"
click node_frontend_app "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/App.tsx"
click node_frontend_auth "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/auth/AuthContext.tsx"
click node_frontend_api "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/api/client.ts"
click node_frontend_learning "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/pages/Learn.tsx"
click node_frontend_quiz "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/pages/Quiz.tsx"
click node_frontend_progress "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/pages/Stats.tsx"
click node_worker_entry "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/index.ts"
click node_worker_auth "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/routes/auth.ts"
click node_worker_domains "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/routes/content.ts"
click node_worker_grading "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/grading.ts"
click node_worker_db "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/db.ts"
click node_worker_schema "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/migrations/0001_init.sql"
click node_python_entry "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/backend/main.py"
click node_python_domains "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/backend/routers/content.py"
click node_python_grading "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/backend/grading.py"
click node_python_db "https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/backend/database.py"
click node_curriculum_plan "https://github.com/seoh0711/gemini-antigravity-study/blob/main/_workspace/00_architect/syllabus-tree.json"
click node_authored_content "https://github.com/seoh0711/gemini-antigravity-study/blob/main/_workspace/10_content/content.json"
click node_assessment_assets "https://github.com/seoh0711/gemini-antigravity-study/blob/main/_workspace/20_questions/questions.json"
click node_qa_reports "https://github.com/seoh0711/gemini-antigravity-study/blob/main/_workspace/30_qa/content-qa-report.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_bootstrap,node_frontend_app,node_frontend_auth,node_frontend_api,node_frontend_learning,node_frontend_quiz,node_frontend_progress toneBlue
class node_worker_entry,node_worker_auth,node_worker_domains,node_worker_grading,node_worker_db,node_worker_schema toneAmber
class node_python_entry,node_python_domains,node_python_grading,node_python_db toneMint
class node_curriculum_plan,node_authored_content,node_assessment_assets,node_qa_reports toneRose
```

## Components

### Learner Frontend

React client for learning and practice.

- [Frontend bootstrap](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/main.tsx): React entry · `app/frontend/src/main.tsx`
- [App and routing](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/App.tsx): React routes · `app/frontend/src/App.tsx`
- [Auth guard](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/auth/AuthContext.tsx): auth state · `app/frontend/src/auth/AuthContext.tsx`
- [API client and types](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/api/client.ts): API boundary · `app/frontend/src/api/client.ts`
- [Learning views](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/pages/Learn.tsx): learner pages · `app/frontend/src/pages/Learn.tsx`
- [Quiz interaction](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/pages/Quiz.tsx): assessment UI · Captures answers and presents feedback. · `app/frontend/src/pages/Quiz.tsx`
- [Progress views](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/frontend/src/pages/Stats.tsx): learner pages · `app/frontend/src/pages/Stats.tsx`

### Primary Worker API

Cloudflare Worker deployment target.

- [Worker entry and app](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/index.ts): HTTP application · `app/worker/src/index.ts`
- [Authentication](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/routes/auth.ts): auth routes · `app/worker/src/routes/auth.ts`
- [Content, quiz and progress routes](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/routes/content.ts): domain routes · `app/worker/src/routes/content.ts`
- [Grading](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/grading.ts): assessment logic · `app/worker/src/grading.ts`
- [Worker database access](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/src/db.ts): persistence layer · `app/worker/src/db.ts`
- [Database schema](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/worker/migrations/0001_init.sql): SQL migration · `app/worker/migrations/0001_init.sql`

### Alternative Python API

Parallel FastAPI-style implementation.

- [Python API](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/backend/main.py): FastAPI entry · `app/backend/main.py`
- [Mirrored domain routers](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/backend/routers/content.py): API routes · Alternative content, quiz, progress, and auth contract implementation. · `app/backend/routers/content.py`
- [Python grading](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/backend/grading.py): assessment logic · `app/backend/grading.py`
- [Python persistence](https://github.com/seoh0711/gemini-antigravity-study/blob/main/app/backend/database.py): database bootstrap · `app/backend/database.py`

### Curriculum Pipeline

Staged authored content and QA assets.

- [Curriculum plan](https://github.com/seoh0711/gemini-antigravity-study/blob/main/_workspace/00_architect/syllabus-tree.json): syllabus assets · `_workspace/00_architect/syllabus-tree.json`
- [Authored lessons](https://github.com/seoh0711/gemini-antigravity-study/blob/main/_workspace/10_content/content.json): content assets · `_workspace/10_content/content.json`
- [Questions and challenges](https://github.com/seoh0711/gemini-antigravity-study/blob/main/_workspace/20_questions/questions.json): assessment assets · `_workspace/20_questions/questions.json`
- [Content and integration QA](https://github.com/seoh0711/gemini-antigravity-study/blob/main/_workspace/30_qa/content-qa-report.md): validation outputs · `_workspace/30_qa/content-qa-report.md`

## Connections

- Frontend bootstrap → App and routing: renders
- App and routing → Auth guard: protects routes
- App and routing → Learning views: routes to
- App and routing → Quiz interaction: routes to
- App and routing → Progress views: routes to
- Learning views → API client and types: loads content
- Quiz interaction → API client and types: submits answers
- Progress views → API client and types: loads statistics
- API client and types → Worker entry and app: primary API contract
- Worker entry and app → Authentication: mounts
- Worker entry and app → Content, quiz and progress routes: mounts
- Content, quiz and progress routes → Grading: grades submissions
- Content, quiz and progress routes → Worker database access: reads and writes
- Grading → Worker database access: persists outcomes
- Database schema → Worker database access: initializes
- Python API → Mirrored domain routers: mounts
- Mirrored domain routers → Python grading: grades submissions
- Mirrored domain routers → Python persistence: reads and writes
- Curriculum plan → Authored lessons: guides
- Authored lessons → Questions and challenges: drives assessments
- Questions and challenges → Content and integration QA: validated by
- Authored lessons → Worker database access: seeds content
- Questions and challenges → Worker database access: seeds assessments