# Planned Python Modules, Scripts & Frontend Files

> [← Repository Tree](./repo-tree.md) | [Tech & Files HTML View](./index.html) | Next: [ERD & Tables →](../04-data/erd-and-tables.md)

## Python Application Modules

| Module | Files | Core Responsibilities |
| :--- | :--- | :--- |
| **Entry & Core** | `run.py`, `app/main.py`, `app/core/{config,database,security,exceptions}.py` | Auto DB bootstrap + curriculum seed on startup, FastAPI factory, SQLite/Postgres engine, JWT/guest cookies, `pbkdf2_sha256` & PIN hashing |
| **ORM Models** | `app/models/{user,curriculum,exercise,progress}.py` | 16 SQLAlchemy tables: `User`, `LearnerProfile`, `Language`, `Course`, `Unit`, `Lesson`, `VocabularyItem`, `GrammarConcept`, `Exercise`, `AudioAsset`, `UserLessonProgress`, `ExerciseAttempt`, `WordMasterySRS`, `UserSkillEstimate`, `Sticker`, `UserSticker` |
| **Pydantic Schemas** | `app/schemas/{auth,curriculum,exercise,placement,gamification,pack}.py` | Request/response DTOs + 11-type `ExerciseConfigUnion` discriminated union + `speech_register` (`alias="register"`) pack schemas |
| **Exercise Engine** | `app/exercises/{text_normalizer,distractor_generator,grader,session_builder,placement_engine,score_estimator}.py` | Unicode `NFC` + RTL/CJK tokenizer, 11-type strategy grader, placement diagnostic (`A1–C1`/`N5–N1`), Band/TOEIC/JLPT score estimator |
| **Domain Services** | `app/services/{auth,curriculum,srs,gamification,audio,pack}_service.py` | Guest→account migration, tier/skill map assembly, SM-2 scheduling, XP/stars/stickers, multi-accent MP3 lookup, YAML pack upsert/export |
| **API Routers** | `app/api/{deps,pages}.py`, `app/api/v1/{auth,languages,lessons,placement,review,gamification,studio}.py` | Jinja2 views (`/`, `/learn`, `/placement`, `/lesson/{id}`, `/review`, `/stickers`, `/parent`, `/studio`, `/healthz`, `/favicon.ico`) + 21 REST `/api/v1` endpoints |

## Python CLI Scripts (`scripts/`)

| Script | CLI Command | Action |
| :--- | :--- | :--- |
| `scripts/init_db.py` | `.venv/bin/python -m scripts.init_db` | Creates SQLite tables, seeds `stickers.yaml` & all 17 starter packs |
| `scripts/validate_packs.py` | `.venv/bin/python -m scripts.validate_packs --strict` | Validates YAML syntax, Pydantic 11-type schemas, Unicode/RTL Bidi & answer solvability |
| `scripts/seed_curriculum.py` | `.venv/bin/python -m scripts.seed_curriculum --path content/packs/` | Idempotent recursive or single-pack slug-based upsert into DB |
| `scripts/generate_audio.py` | `.venv/bin/python -m scripts.generate_audio --lang en --accent en-GB` | Optional batch MP3 generator (`edge-tts`/`gTTS`), caching `{lang}/{accent}/{hash}.mp3` |
| `scripts/export_progress.py` | `.venv/bin/python -m scripts.export_progress --profile-id 1 --format csv` | Exports learner XP, mastery & exam readiness report |
| `scripts/export_d1_sql.py` | `.venv/bin/python -m scripts.export_d1_sql` | Exports Cloudflare D1 DDL (`0001_schema.sql`) & cascade-safe `ON CONFLICT` upserts (`0002_seed.sql`) |
| `scripts/sync_worker_assets.py` | `.venv/bin/python -m scripts.sync_worker_assets` | Syncs `app/static/` → `worker/public/static/` & `docs/` → `worker/public/docs-portal/` |

## Cloudflare Edge Worker Modules (`worker/src/`)

| Module | Files | Role |
| :--- | :--- | :--- |
| **Entry & Config** | `worker/wrangler.jsonc`, `worker/src/index.ts`, `worker/src/types.ts` | Hono HTTP router on `https://language.outxet.dev`, D1 & Assets bindings, cookie/error middleware |
| **Edge Domain Logic** | `worker/src/lib/{security,text_normalizer,grader,session_builder,score_estimator,placement_engine,srs_gamification,profile,curriculum,pack_service}.ts` | TypeScript parity implementations of Web Crypto `HS256`/`pbkdf2_sha256`, all 11 graders, SM-2 SRS, exam estimators & YAML Pack Studio |
| **Edge SSR Views** | `worker/src/views/html.ts` | HTML templates mirroring all 8 `app/templates/` views & linking shared `/static/*` JS/CSS modules |

## Frontend ES6+ Modules (`app/static/js/`)

| Module | Role |
| :--- | :--- |
| `app.js` & `api_client.js` | Topbar mode/access/SFX switches, guest-start form wiring, toast helper, & typed `fetch` API v1 wrapper |
| `drag_engine.js` | Unified `DragDropBoard` (`pointerdown/move/up` `>= 6px` threshold + floating ghost, `elementsFromPoint`, tap-to-select & keyboard `Enter`/`Space` parity) |
| `audio_engine.js` & `sfx_synth.js` | Multi-accent playback (`0.7x`/`1.0x`/`1.15x`) + procedural Web Audio SFX (`pickup`, `snap`, `remove`, `success`, `warning`, `tryAgain`, `celebration`) |
| `mascot.js` & `confetti.js` | Reactive **Breezy** coach mood/animation controller + Canvas celebratory confetti |
| `timer_hud.js` & `explanation_drawer.js` | Playful elapsed / Exam Focus countdown timer + structured Rule / `why_others_fail` / `band_tip` / `evidence_quote` / transcript drawer |
| `lesson_player.js` & `studio_builder.js` | Lesson & Brain Boost session orchestrator + Studio YAML/JSON editor, quick pack generator & live validator |
| `renderers/index.js` & `_board_helpers.js` | Shared `RENDERER_REGISTRY`, drop-slot factory, illustration loader & ordered-rail board builder |
| `renderers/*.js` (11 files) | Modular renderers implementing `mountRenderer(stageEl, exercise, opts)` -> `{ getSubmission(), applyFeedback(), reset(), destroy() }` |

## Changelog

| Version | Date | Summary of Changes |
| :--- | :--- | :--- |
| **v1.2.0** | 2026-11-22 | Documented new Cloudflare sync CLI scripts (`export_d1_sql.py`, `sync_worker_assets.py`) and all `worker/src/` Hono TypeScript modules serving `https://language.outxet.dev`. |
| **v1.1.0** | 2026-11-15 | Documented actual module exports (`mountRenderer`, `DragDropBoard`, `RENDERER_REGISTRY`), added `app.js`, `api_client.js`, `_board_helpers.js`, `renderers/index.js`, `/review`, `/healthz`, `speech_register` alias, and `Breezy` mascot. |
| **v1.0.0** | 2026-11-15 | Initial planned Python modules, CLI scripts, and JS frontend architecture. |

