# Planned Repository Tree

> [← Tech Stack](./tech-stack.md) | [Tech & Files HTML View](./index.html) | Next: [Python & Frontend Modules →](./python-and-frontend.md)

```text
LanguageLearning/
├── docs/                                # Split MD + visual HTML portals (01-hld .. 04-data)
├── app/
│   ├── __init__.py
│   ├── main.py                          # FastAPI app factory, static mount & routers
│   ├── core/                            # config.py, database.py, security.py, exceptions.py
│   ├── models/                          # user.py, curriculum.py, exercise.py, progress.py
│   ├── schemas/                         # auth.py, curriculum.py, exercise.py, placement.py, gamification.py, pack.py
│   ├── exercises/                       # text_normalizer.py, distractor_generator.py, grader.py,
│   │                                    # session_builder.py, placement_engine.py, score_estimator.py
│   ├── services/                        # auth_service.py, curriculum_service.py, srs_service.py,
│   │                                    # gamification_service.py, audio_service.py, pack_service.py
│   ├── api/
│   │   ├── deps.py                      # DB session, active learner/user, parent PIN guard
│   │   ├── pages.py                     # Jinja2 HTML views
│   │   └── v1/                          # auth.py, languages.py, lessons.py, placement.py,
│   │                                    # review.py, gamification.py, studio.py
│   ├── templates/                       # base.html, index.html, learn_map.html, placement.html,
│   │                                    # lesson_player.html, stickers.html, parent_dashboard.html, studio.html
│   └── static/
│       ├── css/                         # tokens.css, base.css, map.css, exercises.css
│       ├── js/
│       │   ├── core & UI                # app.js, api_client.js, drag_engine.js, audio_engine.js, sfx_synth.js,
│       │   │                            # mascot.js, confetti.js, timer_hud.js, explanation_drawer.js,
│       │   │                            # lesson_player.js, studio_builder.js
│       │   └── renderers/               # index.js, _board_helpers.js + 11 renderers (picture_match .. listening_lab)
│       ├── img/                         # owl-favicon.svg, avatars/{owl,fox,cat,panda}.svg, stickers/*.svg
│       └── audio/tts_cache/             # {lang}/{accent}/{hash}.mp3 (.gitkeep)
├── content/
│   ├── stickers.yaml                    # Global, JLPT Nx, IELTS Band, TESOL badge rules
│   └── packs/
│       ├── en/                          # en_general_a0_c2.yaml, en_ielts_academic.yaml,
│       │                                # en_toeic_pro.yaml, en_tesol_mastery.yaml
│       ├── ja/                          # ja_jlpt_n5.yaml .. ja_jlpt_n1.yaml
│       ├── zh/                          # zh_hsk_ladder.yaml
│       ├── ko/                          # ko_topik_ladder.yaml
│       ├── fr/                          # fr_delf_dalf.yaml
│       ├── es/                          # es_dele_ladder.yaml
│       ├── de/                          # de_goethe_ladder.yaml
│       ├── ar/                          # ar_msa_ladder.yaml
│       ├── vi/                          # vi_complete_ladder.yaml
│       └── pl/                          # pl_complete_ladder.yaml
├── worker/                              # Cloudflare Worker + D1 deployment (language.outxet.dev)
│   ├── wrangler.jsonc                   # Worker config, custom domain & D1 binding (lingobright-db)
│   ├── package.json / tsconfig.json
│   ├── migrations/                      # 0001_schema.sql, 0002_seed.sql (auto-generated by export_d1_sql.py)
│   ├── public/                          # Git-ignored build output synced from app/static & docs/
│   ├── src/
│   │   ├── index.ts                     # Hono router (8 HTML views + 21 /api/v1 endpoints)
│   │   ├── types.ts                     # Env, D1 row interfaces & JSON coercion helpers
│   │   ├── views/html.ts                # Edge SSR HTML shells sharing app/static/ frontend
│   │   └── lib/                         # security.ts, text_normalizer.ts, grader.ts, session_builder.ts,
│   │                                    # score_estimator.ts, placement_engine.ts, srs_gamification.ts,
│   │                                    # profile.ts, curriculum.ts, pack_service.ts
│   └── tests/grader_normalizer.test.ts  # Vitest edge parity tests
├── scripts/                             # init_db.py, validate_packs.py, seed_curriculum.py,
│                                        # generate_audio.py, export_progress.py,
│                                        # export_d1_sql.py, sync_worker_assets.py
├── tests/                               # conftest.py, test_text_normalizer.py, test_grader_all_11.py,
│                                        # test_placement_and_estimator.py, test_srs_gamification.py,
│                                        # test_all_starter_packs.py, test_api_flow.py
├── run.py                               # Single-command launcher (auto DB init + uvicorn)
└── requirements.txt / requirements-dev.txt / pyproject.toml / README.md
```

## Changelog

| Version | Date | Summary of Changes |
| :--- | :--- | :--- |
| **v1.2.0** | 2026-11-22 | Added `content/packs/pl/pl_complete_ladder.yaml`, `scripts/export_d1_sql.py`, `scripts/sync_worker_assets.py`, and full `worker/` Cloudflare Worker + D1 deployment tree. |
| **v1.1.0** | 2026-11-15 | Added implemented helper/asset files (`renderers/index.js`, `renderers/_board_helpers.js`, `owl-favicon.svg`, `avatars/*.svg`, `stickers/*.svg`, `tests/conftest.py`, `requirements-dev.txt`) to exact repository tree. |
| **v1.0.0** | 2026-11-15 | Initial planned repository directory tree. |

