update reading-listening + phát âm vob

.claude/skills/gitnexus/gitnexus-cli/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: gitnexus-cli
+description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+---
+
+# GitNexus CLI Commands
+
+All commands work via `npx` — no global install required.
+
+## Commands
+
+### analyze — Build or refresh the index
+
+```bash
+npx gitnexus analyze
+```
+
+Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
+
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
+
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.
+
+### status — Check index freshness
+
+```bash
+npx gitnexus status
+```
+
+Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
+
+### clean — Delete the index
+
+```bash
+npx gitnexus clean
+```
+
+Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
+
+| Flag      | Effect                                            |
+| --------- | ------------------------------------------------- |
+| `--force` | Skip confirmation prompt                          |
+| `--all`   | Clean all indexed repos, not just the current one |
+
+### wiki — Generate documentation from the graph
+
+```bash
+npx gitnexus wiki
+```
+
+Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
+
+| Flag                | Effect                                    |
+| ------------------- | ----------------------------------------- |
+| `--force`           | Force full regeneration                   |
+| `--model <model>`   | LLM model (default: minimax/minimax-m2.5) |
+| `--base-url <url>`  | LLM API base URL                          |
+| `--api-key <key>`   | LLM API key                               |
+| `--concurrency <n>` | Parallel LLM calls (default: 3)           |
+| `--gist`            | Publish wiki as a public GitHub Gist      |
+
+### list — Show all indexed repos
+
+```bash
+npx gitnexus list
+```
+
+Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
+
+## After Indexing
+
+1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
+2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
+
+## Troubleshooting
+
+- **"Not inside a git repository"**: Run from a directory inside a git repo
+- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
+- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

.claude/skills/gitnexus/gitnexus-debugging/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: gitnexus-debugging
+description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
+---
+
+# Debugging with GitNexus
+
+## When to Use
+
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "This endpoint returns 500"
+- Investigating bugs, errors, or unexpected behavior
+
+## Workflow
+
+```
+1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
+2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
+3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
+4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] Understand the symptom (error message, unexpected behavior)
+- [ ] gitnexus_query for error text or related code
+- [ ] Identify the suspect function from returned processes
+- [ ] gitnexus_context to see callers and callees
+- [ ] Trace execution flow via process resource if applicable
+- [ ] gitnexus_cypher for custom call chain traces if needed
+- [ ] Read source files to confirm root cause
+```
+
+## Debugging Patterns
+
+| Symptom              | GitNexus Approach                                          |
+| -------------------- | ---------------------------------------------------------- |
+| Error message        | `gitnexus_query` for error text → `context` on throw sites |
+| Wrong return value   | `context` on the function → trace callees for data flow    |
+| Intermittent failure | `context` → look for external calls, async deps            |
+| Performance issue    | `context` → find symbols with many callers (hot paths)     |
+| Recent regression    | `detect_changes` to see what your changes affect           |
+
+## Tools
+
+**gitnexus_query** — find code related to error:
+
+```
+gitnexus_query({query: "payment validation error"})
+→ Processes: CheckoutFlow, ErrorHandling
+→ Symbols: validatePayment, handlePaymentError, PaymentException
+```
+
+**gitnexus_context** — full context for a suspect:
+
+```
+gitnexus_context({name: "validatePayment"})
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates (external API!)
+→ Processes: CheckoutFlow (step 3/7)
+```
+
+**gitnexus_cypher** — custom call chain traces:
+
+```cypher
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
+RETURN [n IN nodes(path) | n.name] AS chain
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+2. gitnexus_context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls fetchRates (external)
+
+4. Root cause: fetchRates calls external API without proper timeout
+```

.claude/skills/gitnexus/gitnexus-exploring/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: gitnexus-exploring
+description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
+---
+
+# Exploring Codebases with GitNexus
+
+## When to Use
+
+- "How does authentication work?"
+- "What's the project structure?"
+- "Show me the main components"
+- "Where is the database logic?"
+- Understanding code you haven't seen before
+
+## Workflow
+
+```
+1. READ gitnexus://repos                          → Discover indexed repos
+2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
+3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
+4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
+5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
+```
+
+> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] READ gitnexus://repo/{name}/context
+- [ ] gitnexus_query for the concept you want to understand
+- [ ] Review returned processes (execution flows)
+- [ ] gitnexus_context on key symbols for callers/callees
+- [ ] READ process resource for full execution traces
+- [ ] Read source files for implementation details
+```
+
+## Resources
+
+| Resource                                | What you get                                            |
+| --------------------------------------- | ------------------------------------------------------- |
+| `gitnexus://repo/{name}/context`        | Stats, staleness warning (~150 tokens)                  |
+| `gitnexus://repo/{name}/clusters`       | All functional areas with cohesion scores (~300 tokens) |
+| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens)              |
+| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens)              |
+
+## Tools
+
+**gitnexus_query** — find execution flows related to a concept:
+
+```
+gitnexus_query({query: "payment processing"})
+→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Symbols grouped by flow with file locations
+```
+
+**gitnexus_context** — 360-degree view of a symbol:
+
+```
+gitnexus_context({name: "validateUser"})
+→ Incoming calls: loginHandler, apiMiddleware
+→ Outgoing calls: checkToken, getUserById
+→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
+2. gitnexus_query({query: "payment processing"})
+   → CheckoutFlow: processPayment → validateCard → chargeStripe
+   → RefundFlow: initiateRefund → calculateRefund → processRefund
+3. gitnexus_context({name: "processPayment"})
+   → Incoming: checkoutHandler, webhookHandler
+   → Outgoing: validateCard, chargeStripe, saveTransaction
+4. Read src/payments/processor.ts for implementation details
+```

.claude/skills/gitnexus/gitnexus-guide/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gitnexus-guide
+description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
+---
+
+# GitNexus Guide
+
+Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring:
+
+1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
+2. **Match your task to a skill below** and **read that skill file**
+3. **Follow the skill's workflow and checklist**
+
+> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
+
+## Skills
+
+| Task                                         | Skill to read       |
+| -------------------------------------------- | ------------------- |
+| Understand architecture / "How does X work?" | `gitnexus-exploring`         |
+| Blast radius / "What breaks if I change X?"  | `gitnexus-impact-analysis`   |
+| Trace bugs / "Why is X failing?"             | `gitnexus-debugging`         |
+| Rename / extract / split / refactor          | `gitnexus-refactoring`       |
+| Tools, resources, schema reference           | `gitnexus-guide` (this file) |
+| Index, status, clean, wiki CLI commands      | `gitnexus-cli`               |
+
+## Tools Reference
+
+| Tool             | What it gives you                                                        |
+| ---------------- | ------------------------------------------------------------------------ |
+| `query`          | Process-grouped code intelligence — execution flows related to a concept |
+| `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
+| `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `detect_changes` | Git-diff impact — what do your current changes affect                    |
+| `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
+| `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
+| `list_repos`     | Discover indexed repos                                                   |
+
+## Resources Reference
+
+Lightweight reads (~100-500 tokens) for navigation:
+
+| Resource                                       | Content                                   |
+| ---------------------------------------------- | ----------------------------------------- |
+| `gitnexus://repo/{name}/context`               | Stats, staleness check                    |
+| `gitnexus://repo/{name}/clusters`              | All functional areas with cohesion scores |
+| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members                              |
+| `gitnexus://repo/{name}/processes`             | All execution flows                       |
+| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace                        |
+| `gitnexus://repo/{name}/schema`                | Graph schema for Cypher                   |
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```

.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: gitnexus-impact-analysis
+description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
+---
+
+# Impact Analysis with GitNexus
+
+## When to Use
+
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+- Before making non-trivial code changes
+- Before committing — to understand what your changes affect
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+3. gitnexus_detect_changes()                               → Map current git changes to affected flows
+4. Assess risk and report to user
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
+- [ ] Review d=1 items first (these WILL BREAK)
+- [ ] Check high-confidence (>0.8) dependencies
+- [ ] READ processes to check affected execution flows
+- [ ] gitnexus_detect_changes() for pre-commit check
+- [ ] Assess risk level and report to user
+```
+
+## Understanding Output
+
+| Depth | Risk Level       | Meaning                  |
+| ----- | ---------------- | ------------------------ |
+| d=1   | **WILL BREAK**   | Direct callers/importers |
+| d=2   | LIKELY AFFECTED  | Indirect dependencies    |
+| d=3   | MAY NEED TESTING | Transitive effects       |
+
+## Risk Assessment
+
+| Affected                       | Risk     |
+| ------------------------------ | -------- |
+| <5 symbols, few processes      | LOW      |
+| 5-15 symbols, 2-5 processes    | MEDIUM   |
+| >15 symbols or many processes  | HIGH     |
+| Critical path (auth, payments) | CRITICAL |
+
+## Tools
+
+**gitnexus_impact** — the primary tool for symbol blast radius:
+
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_detect_changes** — git-diff based impact analysis:
+
+```
+gitnexus_detect_changes({scope: "staged"})
+
+→ Changed: 5 symbols in 3 files
+→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
+→ Risk: MEDIUM
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware (WILL BREAK)
+   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
+
+2. READ gitnexus://repo/my-app/processes
+   → LoginFlow and TokenRefresh touch validateUser
+
+3. Risk: 2 direct callers, 2 processes = MEDIUM
+```

.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: gitnexus-refactoring
+description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
+---
+
+# Refactoring with GitNexus
+
+## When to Use
+
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Move this to a new file"
+- Any task involving renaming, extracting, splitting, or restructuring code
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
+2. gitnexus_query({query: "X"})                            → Find execution flows involving X
+3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
+4. Plan update order: interfaces → implementations → callers → tests
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklists
+
+### Rename Symbol
+
+```
+- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
+- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
+- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
+- [ ] gitnexus_detect_changes() — verify only expected files changed
+- [ ] Run tests for affected processes
+```
+
+### Extract Module
+
+```
+- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
+- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
+- [ ] Define new module interface
+- [ ] Extract code, update imports
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+### Split Function/Service
+
+```
+- [ ] gitnexus_context({name: target}) — understand all callees
+- [ ] Group callees by responsibility
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] Create new functions/services
+- [ ] Update callers
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+## Tools
+
+**gitnexus_rename** — automated multi-file rename:
+
+```
+gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+→ 12 edits across 8 files
+→ 10 graph edits (high confidence), 2 ast_search edits (review)
+→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
+```
+
+**gitnexus_impact** — map all dependents first:
+
+```
+gitnexus_impact({target: "validateUser", direction: "upstream"})
+→ d=1: loginHandler, apiMiddleware, testUtils
+→ Affected Processes: LoginFlow, TokenRefresh
+```
+
+**gitnexus_detect_changes** — verify your changes after refactoring:
+
+```
+gitnexus_detect_changes({scope: "all"})
+→ Changed: 8 files, 12 symbols
+→ Affected processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM
+```
+
+**gitnexus_cypher** — custom reference queries:
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath ORDER BY caller.filePath
+```
+
+## Risk Rules
+
+| Risk Factor         | Mitigation                                |
+| ------------------- | ----------------------------------------- |
+| Many callers (>5)   | Use gitnexus_rename for automated updates |
+| Cross-area refs     | Use detect_changes after to verify scope  |
+| String/dynamic refs | gitnexus_query to find them               |
+| External/public API | Version and deprecate properly            |
+
+## Example: Rename `validateUser` to `authenticateUser`
+
+```
+1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+   → 12 edits: 10 graph (safe), 2 ast_search (review)
+   → Files: validator.ts, login.ts, middleware.ts, config.json...
+
+2. Review ast_search edits (config.json: dynamic reference!)
+
+3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+   → Applied 12 edits across 8 files
+
+4. gitnexus_detect_changes({scope: "all"})
+   → Affected: LoginFlow, TokenRefresh
+   → Risk: MEDIUM — run tests for these flows
+```

.env.production.example

@@ -27,8 +27,9 @@ MINIO_ROOT_PASSWORD=change-minio-password
 
 AUTH_HTTPONLY_REFRESH=true
 
-# Metrics (Prometheus scrapes GET /metrics on api:8000)
+# Metrics (Prometheus scrapes GET /metrics on api:8000 — set a strong bearer token)
 METRICS_ENABLED=true
+METRICS_TOKEN=change-this-metrics-bearer-token
 
 # AI
 OPENROUTER_API_KEY=sk-or-...

AGENTS.md

@@ -0,0 +1,43 @@
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **ielts_web** (7370 symbols, 16808 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/ielts_web/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/ielts_web/clusters` | All functional areas |
+| `gitnexus://repo/ielts_web/processes` | All execution flows |
+| `gitnexus://repo/ielts_web/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

CLAUDE.md

@@ -0,0 +1,43 @@
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **ielts_web** (7370 symbols, 16808 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/ielts_web/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/ielts_web/clusters` | All functional areas |
+| `gitnexus://repo/ielts_web/processes` | All execution flows |
+| `gitnexus://repo/ielts_web/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

backend/.env.example

@@ -9,7 +9,8 @@ SECRET_KEY=change-this-to-64-char-random-string
 ALGORITHM=HS256
 ACCESS_TOKEN_EXPIRE_MINUTES=30
 REFRESH_TOKEN_EXPIRE_DAYS=30
-ADMIN_EMAILS=admin@gmail.com
+# Legacy only. Admin rights should be assigned by updating users.role in the DB/seed process.
+# Use: python -m app.cli.promote_admin --email you@example.com
 
 # ── App ─────────────────────────────────────────────────────────────────────
 APP_NAME=LinguaIELTS API
@@ -34,13 +35,21 @@ STORAGE_BACKEND=local
 # S3_PUBLIC_BASE_URL=/media
 
 METRICS_ENABLED=true
+# Required when METRICS_ENABLED=true and ENVIRONMENT=production
+METRICS_TOKEN=
 
 # Auth cookies (production: refresh httpOnly; dev set false for simpler testing)
 AUTH_HTTPONLY_REFRESH=false
 
 # ── AI ──────────────────────────────────────────────────────────────────────
 OPENROUTER_API_KEY=
+# Extra keys (comma-separated) for rotation when quota/rate-limit hit — scales to 1000+ users
+# OPENROUTER_API_KEYS=sk-or-v1-key2,sk-or-v1-key3
 OPENROUTER_FAST_MODEL=google/gemini-2.0-flash-001
+# Prefer :free models first (default true in production) — no token cost, auto-failover cascade
+# OPENROUTER_PREFER_FREE=true
+# Comma-separated free models (optional — defaults built-in)
+# OPENROUTER_FREE_MODELS=google/gemini-2.0-flash-exp:free,meta-llama/llama-3.3-70b-instruct:free
 
 # ── Observability ───────────────────────────────────────────────────────────
 SENTRY_DSN=
@@ -48,7 +57,7 @@ ENVIRONMENT=development
 # Skip SQLAlchemy create_all on startup when false (production: use Alembic only)
 AUTO_CREATE_TABLES=true
 
-# Email (password reset)
+# Email (password reset + email verification)
 SMTP_HOST=
 SMTP_PORT=587
 SMTP_USER=
@@ -56,3 +65,13 @@ SMTP_PASSWORD=
 SMTP_FROM=
 SMTP_USE_TLS=true
 PASSWORD_RESET_EXPIRE_HOURS=24
+EMAIL_VERIFY_EXPIRE_MINUTES=15
+# Set false to skip email verification requirement (dev only)
+REQUIRE_EMAIL_VERIFICATION=true
+
+# ── Google OAuth ─────────────────────────────────────────────────────────────
+# Get from Google Cloud Console → APIs & Services → Credentials → OAuth 2.0 Client ID
+# Register redirect URI: http://localhost:5173/auth/google/callback
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+GOOGLE_REDIRECT_URI=http://localhost:5173/auth/google/callback

backend/README.md

@@ -17,7 +17,14 @@ python -m pip install -r requirements.txt
 DATABASE_URL=sqlite+aiosqlite:///./linguaielts.db
 ```
 
-3) Run the API (**current directory must be `backend/`** so `import app` works):
+3) Run migrations (recommended even for SQLite):
+
+```bash
+cd backend
+alembic upgrade head
+```
+
+4) Run the API (**current directory must be `backend/`** so `import app` works):
 
 ```bash
 cd backend
@@ -34,13 +41,50 @@ If you ran uvicorn from `DATN/` (parent folder) you get `No module named 'app'`
 
 Open docs at `http://localhost:8000/docs`.
 
-Optional in `backend/.env` for Speaking LLM cards (grammar/vocabulary highlights):
+Optional in `backend/.env` for AI features (Speaking, Writing, Translation, Vocab, Study plan):
 
 ```env
 OPENROUTER_API_KEY=sk-or-v1-...
+# Extra keys — rotated automatically when quota/rate-limit hit (recommended for 1000+ users)
+# OPENROUTER_API_KEYS=sk-or-v1-key2,sk-or-v1-key3
 OPENROUTER_FAST_MODEL=google/gemini-2.0-flash-001
+# Production default: try :free models first (no token cost, auto-failover across 6+ models)
+# OPENROUTER_PREFER_FREE=true
 ```
 
+The shared client (`app/core/openrouter_client.py`) cascades: **free models → paid primary → fallback**, rotates API keys on 402/429, and enables `provider.allow_fallbacks` on OpenRouter.
+
+## Database migrations
+
+Initial migration `20260524_initial_schema` uses **frozen DDL** (not `Base.metadata.create_all`) so fresh databases can run `alembic upgrade head` without duplicate table/column errors from later revisions.
+
+```bash
+cd backend
+alembic upgrade head
+```
+
+## Admin user (one-time)
+
+Admin is **not** auto-assigned by email at login/register. After a user registers, promote deliberately:
+
+```bash
+cd backend
+python -m app.cli.promote_admin --email admin@example.com
+```
+
+Or SQL: `UPDATE users SET role='admin' WHERE email='admin@example.com';`
+
+## Security notes (production)
+
+| Topic | Configuration |
+|-------|----------------|
+| Secrets | `ENVIRONMENT=production` fails startup if `SECRET_KEY`, DB password, S3 keys, or `METRICS_TOKEN` look weak/default. Generate: `openssl rand -hex 32` |
+| OpenAPI | `/docs`, `/redoc`, `/openapi.json` disabled when `ENVIRONMENT=production` |
+| Metrics | `GET /metrics` requires `Authorization: Bearer <METRICS_TOKEN>` in production |
+| Refresh token | Set `AUTH_HTTPONLY_REFRESH=true`; access token kept in memory on frontend (`tokenStore.js`) |
+| History scores | `POST /history/save` is disabled (410) — use skill submit endpoints for server-side scoring |
+| Rate limit | SlowAPI uses `X-Forwarded-For` only when the direct client is a trusted proxy; nginx also rate-limits auth/ML routes |
+
 ## Mock test JSON APIs (used by frontend)
 
 - `GET /mock-tests`
@@ -50,3 +94,5 @@ OPENROUTER_FAST_MODEL=google/gemini-2.0-flash-001
 
 These endpoints read directly from `backend/data` and return the JSON with original field names.
 
+#tạo bản đồ code cho AI 
+gitnexus analyze

backend/alembic/versions/002_password_reset.py

@@ -2,6 +2,7 @@
 
 from alembic import op
 import sqlalchemy as sa
+from sqlalchemy import inspect
 
 revision = "002_password_reset"
 down_revision = "001_add_indexes"
@@ -10,17 +11,25 @@ depends_on = None
 
 
 def upgrade() -> None:
-    op.create_table(
-        "password_reset_tokens",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
-        sa.Column("token_hash", sa.String(255), nullable=False),
-        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("used_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
-    )
-    op.create_index("ix_password_reset_tokens_user_id", "password_reset_tokens", ["user_id"])
-    op.create_index("ix_password_reset_tokens_token_hash", "password_reset_tokens", ["token_hash"], unique=True)
+    bind = op.get_bind()
+    inspector = inspect(bind)
+    if not inspector.has_table("password_reset_tokens"):
+        op.create_table(
+            "password_reset_tokens",
+            sa.Column("id", sa.Integer(), primary_key=True),
+            sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+            sa.Column("token_hash", sa.String(255), nullable=False),
+            sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+            sa.Column("used_at", sa.DateTime(timezone=True), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        )
+        inspector = inspect(bind)
+
+    indexes = {idx["name"] for idx in inspector.get_indexes("password_reset_tokens")}
+    if "ix_password_reset_tokens_user_id" not in indexes:
+        op.create_index("ix_password_reset_tokens_user_id", "password_reset_tokens", ["user_id"])
+    if "ix_password_reset_tokens_token_hash" not in indexes:
+        op.create_index("ix_password_reset_tokens_token_hash", "password_reset_tokens", ["token_hash"], unique=True)
 
 
 def downgrade() -> None:

backend/alembic/versions/003_history_archive.py

@@ -2,6 +2,7 @@
 
 from alembic import op
 import sqlalchemy as sa
+from sqlalchemy import inspect
 
 revision = "003_history_archive"
 down_revision = "002_password_reset"
@@ -10,24 +11,31 @@ depends_on = None
 
 
 def upgrade() -> None:
-    op.create_table(
-        "history_archive",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("user_id", sa.Integer(), nullable=False),
-        sa.Column("quiz_id", sa.String(100), nullable=True),
-        sa.Column("practice_session_id", sa.Integer(), nullable=True),
-        sa.Column("subject", sa.String(100), nullable=True),
-        sa.Column("score", sa.Integer(), nullable=True),
-        sa.Column("total_questions", sa.Integer(), nullable=True),
-        sa.Column("percentage", sa.Float(), nullable=True),
-        sa.Column("band_score", sa.Float(), nullable=True),
-        sa.Column("mode", sa.String(20), nullable=True),
-        sa.Column("duration_seconds", sa.Integer(), nullable=True),
-        sa.Column("answers", sa.JSON(), nullable=True),
-        sa.Column("completed_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("archived_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-    )
-    op.create_index("idx_history_archive_user_date", "history_archive", ["user_id", "completed_at"])
+    bind = op.get_bind()
+    inspector = inspect(bind)
+    if not inspector.has_table("history_archive"):
+        op.create_table(
+            "history_archive",
+            sa.Column("id", sa.Integer(), primary_key=True),
+            sa.Column("user_id", sa.Integer(), nullable=False),
+            sa.Column("quiz_id", sa.String(100), nullable=True),
+            sa.Column("practice_session_id", sa.Integer(), nullable=True),
+            sa.Column("subject", sa.String(100), nullable=True),
+            sa.Column("score", sa.Integer(), nullable=True),
+            sa.Column("total_questions", sa.Integer(), nullable=True),
+            sa.Column("percentage", sa.Float(), nullable=True),
+            sa.Column("band_score", sa.Float(), nullable=True),
+            sa.Column("mode", sa.String(20), nullable=True),
+            sa.Column("duration_seconds", sa.Integer(), nullable=True),
+            sa.Column("answers", sa.JSON(), nullable=True),
+            sa.Column("completed_at", sa.DateTime(timezone=True), nullable=False),
+            sa.Column("archived_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        )
+        inspector = inspect(bind)
+
+    indexes = {idx["name"] for idx in inspector.get_indexes("history_archive")}
+    if "idx_history_archive_user_date" not in indexes:
+        op.create_index("idx_history_archive_user_date", "history_archive", ["user_id", "completed_at"])
 
 
 def downgrade() -> None:

backend/alembic/versions/004_adaptive_notifications.py

@@ -2,6 +2,7 @@
 
 from alembic import op
 import sqlalchemy as sa
+from sqlalchemy import inspect, text
 
 revision = "004_adaptive_notifications"
 down_revision = "003_history_archive"
@@ -10,58 +11,71 @@ depends_on = None
 
 
 def upgrade() -> None:
-    op.add_column(
-        "study_plan_tasks",
-        sa.Column("suggested_difficulty", sa.String(20), nullable=True),
-    )
-    op.add_column(
-        "study_plan_tasks",
-        sa.Column("priority_score", sa.Float(), server_default="0", nullable=False),
-    )
+    bind = op.get_bind()
+    inspector = inspect(bind)
 
-    op.create_table(
-        "skill_adaptive_states",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
-        sa.Column("skill", sa.String(30), nullable=False),
-        sa.Column("srs_ease", sa.Float(), server_default="2.5", nullable=False),
-        sa.Column("srs_interval_days", sa.Integer(), server_default="1", nullable=False),
-        sa.Column("srs_repetitions", sa.Integer(), server_default="0", nullable=False),
-        sa.Column("srs_next_review_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("srs_last_review_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("suggested_difficulty", sa.String(20), server_default="medium", nullable=False),
-        sa.Column("avg_performance", sa.Float(), server_default="0", nullable=False),
-        sa.Column("attempt_count", sa.Integer(), server_default="0", nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.UniqueConstraint("user_id", "skill", name="uq_user_skill_adaptive"),
-    )
-    op.create_index("idx_skill_adaptive_user", "skill_adaptive_states", ["user_id"])
+    # Use raw SQL with IF NOT EXISTS to avoid inspect() issues with async drivers
+    bind.execute(sa.text(
+        "ALTER TABLE study_plan_tasks "
+        "ADD COLUMN IF NOT EXISTS suggested_difficulty VARCHAR(20);"
+    ))
+    bind.execute(sa.text(
+        "ALTER TABLE study_plan_tasks "
+        "ADD COLUMN IF NOT EXISTS priority_score FLOAT NOT NULL DEFAULT 0;"
+    ))
 
-    op.create_table(
-        "notification_settings",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False, unique=True),
-        sa.Column("reminder_enabled", sa.Boolean(), server_default=sa.true(), nullable=False),
-        sa.Column("reminder_time", sa.Time(), nullable=True),
-        sa.Column("channel", sa.String(20), server_default="in_app", nullable=False),
-        sa.Column("email_daily_digest", sa.Boolean(), server_default=sa.false(), nullable=False),
-        sa.Column("push_enabled", sa.Boolean(), server_default=sa.false(), nullable=False),
-        sa.Column("timezone", sa.String(64), server_default="Asia/Ho_Chi_Minh", nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-    )
+    if not inspector.has_table("skill_adaptive_states"):
+        op.create_table(
+            "skill_adaptive_states",
+            sa.Column("id", sa.Integer(), primary_key=True),
+            sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+            sa.Column("skill", sa.String(30), nullable=False),
+            sa.Column("srs_ease", sa.Float(), server_default="2.5", nullable=False),
+            sa.Column("srs_interval_days", sa.Integer(), server_default="1", nullable=False),
+            sa.Column("srs_repetitions", sa.Integer(), server_default="0", nullable=False),
+            sa.Column("srs_next_review_at", sa.DateTime(timezone=True), nullable=True),
+            sa.Column("srs_last_review_at", sa.DateTime(timezone=True), nullable=True),
+            sa.Column("suggested_difficulty", sa.String(20), server_default="medium", nullable=False),
+            sa.Column("avg_performance", sa.Float(), server_default="0", nullable=False),
+            sa.Column("attempt_count", sa.Integer(), server_default="0", nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.UniqueConstraint("user_id", "skill", name="uq_user_skill_adaptive"),
+        )
+        inspector = inspect(bind)
+    indexes = {idx["name"] for idx in inspector.get_indexes("skill_adaptive_states")}
+    if "idx_skill_adaptive_user" not in indexes:
+        op.create_index("idx_skill_adaptive_user", "skill_adaptive_states", ["user_id"])
 
-    op.create_table(
-        "notifications",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
-        sa.Column("type", sa.String(40), nullable=False),
-        sa.Column("title", sa.String(200), nullable=False),
-        sa.Column("body", sa.Text(), nullable=False),
-        sa.Column("link_path", sa.String(200), nullable=True),
-        sa.Column("is_read", sa.Boolean(), server_default=sa.false(), nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-    )
-    op.create_index("idx_notifications_user_read", "notifications", ["user_id", "is_read", "created_at"])
+    if not inspector.has_table("notification_settings"):
+        op.create_table(
+            "notification_settings",
+            sa.Column("id", sa.Integer(), primary_key=True),
+            sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False, unique=True),
+            sa.Column("reminder_enabled", sa.Boolean(), server_default=sa.true(), nullable=False),
+            sa.Column("reminder_time", sa.Time(), nullable=True),
+            sa.Column("channel", sa.String(20), server_default="in_app", nullable=False),
+            sa.Column("email_daily_digest", sa.Boolean(), server_default=sa.false(), nullable=False),
+            sa.Column("push_enabled", sa.Boolean(), server_default=sa.false(), nullable=False),
+            sa.Column("timezone", sa.String(64), server_default="Asia/Ho_Chi_Minh", nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        )
+
+    if not inspector.has_table("notifications"):
+        op.create_table(
+            "notifications",
+            sa.Column("id", sa.Integer(), primary_key=True),
+            sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+            sa.Column("type", sa.String(40), nullable=False),
+            sa.Column("title", sa.String(200), nullable=False),
+            sa.Column("body", sa.Text(), nullable=False),
+            sa.Column("link_path", sa.String(200), nullable=True),
+            sa.Column("is_read", sa.Boolean(), server_default=sa.false(), nullable=False),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        )
+        inspector = inspect(bind)
+    indexes = {idx["name"] for idx in inspector.get_indexes("notifications")}
+    if "idx_notifications_user_read" not in indexes:
+        op.create_index("idx_notifications_user_read", "notifications", ["user_id", "is_read", "created_at"])
 
 
 def downgrade() -> None:

backend/alembic/versions/005_admin_user_columns.py

@@ -0,0 +1,59 @@
+"""Admin: users.role/lock fields and user_profiles leaderboard moderation."""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy import inspect
+
+revision = "005_admin_user_columns"
+down_revision = "004_adaptive_notifications"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    inspector = inspect(op.get_bind())
+
+    user_columns = {col["name"] for col in inspector.get_columns("users")}
+    if "role" not in user_columns:
+        op.add_column(
+            "users",
+            sa.Column("role", sa.String(20), nullable=False, server_default="user"),
+        )
+    if "is_active" not in user_columns:
+        op.add_column(
+            "users",
+            sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.true()),
+        )
+    if "locked_at" not in user_columns:
+        op.add_column("users", sa.Column("locked_at", sa.DateTime(timezone=True)))
+    if "lock_reason" not in user_columns:
+        op.add_column("users", sa.Column("lock_reason", sa.Text()))
+
+    profile_columns = {col["name"] for col in inspector.get_columns("user_profiles")}
+    if "is_leaderboard_hidden" not in profile_columns:
+        op.add_column(
+            "user_profiles",
+            sa.Column(
+                "is_leaderboard_hidden",
+                sa.Boolean(),
+                nullable=False,
+                server_default=sa.false(),
+            ),
+        )
+    if "leaderboard_flag_reason" not in profile_columns:
+        op.add_column("user_profiles", sa.Column("leaderboard_flag_reason", sa.Text()))
+    if "leaderboard_hidden_at" not in profile_columns:
+        op.add_column(
+            "user_profiles",
+            sa.Column("leaderboard_hidden_at", sa.DateTime(timezone=True)),
+        )
+
+
+def downgrade() -> None:
+    op.drop_column("user_profiles", "leaderboard_hidden_at")
+    op.drop_column("user_profiles", "leaderboard_flag_reason")
+    op.drop_column("user_profiles", "is_leaderboard_hidden")
+    op.drop_column("users", "lock_reason")
+    op.drop_column("users", "locked_at")
+    op.drop_column("users", "is_active")
+    op.drop_column("users", "role")

backend/alembic/versions/006_google_oauth_email_verify.py

@@ -0,0 +1,68 @@
+"""Google OAuth columns and email_verifications table.
+
+Revision ID: 006_google_oauth_email_verify
+Revises: 005_admin_user_columns
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy import inspect
+
+revision = "006_google_oauth_email_verify"
+down_revision = "005_admin_user_columns"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    inspector = inspect(op.get_bind())
+    user_columns = {col["name"] for col in inspector.get_columns("users")}
+
+    if "google_id" not in user_columns:
+        op.add_column("users", sa.Column("google_id", sa.String(255), nullable=True))
+        op.create_index("ix_users_google_id", "users", ["google_id"], unique=True)
+
+    if "is_verified" not in user_columns:
+        # Existing users are trusted — mark them verified by default.
+        op.add_column(
+            "users",
+            sa.Column("is_verified", sa.Boolean(), nullable=False, server_default=sa.true()),
+        )
+
+    if "auth_provider" not in user_columns:
+        op.add_column(
+            "users",
+            sa.Column("auth_provider", sa.String(20), nullable=False, server_default="email"),
+        )
+
+    tables = inspector.get_table_names()
+    if "email_verifications" not in tables:
+        op.create_table(
+            "email_verifications",
+            sa.Column("id", sa.Integer(), primary_key=True),
+            sa.Column(
+                "user_id",
+                sa.Integer(),
+                sa.ForeignKey("users.id", ondelete="CASCADE"),
+                nullable=False,
+            ),
+            sa.Column("code_hash", sa.String(64), nullable=False),
+            sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+            sa.Column("used_at", sa.DateTime(timezone=True), nullable=True),
+            sa.Column(
+                "created_at",
+                sa.DateTime(timezone=True),
+                server_default=sa.func.now(),
+            ),
+        )
+        op.create_index(
+            "ix_email_verifications_user_id", "email_verifications", ["user_id"]
+        )
+
+
+def downgrade() -> None:
+    op.drop_table("email_verifications")
+    op.drop_index("ix_users_google_id", table_name="users")
+    op.drop_column("users", "auth_provider")
+    op.drop_column("users", "is_verified")
+    op.drop_column("users", "google_id")

backend/alembic/versions/007_translation_practice.py

@@ -0,0 +1,78 @@
+"""007 – Add translation practice tables
+
+Revision ID: 007
+Revises: 006
+Create Date: 2026-05-30
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy import inspect
+
+revision = "007_translation_practice"
+down_revision = "006_google_oauth_email_verify"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    inspector = inspect(op.get_bind())
+    tables = set(inspector.get_table_names())
+
+    if "translation_steps" not in tables:
+        op.create_table(
+            "translation_steps",
+            sa.Column("id", sa.Integer(), primary_key=True),
+            sa.Column("order", sa.Integer(), nullable=False, server_default="0"),
+            sa.Column("title", sa.String(200), nullable=False),
+            sa.Column("description", sa.Text(), nullable=False, server_default=""),
+            sa.Column("badge_label", sa.String(30), nullable=True),
+            sa.Column("badge_color", sa.String(20), nullable=False, server_default="gray"),
+            sa.Column("icon_emoji", sa.String(10), nullable=False, server_default="📝"),
+        )
+
+    if "translation_topics" not in tables:
+        op.create_table(
+            "translation_topics",
+            sa.Column("id", sa.Integer(), primary_key=True),
+            sa.Column("step_id", sa.Integer(), sa.ForeignKey("translation_steps.id", ondelete="CASCADE"), nullable=False),
+            sa.Column("order", sa.Integer(), nullable=False, server_default="0"),
+            sa.Column("title", sa.String(200), nullable=False),
+            sa.Column("description", sa.Text(), nullable=False, server_default=""),
+        )
+        op.create_index("ix_translation_topics_step_id", "translation_topics", ["step_id"])
+
+    if "translation_sentences" not in tables:
+        op.create_table(
+            "translation_sentences",
+            sa.Column("id", sa.Integer(), primary_key=True),
+            sa.Column("topic_id", sa.Integer(), sa.ForeignKey("translation_topics.id", ondelete="CASCADE"), nullable=False),
+            sa.Column("order", sa.Integer(), nullable=False, server_default="0"),
+            sa.Column("vietnamese", sa.Text(), nullable=False),
+            sa.Column("english", sa.Text(), nullable=False),
+            sa.Column("explanation", sa.Text(), nullable=True),
+        )
+        op.create_index("ix_translation_sentences_topic_id", "translation_sentences", ["topic_id"])
+
+    if "translation_attempts" not in tables:
+        op.create_table(
+            "translation_attempts",
+            sa.Column("id", sa.Integer(), primary_key=True),
+            sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+            sa.Column("sentence_id", sa.Integer(), sa.ForeignKey("translation_sentences.id", ondelete="CASCADE"), nullable=False),
+            sa.Column("user_translation", sa.Text(), nullable=False),
+            sa.Column("score", sa.Float(), nullable=True),
+            sa.Column("feedback", sa.Text(), nullable=True),
+            sa.Column("model_answer", sa.Text(), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        )
+        op.create_index("ix_translation_attempts_user_id", "translation_attempts", ["user_id"])
+        op.create_index("ix_translation_attempts_sentence_id", "translation_attempts", ["sentence_id"])
+
+
+def downgrade() -> None:
+    op.drop_table("translation_attempts")
+    op.drop_table("translation_sentences")
+    op.drop_table("translation_topics")
+    op.drop_table("translation_steps")

backend/alembic/versions/20260524_initial_schema.py

@@ -1,19 +1,18 @@
-"""Initial schema — all tables from SQLAlchemy models.
+"""Initial schema — frozen baseline DDL (no live model import).
 
 Revision ID: 20260524_initial
 Revises:
 Create Date: 2026-05-24
 
+Tables/columns added in later revisions (002–005) are intentionally omitted here
+so `alembic upgrade head` on a fresh database does not duplicate objects.
 """
 
 from typing import Sequence, Union
 
+import sqlalchemy as sa
 from alembic import op
 
-# Import models so Base.metadata is populated
-from app.db import models  # noqa: F401
-from app.db.database import Base
-
 revision: str = "20260524_initial"
 down_revision: Union[str, None] = None
 branch_labels: Union[str, Sequence[str], None] = None
@@ -21,10 +20,400 @@ depends_on: Union[str, Sequence[str], None] = None
 
 
 def upgrade() -> None:
-    bind = op.get_bind()
-    Base.metadata.create_all(bind=bind)
+    op.create_table(
+        "users",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("email", sa.String(255), nullable=False),
+        sa.Column("password_hash", sa.String(255), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index("ix_users_id", "users", ["id"])
+    op.create_index("ix_users_email", "users", ["email"], unique=True)
+
+    op.create_table(
+        "user_profiles",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+            unique=True,
+        ),
+        sa.Column("full_name", sa.String(255)),
+        sa.Column("avatar_url", sa.Text()),
+        sa.Column("phone", sa.String(20)),
+        sa.Column("bio", sa.Text()),
+        sa.Column("target_band", sa.Float(), server_default="7"),
+        sa.Column("exam_date", sa.Date()),
+        sa.Column("streak", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("longest_streak", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("streak_freeze_count", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("last_activity_date", sa.Date()),
+        sa.Column("xp", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("daily_writing_used", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("daily_speaking_used", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("tutor_questions_used_month", sa.Integer(), server_default="0", nullable=False),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index("ix_user_profiles_id", "user_profiles", ["id"])
+
+    op.create_table(
+        "practice_sessions",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("session_type", sa.String(20), nullable=False),
+        sa.Column("quiz_id", sa.String(100)),
+        sa.Column("status", sa.String(20), server_default="started", nullable=False),
+        sa.Column("score", sa.Float()),
+        sa.Column(
+            "started_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column("submitted_at", sa.DateTime(timezone=True)),
+    )
+    op.create_index("ix_practice_sessions_id", "practice_sessions", ["id"])
+    op.create_index("ix_practice_sessions_user_id", "practice_sessions", ["user_id"])
+
+    op.create_table(
+        "history",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("quiz_id", sa.String(100)),
+        sa.Column(
+            "practice_session_id",
+            sa.Integer(),
+            sa.ForeignKey("practice_sessions.id", ondelete="SET NULL"),
+        ),
+        sa.Column("subject", sa.String(100)),
+        sa.Column("score", sa.Integer()),
+        sa.Column("total_questions", sa.Integer()),
+        sa.Column("percentage", sa.Float()),
+        sa.Column("band_score", sa.Float()),
+        sa.Column("mode", sa.String(20)),
+        sa.Column("duration_seconds", sa.Integer()),
+        sa.Column("answers", sa.JSON()),
+        sa.Column(
+            "completed_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index("ix_history_id", "history", ["id"])
+    op.create_index("ix_history_practice_session_id", "history", ["practice_session_id"])
+
+    op.create_table(
+        "progress",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("subject", sa.String(100), nullable=False),
+        sa.Column("total_questions", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("completed_questions", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("percentage", sa.Float(), server_default="0", nullable=False),
+        sa.Column("band_score", sa.Float()),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.UniqueConstraint("user_id", "subject", name="uq_user_subject"),
+    )
+    op.create_index("ix_progress_id", "progress", ["id"])
+
+    op.create_table(
+        "refresh_tokens",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("token_hash", sa.String(255), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("revoked", sa.Boolean(), server_default=sa.false(), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column("revoked_at", sa.DateTime(timezone=True)),
+    )
+    op.create_index("ix_refresh_tokens_id", "refresh_tokens", ["id"])
+    op.create_index("ix_refresh_tokens_user_id", "refresh_tokens", ["user_id"])
+    op.create_index("ix_refresh_tokens_token_hash", "refresh_tokens", ["token_hash"], unique=True)
+
+    op.create_table(
+        "vocab_topics",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("name", sa.String(200), nullable=False),
+        sa.Column("sort_order", sa.Integer(), server_default="0", nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index("ix_vocab_topics_id", "vocab_topics", ["id"])
+    op.create_index("ix_vocab_topics_user_id", "vocab_topics", ["user_id"])
+
+    op.create_table(
+        "vocab_words",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "topic_id",
+            sa.Integer(),
+            sa.ForeignKey("vocab_topics.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("word", sa.String(200), nullable=False),
+        sa.Column("phonetic", sa.String(200)),
+        sa.Column("word_type", sa.String(100)),
+        sa.Column("meaning_en", sa.Text()),
+        sa.Column("meaning_vi", sa.Text()),
+        sa.Column("example", sa.Text()),
+        sa.Column("example_vi", sa.Text()),
+        sa.Column("note", sa.Text()),
+        sa.Column("mastery", sa.String(20), server_default="new", nullable=False),
+        sa.Column("srs_ease", sa.Float(), server_default="2.5", nullable=False),
+        sa.Column("srs_interval_days", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("srs_repetitions", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("srs_next_review_at", sa.DateTime(timezone=True)),
+        sa.Column("srs_last_review_at", sa.DateTime(timezone=True)),
+        sa.Column("source_quiz_id", sa.String(100)),
+        sa.Column("source_type", sa.String(20)),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index("ix_vocab_words_id", "vocab_words", ["id"])
+    op.create_index("ix_vocab_words_topic_id", "vocab_words", ["topic_id"])
+
+    op.create_table(
+        "system_vocab_topics",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("name", sa.String(200), nullable=False),
+        sa.Column("description", sa.Text()),
+        sa.Column("level", sa.String(50)),
+        sa.Column("sort_order", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("is_active", sa.Boolean(), server_default=sa.true(), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index("ix_system_vocab_topics_id", "system_vocab_topics", ["id"])
+    op.create_index("ix_system_vocab_topics_name", "system_vocab_topics", ["name"])
+
+    op.create_table(
+        "system_vocab_words",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "topic_id",
+            sa.Integer(),
+            sa.ForeignKey("system_vocab_topics.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("word", sa.String(200), nullable=False),
+        sa.Column("phonetic", sa.String(200)),
+        sa.Column("word_type", sa.String(100)),
+        sa.Column("meaning_en", sa.Text()),
+        sa.Column("meaning_vi", sa.Text()),
+        sa.Column("example", sa.Text()),
+        sa.Column("example_vi", sa.Text()),
+        sa.Column("tags", sa.JSON()),
+        sa.Column("sort_order", sa.Integer(), server_default="0", nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index("ix_system_vocab_words_id", "system_vocab_words", ["id"])
+    op.create_index("ix_system_vocab_words_topic_id", "system_vocab_words", ["topic_id"])
+
+    op.create_table(
+        "reading_annotations",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("session_id", sa.String(100), nullable=False),
+        sa.Column("quiz_id", sa.String(100)),
+        sa.Column("highlights", sa.JSON()),
+        sa.Column("note", sa.Text()),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index("ix_reading_annotations_id", "reading_annotations", ["id"])
+    op.create_index("ix_reading_annotations_user_id", "reading_annotations", ["user_id"])
+    op.create_index("ix_reading_annotations_session_id", "reading_annotations", ["session_id"])
+    op.create_index("ix_reading_annotations_quiz_id", "reading_annotations", ["quiz_id"])
+
+    op.create_table(
+        "shadowing_videos",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("video_id", sa.String(20), nullable=False),
+        sa.Column("title", sa.String(500), server_default="", nullable=False),
+        sa.Column("level", sa.String(50), server_default="Intermediate", nullable=False),
+        sa.Column("language", sa.String(10), server_default="en", nullable=False),
+        sa.Column("source_url", sa.Text(), server_default="", nullable=False),
+        sa.Column("transcript_source", sa.String(20), server_default="youtube", nullable=False),
+        sa.Column("segments", sa.JSON(), server_default="[]", nullable=False),
+        sa.Column(
+            "created_by",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index("ix_shadowing_videos_id", "shadowing_videos", ["id"])
+    op.create_index("ix_shadowing_videos_video_id", "shadowing_videos", ["video_id"], unique=True)
+
+    op.create_table(
+        "shadowing_user_history",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("video_id", sa.String(20), nullable=False),
+        sa.Column("display_title", sa.String(500)),
+        sa.Column("display_level", sa.String(50)),
+        sa.Column(
+            "last_viewed_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.UniqueConstraint("user_id", "video_id", name="uq_shadowing_user_video"),
+    )
+    op.create_index("ix_shadowing_user_history_id", "shadowing_user_history", ["id"])
+    op.create_index("ix_shadowing_user_history_user_id", "shadowing_user_history", ["user_id"])
+    op.create_index("ix_shadowing_user_history_video_id", "shadowing_user_history", ["video_id"])
+
+    op.create_table(
+        "study_plan_tasks",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("day_number", sa.Integer(), nullable=False),
+        sa.Column("plan_date", sa.Date()),
+        sa.Column("focus_skill", sa.String(50), nullable=False),
+        sa.Column("task_description", sa.Text(), nullable=False),
+        sa.Column("duration_minutes", sa.Integer(), server_default="45", nullable=False),
+        sa.Column("quiz_id", sa.String(100)),
+        sa.Column("route_path", sa.String(200)),
+        sa.Column("is_completed", sa.Boolean(), server_default=sa.false(), nullable=False),
+        sa.Column("completed_at", sa.DateTime(timezone=True)),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index("ix_study_plan_tasks_id", "study_plan_tasks", ["id"])
+    op.create_index("ix_study_plan_tasks_user_id", "study_plan_tasks", ["user_id"])
 
 
 def downgrade() -> None:
-    bind = op.get_bind()
-    Base.metadata.drop_all(bind=bind)
+    op.drop_table("study_plan_tasks")
+    op.drop_table("shadowing_user_history")
+    op.drop_table("shadowing_videos")
+    op.drop_table("reading_annotations")
+    op.drop_table("system_vocab_words")
+    op.drop_table("system_vocab_topics")
+    op.drop_table("vocab_words")
+    op.drop_table("vocab_topics")
+    op.drop_table("refresh_tokens")
+    op.drop_table("progress")
+    op.drop_table("history")
+    op.drop_table("practice_sessions")
+    op.drop_table("user_profiles")
+    op.drop_table("users")

backend/app/cli/__init__.py

@@ -0,0 +1 @@
+"""Management CLI entrypoints."""

backend/app/cli/promote_admin.py

@@ -0,0 +1,55 @@
+"""
+One-shot CLI to grant admin role to an existing user by email.
+
+Usage (from backend/):
+    python -m app.cli.promote_admin --email admin@example.com
+
+Does not auto-promote at login/register — assign admin deliberately via this tool
+or direct SQL: UPDATE users SET role='admin' WHERE email='...';
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+
+from sqlalchemy import select
+
+from app.db.database import AsyncSessionLocal
+from app.db.models import User
+
+logger = logging.getLogger(__name__)
+
+
+async def _promote(email: str) -> int:
+    normalized = email.strip().lower()
+    if not normalized:
+        print("Email is required.", file=sys.stderr)
+        return 1
+
+    async with AsyncSessionLocal() as db:
+        result = await db.execute(select(User).where(User.email == normalized))
+        user = result.scalar_one_or_none()
+        if not user:
+            print(f"No user found with email: {normalized}", file=sys.stderr)
+            return 1
+        if user.role == "admin":
+            print(f"User {normalized} is already admin (id={user.id}).")
+            return 0
+        user.role = "admin"
+        await db.commit()
+        print(f"Promoted user id={user.id} ({normalized}) to admin.")
+        return 0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Promote a user to admin by email.")
+    parser.add_argument("--email", required=True, help="Registered user email")
+    args = parser.parse_args()
+    raise SystemExit(asyncio.run(_promote(args.email)))
+
+
+if __name__ == "__main__":
+    main()

backend/app/core/auth_cookies.py

@@ -94,8 +94,13 @@ def validate_csrf(request: Request) -> None:
     exempt_prefixes = (
         "/auth/login",
         "/auth/register",
+        "/auth/refresh",            # refresh uses httpOnly cookie — no CSRF token needed
+        "/auth/logout",             # logout is safe (revoke-only, no state change risk)
         "/auth/forgot-password",
         "/auth/reset-password",
+        "/auth/google",             # Google OAuth — no session yet when exchanging code
+        "/auth/verify-email",       # OTP verify — public, no session yet
+        "/auth/resend-verification", # OTP resend — public, no session yet
         "/health",
         "/metrics",
         "/docs",

backend/app/core/config.py

@@ -8,9 +8,19 @@ Uses pydantic-settings for type-safe configuration.
 from functools import lru_cache
 from typing import Any
 
-from pydantic import field_validator
+from pydantic import field_validator, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+_WEAK_SECRET_MARKERS = (
+    "change-this",
+    "changeme",
+    "minioadmin",
+    "password",
+    "secret",
+    "example",
+    "yourdomain",
+)
+
 
 class Settings(BaseSettings):
     # ── Application ──────────────────────────────────────────
@@ -36,6 +46,7 @@ class Settings(BaseSettings):
     ALGORITHM: str = "HS256"
     ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
     REFRESH_TOKEN_EXPIRE_DAYS: int = 30
+    # Deprecated — no runtime effect. Use app.cli.promote_admin instead.
     ADMIN_EMAILS: str = ""
     AVATAR_UPLOAD_DIR: str = "uploads/avatars"
 
@@ -51,6 +62,8 @@ class Settings(BaseSettings):
 
     # ── Metrics ────────────────────────────────────────────────
     METRICS_ENABLED: bool = True
+    # Bearer token required for GET /metrics when ENVIRONMENT=production
+    METRICS_TOKEN: str = ""
 
     # ── ML preload ─────────────────────────────────────────────
     ML_PRELOAD_ON_STARTUP: bool | None = None
@@ -76,10 +89,26 @@ class Settings(BaseSettings):
     SMTP_USE_TLS: bool = True
     PASSWORD_RESET_EXPIRE_HOURS: int = 24
 
+    # ── Google OAuth ───────────────────────────────────────────
+    GOOGLE_CLIENT_ID: str = ""
+    GOOGLE_CLIENT_SECRET: str = ""
+    # Registered redirect URI in Google Cloud Console
+    GOOGLE_REDIRECT_URI: str = "http://localhost:5173/auth/google/callback"
+
+    # ── Email verification ─────────────────────────────────────
+    EMAIL_VERIFY_EXPIRE_MINUTES: int = 15
+    REQUIRE_EMAIL_VERIFICATION: bool = True
+
     # ── ML / Speaking pipeline ────────────────────────────────
     OPENROUTER_API_KEY: str = ""
+    # Additional keys (comma-separated) — rotated when one hits quota/rate-limit.
+    OPENROUTER_API_KEYS: str = ""
     # Must be a model slug that exists on OpenRouter (mistral-7b-instruct returns 404).
     OPENROUTER_FAST_MODEL: str = "google/gemini-2.0-flash-001"
+    # Comma-separated free models tried when primary hits quota (see openrouter_client.py).
+    OPENROUTER_FREE_MODELS: str = ""
+    # When True (default in production), try :free models before paid primary.
+    OPENROUTER_PREFER_FREE: bool | None = None
     PRON_MODEL_PATH: str = "model/pron_scorer_best.pt"
     WHISPER_MODEL_SIZE: str = "base"
 
@@ -121,6 +150,36 @@ class Settings(BaseSettings):
             return self.AUTH_HTTPONLY_REFRESH
         return self.ENVIRONMENT == "production"
 
+    @staticmethod
+    def _looks_weak_secret(value: str, *, min_len: int = 32) -> bool:
+        normalized = (value or "").strip().lower()
+        if len(normalized) < min_len:
+            return True
+        return any(marker in normalized for marker in _WEAK_SECRET_MARKERS)
+
+    @model_validator(mode="after")
+    def validate_production_secrets(self) -> "Settings":
+        if self.ENVIRONMENT != "production":
+            return self
+        if self._looks_weak_secret(self.SECRET_KEY):
+            raise ValueError(
+                "SECRET_KEY is missing or uses a weak/default value. "
+                "Generate one with: openssl rand -hex 32"
+            )
+        if self.METRICS_ENABLED and not (self.METRICS_TOKEN or "").strip():
+            raise ValueError(
+                "METRICS_TOKEN is required when METRICS_ENABLED=true in production."
+            )
+        if self.STORAGE_BACKEND.lower() == "s3":
+            if self._looks_weak_secret(self.S3_SECRET_KEY, min_len=16):
+                raise ValueError("S3_SECRET_KEY must be a strong secret in production.")
+            if self._looks_weak_secret(self.S3_ACCESS_KEY, min_len=8):
+                raise ValueError("S3_ACCESS_KEY must not use default credentials in production.")
+        db_url = self.DATABASE_URL.lower()
+        if ":password@" in db_url or ":changeme@" in db_url:
+            raise ValueError("DATABASE_URL must not use default/weak DB passwords in production.")
+        return self
+
 
 @lru_cache()
 def get_settings() -> Settings:
@@ -130,12 +189,3 @@ def get_settings() -> Settings:
 
 # Module-level singleton for convenience imports
 settings = get_settings()
-
-
-def admin_email_set() -> set[str]:
-    """Return lowercase admin bootstrap emails from ADMIN_EMAILS."""
-    return {
-        email.strip().lower()
-        for email in settings.ADMIN_EMAILS.split(",")
-        if email.strip()
-    }

backend/app/core/dependencies.py

@@ -7,7 +7,6 @@ FastAPI dependency functions injected into protected routes.
 from fastapi import Depends, HTTPException, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
-from app.core.config import admin_email_set
 from app.core.security import decode_access_token
 from app.db.database import AsyncSession, get_db
 from app.db.models import User
@@ -46,11 +45,6 @@ async def get_current_user(
     if user is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
 
-    if user.email.lower() in admin_email_set() and user.role != "admin":
-        user.role = "admin"
-        db.add(user)
-        await db.flush()
-
     if not user.is_active:
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Account is locked")
 
@@ -81,10 +75,6 @@ async def get_current_user_optional(
         return None
     result = await db.execute(select(User).where(User.id == int(user_id)))
     user = result.scalar_one_or_none()
-    if user and user.email.lower() in admin_email_set() and user.role != "admin":
-        user.role = "admin"
-        db.add(user)
-        await db.flush()
     if user and not user.is_active:
         return None
     return user

backend/app/core/metrics.py

@@ -4,11 +4,13 @@ from __future__ import annotations
 
 import time
 
+from fastapi import HTTPException, Request
 from prometheus_client import CONTENT_TYPE_LATEST, Counter, Histogram, generate_latest
 from starlette.middleware.base import BaseHTTPMiddleware
-from starlette.requests import Request
 from starlette.responses import Response
 
+from app.core.config import settings
+
 HTTP_REQUESTS = Counter(
     "http_requests_total",
     "Total HTTP requests",
@@ -42,5 +44,18 @@ class PrometheusMiddleware(BaseHTTPMiddleware):
         return response
 
 
-async def metrics_endpoint() -> Response:
+def _authorize_metrics(request: Request) -> None:
+    if settings.ENVIRONMENT != "production":
+        return
+    expected = (settings.METRICS_TOKEN or "").strip()
+    if not expected:
+        raise HTTPException(status_code=503, detail="Metrics endpoint is not configured")
+    auth = request.headers.get("Authorization", "")
+    token = auth[7:].strip() if auth.lower().startswith("bearer ") else ""
+    if token != expected:
+        raise HTTPException(status_code=401, detail="Invalid metrics token")
+
+
+async def metrics_endpoint(request: Request) -> Response:
+    _authorize_metrics(request)
     return Response(content=generate_latest(), media_type=CONTENT_TYPE_LATEST)

backend/app/core/openrouter_client.py

@@ -0,0 +1,253 @@
+"""
+Shared OpenRouter HTTP client — multi-key rotation + free-model cascade.
+
+Designed so many users share AI capacity without exhausting a single key/model:
+  1. OPENROUTER_PREFER_FREE=true → try :free models first (no token cost)
+  2. Multiple keys (OPENROUTER_API_KEY + OPENROUTER_API_KEYS) rotated on 402/429
+  3. Full model cascade per key before moving to the next key
+  4. provider.allow_fallbacks lets OpenRouter route to alternate providers
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import threading
+from typing import Any
+
+import httpx
+
+from app.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
+
+DEFAULT_FREE_MODELS: tuple[str, ...] = (
+    "google/gemini-2.0-flash-exp:free",
+    "meta-llama/llama-3.3-70b-instruct:free",
+    "qwen/qwen-2.5-72b-instruct:free",
+    "deepseek/deepseek-r1-distill-llama-70b:free",
+    "mistralai/mistral-7b-instruct:free",
+    "google/gemma-3-12b-it:free",
+)
+
+_RETRYABLE_STATUS = frozenset({402, 404, 429, 503})
+_FALLBACK_MODEL = "anthropic/claude-3-haiku"
+
+_key_rr = 0
+_key_lock = threading.Lock()
+
+
+def openrouter_keys() -> list[str]:
+    """Primary key + comma-separated extras (deduped)."""
+    out: list[str] = []
+    primary = (settings.OPENROUTER_API_KEY or os.getenv("OPENROUTER_API_KEY", "") or "").strip()
+    if primary:
+        out.append(primary)
+    extra = (getattr(settings, "OPENROUTER_API_KEYS", None) or os.getenv("OPENROUTER_API_KEYS", "") or "").strip()
+    for k in extra.split(","):
+        k = k.strip()
+        if k and k not in out:
+            out.append(k)
+    return out
+
+
+def openrouter_key() -> str:
+    keys = openrouter_keys()
+    return keys[0] if keys else ""
+
+
+def has_openrouter_keys() -> bool:
+    return bool(openrouter_keys())
+
+
+def free_models() -> list[str]:
+    raw = (getattr(settings, "OPENROUTER_FREE_MODELS", None) or "").strip()
+    if raw:
+        return [m.strip() for m in raw.split(",") if m.strip()]
+    return list(DEFAULT_FREE_MODELS)
+
+
+def prefer_free_models() -> bool:
+    val = getattr(settings, "OPENROUTER_PREFER_FREE", None)
+    if val is not None:
+        return bool(val)
+    return settings.ENVIRONMENT == "production"
+
+
+def build_model_cascade(preferred: str | None = None, *, prefer_free: bool | None = None) -> list[str]:
+    """Build deduped model list. Free-first when prefer_free=True (default in production)."""
+    use_free_first = prefer_free_models() if prefer_free is None else prefer_free
+    primary = (
+        (preferred or "").strip()
+        or (settings.OPENROUTER_FAST_MODEL or "").strip()
+        or "google/gemini-2.0-flash-001"
+    )
+    free = free_models()
+    if use_free_first:
+        candidates = (*free, primary, _FALLBACK_MODEL)
+    else:
+        candidates = (primary, *free, _FALLBACK_MODEL)
+    out: list[str] = []
+    for m in candidates:
+        if m and m not in out:
+            out.append(m)
+    return out
+
+
+def _rotate_keys(keys: list[str]) -> list[str]:
+    global _key_rr
+    if len(keys) <= 1:
+        return keys
+    with _key_lock:
+        start = _key_rr % len(keys)
+        _key_rr += 1
+    return keys[start:] + keys[:start]
+
+
+def default_headers(*, title: str = "LinguaIELTS", api_key: str | None = None) -> dict[str, str]:
+    key = (api_key or openrouter_key()).strip()
+    return {
+        "Authorization": f"Bearer {key}",
+        "Content-Type": "application/json",
+        "HTTP-Referer": settings.FRONTEND_ORIGIN or "http://localhost:5173",
+        "X-Title": title,
+    }
+
+
+def _should_try_next_model(exc: httpx.HTTPStatusError) -> bool:
+    if exc.response.status_code in _RETRYABLE_STATUS:
+        return True
+    try:
+        body = exc.response.json()
+        msg = str(body.get("error", {}).get("message", "")).lower()
+        if any(k in msg for k in ("quota", "credit", "rate limit", "insufficient", "no endpoints", "overloaded")):
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def should_retry_model(exc: httpx.HTTPStatusError) -> bool:
+    return _should_try_next_model(exc)
+
+
+def should_try_next_key(exc: httpx.HTTPStatusError) -> bool:
+    """Rotate API key on account-level quota / rate-limit errors."""
+    if exc.response.status_code in {402, 429}:
+        return True
+    return _should_try_next_model(exc)
+
+
+def parse_json_content(raw: str) -> dict[str, Any]:
+    """Extract and parse a JSON object from model output."""
+    text = (raw or "").strip()
+    if not text:
+        raise json.JSONDecodeError("Empty AI response", text, 0)
+
+    if text.startswith("```"):
+        lines = text.split("\n")
+        text = "\n".join(lines[1:-1] if lines[-1].strip() == "```" else lines[1:]).strip()
+
+    try:
+        data = json.loads(text)
+        if isinstance(data, dict):
+            return data
+    except json.JSONDecodeError:
+        pass
+
+    match = re.search(r"\{[\s\S]*\}", text)
+    if match:
+        data = json.loads(match.group(0))
+        if isinstance(data, dict):
+            return data
+
+    raise json.JSONDecodeError("No JSON object in AI response", text, 0)
+
+
+async def chat_completion(
+    messages: list[dict[str, str]],
+    *,
+    model: str | None = None,
+    max_tokens: int = 900,
+    temperature: float = 0.3,
+    timeout: float = 60.0,
+    title: str = "LinguaIELTS",
+    extra_payload: dict[str, Any] | None = None,
+) -> tuple[str, str]:
+    """
+    POST to OpenRouter with key rotation + model cascade.
+
+    Returns (content, model_used).
+    """
+    keys = openrouter_keys()
+    if not keys:
+        raise RuntimeError("OPENROUTER_API_KEY is not configured")
+
+    cascade = build_model_cascade(model)
+    last_exc: Exception | None = None
+
+    for api_key in _rotate_keys(keys):
+        headers = default_headers(title=title, api_key=api_key)
+        key_failed = False
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            for model_id in cascade:
+                payload: dict[str, Any] = {
+                    "model": model_id,
+                    "messages": messages,
+                    "temperature": temperature,
+                    "max_tokens": max_tokens,
+                    "provider": {"allow_fallbacks": True},
+                }
+                if extra_payload:
+                    payload.update(extra_payload)
+                try:
+                    resp = await client.post(OPENROUTER_URL, json=payload, headers=headers)
+                    resp.raise_for_status()
+                    content = resp.json()["choices"][0]["message"]["content"]
+                    logger.debug("OpenRouter OK model=%s key=...%s", model_id, api_key[-6:])
+                    return content, model_id
+                except httpx.HTTPStatusError as exc:
+                    last_exc = exc
+                    if should_try_next_key(exc) and len(keys) > 1:
+                        logger.warning(
+                            "OpenRouter key ...%s exhausted (%s), rotating key",
+                            api_key[-6:],
+                            exc.response.status_code,
+                        )
+                        key_failed = True
+                        break
+                    if _should_try_next_model(exc) and model_id != cascade[-1]:
+                        logger.warning(
+                            "OpenRouter model %s failed (%s), trying next model",
+                            model_id,
+                            exc.response.status_code,
+                        )
+                        continue
+                    raise
+        if not key_failed:
+            break
+
+    raise last_exc or RuntimeError("OpenRouter request failed")
+
+
+async def chat_completion_json(
+    messages: list[dict[str, str]],
+    *,
+    model: str | None = None,
+    max_tokens: int = 900,
+    temperature: float = 0.15,
+    timeout: float = 60.0,
+    title: str = "LinguaIELTS",
+) -> tuple[dict[str, Any], str]:
+    raw, used = await chat_completion(
+        messages,
+        model=model,
+        max_tokens=max_tokens,
+        temperature=temperature,
+        timeout=timeout,
+        title=title,
+    )
+    return parse_json_content(raw), used

backend/app/core/password_policy.py

@@ -0,0 +1,55 @@
+"""Password strength checks shared by register and reset flows."""
+
+from fastapi import HTTPException, status
+
+# Small blocklist — extend as needed; not a substitute for breached-password API.
+_COMMON_PASSWORDS = frozenset(
+    {
+        "password",
+        "password1",
+        "password123",
+        "123456",
+        "12345678",
+        "123456789",
+        "1234567890",
+        "qwerty",
+        "qwerty123",
+        "admin123",
+        "letmein",
+        "welcome",
+        "iloveyou",
+        "monkey",
+        "dragon",
+        "football",
+        "baseball",
+        "abc123",
+        "111111",
+        "000000",
+        "changeme",
+        "secret",
+        "master",
+        "login",
+        "passw0rd",
+        "P@ssw0rd",
+        "P@ssword1",
+    }
+)
+
+
+def assert_password_strength(password: str) -> None:
+    """Raise HTTP 400 when password is too weak or on the common-password list."""
+    if len(password) < 10:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Mật khẩu phải có ít nhất 10 ký tự.",
+        )
+    if password.lower() in _COMMON_PASSWORDS:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Mật khẩu quá phổ biến. Vui lòng chọn mật khẩu khác.",
+        )
+    if password.isdigit():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Mật khẩu không được chỉ gồm chữ số.",
+        )

backend/app/core/rate_limit.py

@@ -1,10 +1,11 @@
-"""Rate limiting (slowapi) — shared limiter and 429 handler."""
+"""Rate limiting (slowapi) shared limiter and 429 handler."""
+
+from ipaddress import ip_address, ip_network
 
 from fastapi import Request
 from fastapi.responses import JSONResponse
 from slowapi import Limiter
 from slowapi.errors import RateLimitExceeded
-from slowapi.util import get_remote_address
 
 from app.core.config import settings
 
@@ -14,8 +15,35 @@ _storage_uri = (
     if settings.ENVIRONMENT == "production" and settings.REDIS_URL
     else None
 )
+
+_TRUSTED_PROXY_NETS = (
+    ip_network("127.0.0.0/8"),
+    ip_network("10.0.0.0/8"),
+    ip_network("172.16.0.0/12"),
+    ip_network("192.168.0.0/16"),
+)
+
+
+def _client_ip(request: Request) -> str:
+    peer = request.client.host if request.client else ""
+    try:
+        peer_ip = ip_address(peer)
+    except ValueError:
+        return peer or "unknown"
+
+    if any(peer_ip in net for net in _TRUSTED_PROXY_NETS):
+        forwarded = request.headers.get("x-forwarded-for", "")
+        first = forwarded.split(",", 1)[0].strip()
+        if first:
+            try:
+                return str(ip_address(first))
+            except ValueError:
+                pass
+    return str(peer_ip)
+
+
 limiter = Limiter(
-    key_func=get_remote_address,
+    key_func=_client_ip,
     storage_uri=_storage_uri,
 )
 
@@ -23,5 +51,5 @@ limiter = Limiter(
 async def rate_limit_exceeded_handler(request: Request, exc: RateLimitExceeded):
     return JSONResponse(
         status_code=429,
-        content={"detail": "Quá nhiều yêu cầu. Vui lòng thử lại sau."},
+        content={"detail": "Qua nhieu yeu cau. Vui long thu lai sau."},
     )

backend/app/core/upload.py

@@ -6,6 +6,9 @@ from fastapi import HTTPException, UploadFile
 
 ALLOWED_IMAGE_TYPES = {"image/jpeg", "image/png", "image/webp"}
 MAX_AVATAR_SIZE = 2 * 1024 * 1024  # 2MB
+MAX_ADMIN_IMAGE_SIZE = 5 * 1024 * 1024  # 5MB
+MAX_AUDIO_UPLOAD_SIZE = 15 * 1024 * 1024  # 15MB
+ALLOWED_AUDIO_EXTENSIONS = {".wav", ".webm", ".m4a", ".mp3", ".ogg"}
 EXTENSION_MAP = {
     "image/jpeg": ".jpg",
     "image/png": ".png",
@@ -13,6 +16,24 @@ EXTENSION_MAP = {
 }
 
 
+async def read_upload_limited(file: UploadFile, max_size: int) -> bytes:
+    """Read an UploadFile without allowing unbounded memory growth."""
+    chunks: list[bytes] = []
+    total = 0
+    while True:
+        chunk = await file.read(1024 * 1024)
+        if not chunk:
+            break
+        total += len(chunk)
+        if total > max_size:
+            raise HTTPException(
+                status_code=413,
+                detail=f"File too large. Maximum size is {max_size // (1024 * 1024)}MB.",
+            )
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
 async def validate_and_read_image(file: UploadFile) -> tuple[bytes, str]:
     """Validate upload. Returns (content_bytes, safe_filename)."""
     if file.content_type not in ALLOWED_IMAGE_TYPES:
@@ -20,7 +41,7 @@ async def validate_and_read_image(file: UploadFile) -> tuple[bytes, str]:
             status_code=400,
             detail=f"Chỉ chấp nhận JPEG, PNG, WebP. Nhận: {file.content_type}",
         )
-    content = await file.read()
+    content = await read_upload_limited(file, MAX_AVATAR_SIZE)
     if len(content) > MAX_AVATAR_SIZE:
         raise HTTPException(
             status_code=400,

backend/app/data/translation_seed.py

@@ -0,0 +1,319 @@
+"""
+Translation Practice seed data.
+Progressive curriculum: Band 5.0 → Band 8.0+
+"""
+from __future__ import annotations
+
+TRANSLATION_SEED: list[dict] = [
+    # ────────────────────────────────────────────────────────────────────────
+    # BƯỚC 1 – Cấu trúc câu cơ bản
+    # ────────────────────────────────────────────────────────────────────────
+    {
+        "title": "Cấu trúc câu cơ bản",
+        "description": "Luyện dịch các câu đơn từ Việt sang Anh. Tập trung vào việc sử dụng đúng thì, mạo từ và cấu trúc câu S-V-O cơ bản.",
+        "badge_label": None,
+        "badge_color": "gray",
+        "icon_emoji": "✏️",
+        "topics": [
+            {
+                "title": "Hiện tại đơn (Simple Present)",
+                "description": "Diễn tả thói quen, sự thật hiển nhiên, lịch trình cố định.",
+                "sentences": [
+                    {"vi": "Tôi học tiếng Anh mỗi ngày.", "en": "I study English every day.", "explain": "Dùng Simple Present với 'every day'. Với 'I' không thêm -s/-es vào động từ."},
+                    {"vi": "Cô ấy dạy toán ở trường tiểu học.", "en": "She teaches Mathematics at a primary school.", "explain": "'She' → thêm -es vào 'teach'. 'Mathematics' viết hoa."},
+                    {"vi": "Họ không thích ăn đồ ăn cay.", "en": "They do not like eating spicy food.", "explain": "Phủ định dùng 'do not' với they/we/I/you."},
+                    {"vi": "Anh ấy thường đi làm bằng xe buýt.", "en": "He usually goes to work by bus.", "explain": "'He' → goes (thêm -es). 'usually' đặt trước động từ chính."},
+                    {"vi": "Chúng tôi sống ở Hà Nội.", "en": "We live in Hanoi.", "explain": "Dùng 'in' cho thành phố, không dùng 'at'."},
+                    {"vi": "Con mèo ngủ trên ghế sofa mỗi buổi chiều.", "en": "The cat sleeps on the sofa every afternoon.", "explain": "Dùng 'the' cho danh từ cụ thể đã biết. 'on' cho bề mặt."},
+                    {"vi": "Em gái tôi chơi đàn piano rất hay.", "en": "My younger sister plays the piano very well.", "explain": "Nhạc cụ dùng với mạo từ 'the'. 'very well' là trạng từ."},
+                    {"vi": "Nhà máy này sản xuất hàng nghìn sản phẩm mỗi năm.", "en": "This factory produces thousands of products every year.", "explain": "'thousands of' = hàng nghìn. 'products' số nhiều."},
+                    {"vi": "Anh ấy không bao giờ uống cà phê vào buổi tối.", "en": "He never drinks coffee in the evening.", "explain": "'never' đặt trước động từ chính. 'in the evening' dùng 'the'."},
+                    {"vi": "Giáo viên luôn giải thích bài học một cách rõ ràng.", "en": "The teacher always explains the lesson clearly.", "explain": "'always' đặt trước động từ chính. 'clearly' = trạng từ."},
+                ],
+            },
+            {
+                "title": "Hiện tại tiếp diễn (Present Continuous)",
+                "description": "Diễn tả hành động đang xảy ra tại thời điểm nói hoặc xu hướng hiện tại.",
+                "sentences": [
+                    {"vi": "Tôi đang học bài cho kỳ thi tuần tới.", "en": "I am studying for next week's exam.", "explain": "am/is/are + V-ing. 'next week's exam' dùng sở hữu cách."},
+                    {"vi": "Cô ấy đang nấu bữa tối trong bếp.", "en": "She is cooking dinner in the kitchen.", "explain": "'is cooking' = đang nấu. 'in the kitchen' dùng 'in'."},
+                    {"vi": "Họ đang xây dựng một tòa nhà mới ở trung tâm thành phố.", "en": "They are building a new building in the city centre.", "explain": "'a new building' dùng mạo từ 'a'. 'city centre' = trung tâm."},
+                    {"vi": "Tại sao em lại khóc vậy?", "en": "Why are you crying?", "explain": "Câu hỏi Present Continuous: Why + are/is/am + S + V-ing?"},
+                    {"vi": "Trời đang mưa rất to.", "en": "It is raining heavily.", "explain": "Thời tiết dùng 'It'. 'heavily' = to, mạnh."},
+                    {"vi": "Công ty chúng tôi đang mở rộng sang thị trường châu Á.", "en": "Our company is expanding into the Asian market.", "explain": "'expand into' = mở rộng sang. 'Asian market' viết hoa."},
+                    {"vi": "Thế giới đang thay đổi rất nhanh nhờ vào công nghệ.", "en": "The world is changing very rapidly due to technology.", "explain": "'due to' = nhờ vào / do. 'rapidly' = nhanh chóng."},
+                    {"vi": "Nhiều ng��ời trẻ đang chọn làm việc từ xa thay vì đến văn phòng.", "en": "Many young people are choosing to work remotely rather than come to the office.", "explain": "'rather than' = thay vì. 'remotely' = từ xa."},
+                ],
+            },
+            {
+                "title": "Hiện tại hoàn thành (Present Perfect)",
+                "description": "Diễn tả hành động đã xảy ra với kết quả còn liên quan đến hiện tại.",
+                "sentences": [
+                    {"vi": "Tôi đã học tiếng Anh được ba năm rồi.", "en": "I have studied English for three years.", "explain": "have/has + V3. 'for + khoảng thời gian'."},
+                    {"vi": "Cô ấy vừa mới hoàn thành luận văn tiến sĩ.", "en": "She has just completed her doctoral thesis.", "explain": "'just' đặt giữa have và V3. 'doctoral thesis' = luận văn TS."},
+                    {"vi": "Họ chưa bao giờ đến thăm Việt Nam.", "en": "They have never visited Vietnam.", "explain": "'never' đặt giữa have và V3 khi dùng Present Perfect."},
+                    {"vi": "Anh ấy đã sống ở nước ngoài kể từ năm 2020.", "en": "He has lived abroad since 2020.", "explain": "'since + mốc thời gian'. 'abroad' = ở nước ngoài."},
+                    {"vi": "Chính phủ đã ban hành nhiều chính sách mới để bảo vệ môi trường.", "en": "The government has issued many new policies to protect the environment.", "explain": "'issue policies' = ban hành chính sách. 'to protect' = để bảo vệ."},
+                    {"vi": "Bao nhiêu lần bạn đã đọc cuốn sách này?", "en": "How many times have you read this book?", "explain": "Câu hỏi PP: How many times + have/has + S + V3?"},
+                    {"vi": "Khoa học đã đạt được nhiều tiến bộ đáng kể trong thập kỷ qua.", "en": "Science has made significant progress in the past decade.", "explain": "'make progress' = đạt tiến bộ. 'past decade' = thập kỷ qua."},
+                    {"vi": "Họ đã hoàn thành dự án trước thời hạn.", "en": "They have completed the project ahead of schedule.", "explain": "'ahead of schedule' = trước thời hạn (cụm cố định)."},
+                ],
+            },
+            {
+                "title": "Quá khứ đơn (Simple Past)",
+                "description": "Diễn tả hành động đã hoàn tất trong quá khứ tại một thời điểm xác định.",
+                "sentences": [
+                    {"vi": "Tôi đã đến Hà Nội vào năm ngoái.", "en": "I went to Hanoi last year.", "explain": "'went' = quá khứ bất quy tắc của 'go'. 'last year' xác định thời điểm."},
+                    {"vi": "Cô ấy đã tốt nghiệp đại học năm 2022.", "en": "She graduated from university in 2022.", "explain": "'graduate from' = tốt nghiệp từ. 'in 2022' = năm cụ thể."},
+                    {"vi": "Chúng tôi đã gặp nhau lần đầu tại một hội nghị quốc tế.", "en": "We met for the first time at an international conference.", "explain": "'met' = quá khứ bất quy tắc của 'meet'. 'for the first time' = lần đầu."},
+                    {"vi": "Anh ấy không đến buổi họp hôm qua vì bị ốm.", "en": "He did not attend the meeting yesterday because he was ill.", "explain": "Phủ định quá khứ: did not + V nguyên thể. 'ill' = bệnh (formal hơn 'sick')."},
+                    {"vi": "Công ty đó được thành lập vào năm 1995.", "en": "That company was founded in 1995.", "explain": "Bị động quá khứ: was/were + V3. 'found → founded'."},
+                    {"vi": "Trận động đất xảy ra vào lúc 3 giờ sáng.", "en": "The earthquake occurred at 3 o'clock in the morning.", "explain": "'occur' = xảy ra (formal). 'at' dùng với giờ cụ thể."},
+                    {"vi": "Chính sách mới được thông qua sau nhiều tháng tranh luận.", "en": "The new policy was passed after months of debate.", "explain": "'pass a policy' = thông qua chính sách. 'months of debate' = nhiều tháng."},
+                    {"vi": "Cô ấy đã cảm thấy rất hồi hộp trước buổi thuyết trình đó.", "en": "She felt very nervous before that presentation.", "explain": "'felt' = quá khứ bất quy tắc của 'feel'. 'nervous' = hồi hộp, lo lắng."},
+                ],
+            },
+            {
+                "title": "Câu bị động (Passive Voice)",
+                "description": "Dùng khi muốn nhấn mạnh đối tượng bị tác động thay vì chủ thể hành động.",
+                "sentences": [
+                    {"vi": "Bức thư này được viết bằng tiếng Pháp.", "en": "This letter is written in French.", "explain": "Bị động hiện tại: is/are + V3. 'in French' = bằng tiếng Pháp."},
+                    {"vi": "Tòa nhà đó đã được xây dựng vào thế kỷ 19.", "en": "That building was constructed in the 19th century.", "explain": "Bị động quá khứ: was/were + V3. '19th century' viết tắt đúng."},
+                    {"vi": "Nhiều cây xanh đang bị chặt phá để xây dựng khu đô thị mới.", "en": "Many trees are being cut down to build new residential areas.", "explain": "Bị động tiếp diễn: are being + V3. 'cut down' = chặt phá."},
+                    {"vi": "Bộ phim này đã được trao giải Oscar.", "en": "This film has been awarded an Oscar.", "explain": "Bị động hoàn thành: has/have been + V3. 'award' = trao."},
+                    {"vi": "Rác thải nhựa cần được xử lý đúng cách để bảo vệ đại dương.", "en": "Plastic waste needs to be disposed of properly to protect the oceans.", "explain": "'dispose of' = xử lý (phrasal verb). 'properly' = đúng cách."},
+                    {"vi": "Thuốc này phải được bảo quản ở nhiệt độ thấp.", "en": "This medicine must be stored at a low temperature.", "explain": "Modal passive: must be + V3. 'stored at' = bảo quản ở."},
+                    {"vi": "Kết quả thi sẽ được công bố vào tuần tới.", "en": "The exam results will be announced next week.", "explain": "Bị động tương lai: will be + V3. 'announce' = công bố."},
+                    {"vi": "Hệ thống giao thông đang được hiện đại hóa ở nhiều thành phố lớn.", "en": "The transportation system is being modernised in many major cities.", "explain": "'modernise' = hiện đại hóa (British spelling). 'major cities' = thành phố lớn."},
+                ],
+            },
+            {
+                "title": "Câu so sánh (Comparison)",
+                "description": "So sánh hơn, so sánh nhất và so sánh bằng — nền tảng cho IELTS Task 1.",
+                "sentences": [
+                    {"vi": "Đọc sách có ích hơn xem tivi.", "en": "Reading books is more beneficial than watching television.", "explain": "'more + adj + than' cho tính từ dài. 'beneficial' = có ích."},
+                    {"vi": "Hà Nội đông dân hơn Đà Nẵng nhiều.", "en": "Hanoi is much more densely populated than Da Nang.", "explain": "'much more' nhấn mạnh mức độ hơn. 'densely populated' = đông dân."},
+                    {"vi": "Học trực tuyến là phương pháp tiện lợi nhất hiện nay.", "en": "Online learning is the most convenient method available today.", "explain": "'the most + adj' = so sánh nhất. 'available' bổ nghĩa cho 'method'."},
+                    {"vi": "Tình trạng ô nhiễm không khí ngày càng nghiêm trọng hơn.", "en": "Air pollution is becoming increasingly serious.", "explain": "'becoming increasingly + adj' = ngày càng. Không cần 'than' ở đây."},
+                    {"vi": "Không có gì quý giá hơn sức khỏe.", "en": "Nothing is more valuable than health.", "explain": "'Nothing is more + adj than' = cấu trúc nhấn mạnh so sánh hơn."},
+                    {"vi": "Phương pháp này đơn giản hơn nhưng kém hiệu quả hơn.", "en": "This method is simpler but less effective.", "explain": "'less + adj' = kém hơn. 'simpler' = tính từ ngắn thêm -er."},
+                    {"vi": "Công nghệ ngày nay tiên tiến hơn nhiều so với hai mươi năm trước.", "en": "Technology today is far more advanced than it was twenty years ago.", "explain": "'far more' nhấn mạnh mức độ. 'than it was' = so với khi đó."},
+                    {"vi": "Kỹ năng mềm quan trọng không kém gì kiến thức chuyên môn.", "en": "Soft skills are just as important as professional knowledge.", "explain": "'just as + adj + as' = so sánh bằng. 'soft skills' = kỹ năng mềm."},
+                ],
+            },
+            {
+                "title": "Mệnh đề quan hệ (Relative Clauses)",
+                "description": "Bổ nghĩa cho danh từ bằng who, which, that, where, whose — rất quan trọng trong IELTS.",
+                "sentences": [
+                    {"vi": "Người phụ nữ mà bạn vừa gặp là giám đốc công ty.", "en": "The woman whom you just met is the director of the company.", "explain": "'whom' = who (formal) cho tân ngữ. 'director of' = giám đốc của."},
+                    {"vi": "Đây là thành phố nơi tôi sinh ra.", "en": "This is the city where I was born.", "explain": "'where' bổ nghĩa cho địa danh. 'was born' = bị động quá khứ."},
+                    {"vi": "Những học sinh đạt điểm cao sẽ nhận học bổng.", "en": "Students who achieve high scores will receive scholarships.", "explain": "'who' bổ nghĩa cho người. 'scholarships' = học bổng (số nhiều)."},
+                    {"vi": "Đây là giải pháp mà các chuyên gia khuyến nghị.", "en": "This is the solution that experts recommend.", "explain": "'that' cho người hoặc vật (informal). 'recommend' = khuyến nghị."},
+                    {"vi": "Lý do tại sao anh ấy từ chối lời mời vẫn còn là bí ẩn.", "en": "The reason why he declined the invitation remains a mystery.", "explain": "'the reason why' = lý do tại sao. 'decline' = từ chối (formal)."},
+                    {"vi": "Cuốn sách mà tôi đang đọc rất thú vị.", "en": "The book that I am reading is very interesting.", "explain": "Mệnh đề quan hệ xác định (defining RC) không có dấu phẩy."},
+                    {"vi": "Nhà khoa học này, người đã phát minh ra vắc-xin, đã đoạt giải Nobel.", "en": "This scientist, who invented the vaccine, was awarded the Nobel Prize.", "explain": "Mệnh đề quan hệ không xác định (non-defining) có dấu phẩy."},
+                    {"vi": "Những quốc gia có nền giáo dục tốt thường có mức sống cao hơn.", "en": "Countries whose education systems are strong tend to have higher living standards.", "explain": "'whose' = có (sở hữu). 'tend to' = có xu hướng."},
+                ],
+            },
+            {
+                "title": "Câu điều kiện (Conditionals)",
+                "description": "If-clauses loại 0, 1, 2, 3 — thiết yếu cho IELTS Writing Task 2.",
+                "sentences": [
+                    {"vi": "Nếu bạn chăm chỉ học, bạn sẽ đạt điểm cao.", "en": "If you study hard, you will achieve high scores.", "explain": "Loại 1: If + present simple, will + V. Khả năng có thể xảy ra."},
+                    {"vi": "Nếu chúng ta không hành động ngay bây giờ, ô nhiễm sẽ trở nên tồi tệ hơn.", "en": "If we do not act now, pollution will become worse.", "explain": "Loại 1. 'act now' = hành động ngay. 'become worse' = trở nên tồi tệ."},
+                    {"vi": "Nếu tôi giàu hơn, tôi sẽ du lịch vòng quanh thế giới.", "en": "If I were richer, I would travel around the world.", "explain": "Loại 2: If + were/V-ed, would + V. Tình huống không có thật ở hiện tại."},
+                    {"vi": "Nếu chính phủ đầu tư nhiều hơn vào giáo dục, chất lượng cuộc sống sẽ được cải thiện.", "en": "If the government invested more in education, the quality of life would improve.", "explain": "Loại 2. 'invest in' = đầu tư vào. 'quality of life' = chất lượng cuộc sống."},
+                    {"vi": "Nếu anh ấy đã học chăm hơn, anh ấy đã không thi trượt.", "en": "If he had studied harder, he would not have failed the exam.", "explain": "Loại 3: If + had V3, would have V3. Hối tiếc về quá khứ."},
+                    {"vi": "Trừ khi chúng ta giảm lượng khí thải carbon, biến đổi khí hậu sẽ tiếp tục leo thang.", "en": "Unless we reduce carbon emissions, climate change will continue to escalate.", "explain": "'Unless' = if not. 'carbon emissions' = khí thải carbon. 'escalate' = leo thang."},
+                    {"vi": "Miễn là bạn có quyết tâm, bạn có thể đạt được bất kỳ mục tiêu nào.", "en": "As long as you have determination, you can achieve any goal.", "explain": "'As long as' = miễn là (điều kiện). 'determination' = quyết tâm."},
+                    {"vi": "Giả sử chính sách này được thực thi, nền kinh tế sẽ phục hồi nhanh hơn.", "en": "Supposing this policy were implemented, the economy would recover more quickly.", "explain": "'Supposing' = giả sử (formal). Loại 2. 'implement' = thực thi."},
+                ],
+            },
+        ],
+    },
+
+    # ────────────────────────────────────────────────────────────────────────
+    # BƯỚC 2 – Collocations & Từ vựng học thuật
+    # ────────────────────────────────────────────────────────────────────────
+    {
+        "title": "Collocations & Từ vựng học thuật",
+        "description": "Dịch các câu sử dụng collocations IELTS phổ biến. Nắm vững các cụm từ này giúp bài thi đạt Band 7+.",
+        "badge_label": "VOCAB",
+        "badge_color": "blue",
+        "icon_emoji": "📚",
+        "topics": [
+            {
+                "title": "Collocations: Giáo dục (Education)",
+                "description": "Các cụm từ thiết yếu về chủ đề Giáo dục cho IELTS.",
+                "sentences": [
+                    {"vi": "Giáo dục đóng vai trò then chốt trong việc xây dựng một xã hội văn minh.", "en": "Education plays a pivotal role in building a civilised society.", "explain": "'play a pivotal role' = đóng vai trò then chốt (collocation mạnh)."},
+                    {"vi": "Nhiều học sinh phải vật lộn với áp lực học tập trong suốt những năm học phổ thông.", "en": "Many students struggle with academic pressure throughout their secondary school years.", "explain": "'struggle with' = vật lộn với. 'academic pressure' = áp lực học tập."},
+                    {"vi": "Tư duy phản biện là kỹ năng thiết yếu mà hệ thống giáo dục cần bồi dưỡng.", "en": "Critical thinking is an essential skill that the education system needs to cultivate.", "explain": "'critical thinking' = tư duy phản biện. 'cultivate' = bồi dưỡng/nuôi dưỡng."},
+                    {"vi": "Việc học ngoại ngữ từ sớm mang lại lợi ích lớn cho sự phát triển nhận thức của trẻ.", "en": "Learning foreign languages from an early age brings significant benefits to children's cognitive development.", "explain": "'cognitive development' = phát triển nhận thức. 'from an early age' = từ sớm."},
+                    {"vi": "Chính sách giáo dục toàn diện cần đáp ứng nhu cầu của tất cả học sinh, kể cả người khuyết tật.", "en": "Inclusive education policies need to address the needs of all students, including those with disabilities.", "explain": "'inclusive education' = giáo dục toàn diện. 'address needs' = đáp ứng nhu cầu."},
+                    {"vi": "Sự chênh lệch về chất lượng giáo dục giữa thành thị và nông thôn cần được thu hẹp.", "en": "The disparity in educational quality between urban and rural areas needs to be narrowed.", "explain": "'disparity' = sự chênh lệch (academic). 'narrowed' = thu hẹp."},
+                    {"vi": "Các trường đại học nên trang bị cho sinh viên những kỹ năng thực tiễn phù hợp với yêu cầu thị trường lao động.", "en": "Universities should equip students with practical skills relevant to the demands of the labour market.", "explain": "'equip with' = trang bị. 'relevant to' = phù hợp với. 'labour market' = thị trường lao động."},
+                    {"vi": "Học tập suốt đời là yếu tố quan trọng để thích nghi với những thay đổi nhanh chóng của xã hội.", "en": "Lifelong learning is an essential factor in adapting to the rapid changes in society.", "explain": "'lifelong learning' = học tập suốt đời. 'adapt to' = thích nghi với."},
+                ],
+            },
+            {
+                "title": "Collocations: Môi trường (Environment)",
+                "description": "Các cụm từ quan trọng về chủ đề Môi trường — chủ đề xuất hiện thường xuyên trong IELTS.",
+                "sentences": [
+                    {"vi": "Biến đổi khí hậu là mối đe dọa nghiêm trọng nhất đối với sự tồn tại của nhân loại.", "en": "Climate change poses the most serious threat to the survival of humanity.", "explain": "'pose a threat' = đặt ra mối đe dọa. 'survival of humanity' = sự tồn tại của nhân loại."},
+                    {"vi": "Nạn phá rừng đang phá hủy các hệ sinh thái quý giá và đẩy nhanh quá trình mất đa dạng sinh học.", "en": "Deforestation is destroying precious ecosystems and accelerating the loss of biodiversity.", "explain": "'deforestation' = nạn phá rừng. 'biodiversity' = đa dạng sinh học. 'accelerate' = đẩy nhanh."},
+                    {"vi": "Năng lượng tái tạo đang dần thay thế nhiên liệu hóa thạch ở nhiều quốc gia.", "en": "Renewable energy is gradually replacing fossil fuels in many countries.", "explain": "'renewable energy' = năng lượng tái tạo. 'fossil fuels' = nhiên liệu hóa thạch."},
+                    {"vi": "Phát triển bền vững đòi hỏi sự cân bằng giữa tăng trưởng kinh tế và bảo tồn thiên nhiên.", "en": "Sustainable development requires a balance between economic growth and the conservation of nature.", "explain": "'sustainable development' = phát triển bền vững. 'conservation' = bảo tồn."},
+                    {"vi": "Các chính phủ cần áp đặt các quy định nghiêm ngặt hơn đối với các ngành công nghiệp gây ô nhiễm.", "en": "Governments need to impose stricter regulations on polluting industries.", "explain": "'impose regulations' = áp đặt quy định. 'stricter' = so sánh hơn của 'strict'."},
+                    {"vi": "Ô nhiễm không khí làm trầm trọng thêm các bệnh về đường hô hấp và làm giảm tuổi thọ.", "en": "Air pollution exacerbates respiratory diseases and reduces life expectancy.", "explain": "'exacerbate' = làm trầm trọng thêm (C2). 'life expectancy' = tuổi thọ."},
+                    {"vi": "Ý thức bảo vệ môi trường của người dân đã được nâng cao đáng kể trong những năm gần đây.", "en": "Public awareness of environmental protection has grown considerably in recent years.", "explain": "'public awareness' = ý thức cộng đồng. 'grow considerably' = tăng đáng kể."},
+                    {"vi": "Việc giảm lượng khí thải carbon dioxide là ưu tiên hàng đầu trong cuộc chiến chống biến đổi khí hậu.", "en": "Reducing carbon dioxide emissions is a top priority in the fight against climate change.", "explain": "'top priority' = ưu tiên hàng đầu. 'in the fight against' = trong cuộc chiến chống lại."},
+                ],
+            },
+            {
+                "title": "Collocations: Công nghệ (Technology)",
+                "description": "Từ vựng và cụm từ về chủ đề Công nghệ — Band 7+ topic.",
+                "sentences": [
+                    {"vi": "Trí tuệ nhân tạo đang biến đổi cơ bản cách chúng ta làm việc và giao tiếp.", "en": "Artificial intelligence is fundamentally transforming the way we work and communicate.", "explain": "'fundamentally transform' = biến đổi cơ bản. 'the way we' = cách chúng ta."},
+                    {"vi": "Sự bùng nổ của mạng xã hội đã có tác động sâu sắc đến hành vi của người tiêu dùng.", "en": "The proliferation of social media has had a profound impact on consumer behaviour.", "explain": "'proliferation' = sự bùng nổ/lan rộng (formal). 'profound impact' = tác động sâu sắc."},
+                    {"vi": "Tự động hóa có thể thay thế nhiều công việc lao động tay chân, dẫn đến thất nghiệp quy mô lớn.", "en": "Automation may replace many manual jobs, leading to large-scale unemployment.", "explain": "'automation' = tự động hóa. 'manual jobs' = công việc chân tay. 'large-scale' = quy mô lớn."},
+                    {"vi": "Khoảng cách số giữa các quốc gia phát triển và đang phát triển ngày càng mở rộng.", "en": "The digital divide between developed and developing nations is widening.", "explain": "'digital divide' = khoảng cách số (cụm quan trọng). 'widening' = đang mở rộng."},
+                    {"vi": "Đổi mới công nghệ phải đi đôi với bảo đảm quyền riêng tư và an ninh dữ liệu.", "en": "Technological innovation must go hand in hand with ensuring data privacy and security.", "explain": "'go hand in hand' = đi đôi với (idiom). 'data privacy' = quyền riêng tư dữ liệu."},
+                    {"vi": "Internet vạn vật đang tạo ra các thành phố thông minh nơi mọi thiết bị đều được kết nối.", "en": "The Internet of Things is creating smart cities where every device is interconnected.", "explain": "'Internet of Things (IoT)' = internet vạn vật. 'interconnected' = kết nối với nhau."},
+                    {"vi": "Công nghệ giáo dục đang mở ra cơ hội học tập cho hàng triệu người ở vùng sâu vùng xa.", "en": "Educational technology is opening up learning opportunities for millions of people in remote areas.", "explain": "'open up opportunities' = mở ra cơ hội. 'remote areas' = vùng sâu vùng xa."},
+                    {"vi": "Phụ thuộc quá mức vào thiết bị kỹ thuật số có thể gây ra những hậu quả tiêu cực về mặt tâm lý.", "en": "Excessive reliance on digital devices can have negative psychological consequences.", "explain": "'excessive reliance on' = phụ thuộc quá mức vào. 'psychological' = thuộc về tâm lý."},
+                ],
+            },
+            {
+                "title": "Collocations: Sức khỏe & Xã hội",
+                "description": "Từ vựng học thuật về sức khỏe cộng đồng và các vấn đề xã hội.",
+                "sentences": [
+                    {"vi": "Béo phì là mối quan tâm sức khỏe cộng đồng ngày càng nghiêm trọng ở nhiều quốc gia.", "en": "Obesity is an increasingly pressing public health concern in many countries.", "explain": "'pressing concern' = mối lo ngại cấp bách. 'public health' = sức khỏe cộng đồng."},
+                    {"vi": "Sức khỏe tâm thần đã được nhìn nhận là một phần không thể tách rời của sức khỏe tổng thể.", "en": "Mental health has been recognised as an integral part of overall well-being.", "explain": "'integral part' = phần không thể tách rời. 'well-being' = sức khỏe tổng thể/hạnh phúc."},
+                    {"vi": "Bất bình đẳng thu nhập ngày càng gia tăng đe dọa nghiêm trọng đến sự gắn kết xã hội.", "en": "Growing income inequality poses a significant threat to social cohesion.", "explain": "'income inequality' = bất bình đẳng thu nhập. 'social cohesion' = sự gắn kết xã hội."},
+                    {"vi": "Đại dịch COVID-19 đã phơi bày những điểm yếu nghiêm trọng trong hệ thống y tế toàn cầu.", "en": "The COVID-19 pandemic exposed serious weaknesses in the global healthcare system.", "explain": "'expose weaknesses' = phơi bày điểm yếu. 'healthcare system' = hệ thống y tế."},
+                    {"vi": "Đô thị hóa nhanh chóng dẫn đến việc hình thành các khu ổ chuột ở vùng ngoại ô của nhiều thành phố.", "en": "Rapid urbanisation leads to the emergence of slums on the outskirts of many cities.", "explain": "'urbanisation' = đô thị hóa. 'slums' = khu ổ chuột. 'outskirts' = ngoại ô."},
+                    {"vi": "Áp lực công việc cường độ cao có thể dẫn đến kiệt sức và các vấn đề sức khỏe nghiêm trọng.", "en": "High-intensity work pressure can lead to burnout and serious health problems.", "explain": "'lead to burnout' = dẫn đến kiệt sức. 'burnout' = tình trạng kiệt sức (thuật ngữ)."},
+                    {"vi": "Trách nhiệm xã hội của doanh nghiệp đã trở thành yếu tố quan trọng trong chiến lược kinh doanh hiện đại.", "en": "Corporate social responsibility has become a crucial factor in modern business strategy.", "explain": "'corporate social responsibility (CSR)' = trách nhiệm xã hội doanh nghiệp."},
+                    {"vi": "Tình nguyện và từ thiện là biểu hiện quan trọng của trách nhiệm công dân và tinh thần cộng đồng.", "en": "Volunteering and philanthropy are vital expressions of civic responsibility and community spirit.", "explain": "'philanthropy' = hoạt động từ thiện. 'civic responsibility' = trách nhiệm công dân."},
+                ],
+            },
+        ],
+    },
+
+    # ────────────────────────────────────────────────────────────────────────
+    # BƯỚC 3 – Dịch đoạn văn Band 6.5
+    # ────────────────────────────────────────────────────────────────────────
+    {
+        "title": "Dịch đoạn văn Band 6.5",
+        "description": "Luyện dịch các đoạn văn ngắn từ Việt sang Anh với mục tiêu đạt độ chính xác và mạch lạc ở mức Band 6.5.",
+        "badge_label": "BAND 6.5",
+        "badge_color": "green",
+        "icon_emoji": "🎯",
+        "topics": [
+            {
+                "title": "Đoạn văn: Vai trò của Giáo dục",
+                "description": "Dịch các đoạn văn bàn về tầm quan trọng của giáo dục.",
+                "sentences": [
+                    {"vi": "Giáo dục là nền tảng của một xã hội thịnh vượng. Đầu tư vào giáo dục không chỉ nâng cao chất lượng nguồn nhân lực mà còn thúc đẩy sự phát triển kinh tế bền vững.", "en": "Education is the foundation of a prosperous society. Investing in education not only improves the quality of the workforce but also promotes sustainable economic development.", "explain": "'not only ... but also ...' = không chỉ ... mà còn. 'workforce' = lực lượng lao động. 'sustainable' = bền vững."},
+                    {"vi": "Khoảng cách về cơ hội học tập giữa học sinh thành thị và nông thôn vẫn là vấn đề đáng lo ngại. Học sinh ở vùng nông thôn thường thiếu tiếp cận với cơ sở hạ tầng giáo dục hiện đại và giáo viên có trình độ chuyên môn cao.", "en": "The gap in educational opportunities between urban and rural students remains a concerning issue. Students in rural areas often lack access to modern educational infrastructure and highly qualified teachers.", "explain": "'lack access to' = thiếu tiếp cận với. 'infrastructure' = cơ sở hạ tầng. 'qualified' = có chuyên môn."},
+                    {"vi": "Trong thế giới ngày càng toàn cầu hóa, khả năng giao tiếp bằng tiếng Anh là lợi thế cạnh tranh quan trọng. Những người thành thạo ngoại ngữ thường có cơ hội nghề nghiệp tốt hơn và thu nhập cao hơn so với những người chỉ biết tiếng mẹ đẻ.", "en": "In an increasingly globalised world, the ability to communicate in English is a significant competitive advantage. Those who are proficient in foreign languages tend to have better career opportunities and higher incomes compared to those who only speak their native language.", "explain": "'proficient in' = thành thạo. 'competitive advantage' = lợi thế cạnh tranh. 'native language' = tiếng mẹ đẻ."},
+                    {"vi": "Một hệ thống giáo dục chất lượng cao cần phải cân bằng giữa việc truyền đạt kiến thức lý thuyết và phát triển kỹ năng thực hành. Chỉ học thuộc lòng mà không hiểu bản chất vấn đề sẽ cản trở khả năng tư duy sáng tạo của học sinh.", "en": "A high-quality education system needs to strike a balance between imparting theoretical knowledge and developing practical skills. Rote memorisation without genuine understanding will hinder students' capacity for creative thinking.", "explain": "'strike a balance' = cân bằng. 'rote memorisation' = học vẹt. 'hinder' = cản trở."},
+                    {"vi": "Nhiều chuyên gia lập luận rằng hệ thống giáo dục truyền thống đang lỗi thời trước sự phát triển nhanh chóng của thị trường lao động. Thay vào đó, các trường học nên ưu tiên phát triển tư duy phản biện, kỹ năng giải quyết vấn đề và khả năng thích nghi.", "en": "Many experts argue that the traditional education system is becoming outdated in the face of the rapidly evolving labour market. Instead, schools should prioritise developing critical thinking, problem-solving skills, and adaptability.", "explain": "'argue that' = lập luận rằng. 'outdated' = lỗi thời. 'adaptability' = khả năng thích nghi."},
+                ],
+            },
+            {
+                "title": "Đoạn văn: Môi trường và Con người",
+                "description": "Dịch các đoạn văn về các vấn đề môi trường — chủ đề Band 6.5 phổ biến.",
+                "sentences": [
+                    {"vi": "Ô nhiễm môi trường đang ngày càng trở thành mối lo ngại toàn cầu. Các hoạt động công nghiệp và giao thông vận tải thải ra lượng lớn khí CO₂, góp phần làm tăng nhiệt độ trái đất và gây ra những biến đổi khí hậu nghiêm trọng.", "en": "Environmental pollution is becoming an increasingly global concern. Industrial activities and transportation emit large amounts of CO₂, contributing to rising global temperatures and causing severe climate changes.", "explain": "'emit' = thải ra. 'contributing to' = góp phần vào. 'severe' = nghiêm trọng."},
+                    {"vi": "Một trong những nguyên nhân chính gây ra ô nhiễm nguồn nước là việc xả thải chất thải công nghiệp chưa qua xử lý ra các con sông và hồ. Điều này không chỉ ảnh hưởng đến hệ sinh thái thủy sinh mà còn đe dọa sức khỏe của cộng đồng dân cư sống xung quanh.", "en": "One of the primary causes of water pollution is the discharge of untreated industrial waste into rivers and lakes. This not only affects aquatic ecosystems but also threatens the health of communities living nearby.", "explain": "'discharge' = xả thải. 'untreated' = chưa qua xử lý. 'aquatic ecosystems' = hệ sinh thái thủy sinh."},
+                    {"vi": "Việc sử dụng năng lượng tái tạo như điện mặt trời và điện gió đang ngày càng trở nên phổ biến hơn nhờ vào chi phí ngày càng giảm và hiệu quả ngày càng tăng. Nhiều quốc gia đang đặt ra các mục tiêu đầy tham vọng để đạt mức phát thải ròng bằng không vào năm 2050.", "en": "The use of renewable energy sources such as solar and wind power is becoming increasingly popular due to falling costs and rising efficiency. Many countries are setting ambitious targets to achieve net-zero emissions by 2050.", "explain": "'net-zero emissions' = phát thải ròng bằng 0. 'ambitious targets' = mục tiêu đầy tham vọng."},
+                    {"vi": "Ý thức bảo vệ môi trường cần được giáo dục từ khi còn nhỏ. Khi trẻ em được dạy về tầm quan trọng của việc tiết kiệm năng lượng, phân loại rác thải và bảo vệ thiên nhiên, chúng sẽ lớn lên với tinh thần trách nhiệm cao hơn đối với hành tinh của mình.", "en": "Environmental awareness needs to be taught from an early age. When children are educated about the importance of saving energy, sorting waste, and protecting nature, they will grow up with a stronger sense of responsibility towards their planet.", "explain": "'environmental awareness' = ý thức bảo vệ MT. 'sense of responsibility' = tinh thần trách nhiệm."},
+                    {"vi": "Nhiều thành phố lớn trên thế giới đang áp dụng mô hình thành phố xanh nhằm giảm lượng khí thải và cải thiện chất lượng cuộc sống của người dân. Các giải pháp như giao thông công cộng bằng điện, không gian xanh và tòa nhà tiết kiệm năng lượng đang được triển khai rộng rãi.", "en": "Many major cities around the world are adopting the green city model to reduce emissions and improve residents' quality of life. Solutions such as electric public transport, green spaces, and energy-efficient buildings are being widely implemented.", "explain": "'adopt a model' = áp dụng mô hình. 'energy-efficient' = tiết kiệm năng lượng. 'implement' = triển khai."},
+                ],
+            },
+            {
+                "title": "Đoạn văn: Công nghệ & Xã hội",
+                "description": "Các đoạn văn thảo luận tác động của công ngh��� đến cuộc sống hiện đại.",
+                "sentences": [
+                    {"vi": "Cuộc cách mạng công nghiệp 4.0 đang thay đổi căn bản mọi lĩnh vực của cuộc sống, từ sản xuất công nghiệp cho đến dịch vụ y tế và giáo dục. Những công nghệ như trí tuệ nhân tạo, blockchain và internet vạn vật đang tái định hình nền kinh tế toàn cầu.", "en": "The Fourth Industrial Revolution is fundamentally changing every aspect of life, from industrial production to healthcare and education services. Technologies such as artificial intelligence, blockchain, and the Internet of Things are reshaping the global economy.", "explain": "'reshape' = tái định hình. 'every aspect of' = mọi lĩnh vực của. 'fundamentally' = căn bản."},
+                    {"vi": "Mặc dù công nghệ mang lại nhiều lợi ích to lớn, nhưng nó cũng tạo ra những thách thức mới. Vấn đề quyền riêng tư dữ liệu và an ninh mạng ngày càng trở nên cấp bách trong bối cảnh ngày càng có nhiều thông tin cá nhân được lưu trữ và xử lý trực tuyến.", "en": "Although technology brings many significant benefits, it also creates new challenges. The issues of data privacy and cybersecurity are becoming increasingly urgent as more personal information is stored and processed online.", "explain": "'Although' nhượng bộ. 'cybersecurity' = an ninh mạng. 'urgent' = cấp bách."},
+                    {"vi": "Sự phát triển của truyền thông xã hội đã tạo ra cả những cơ hội và nguy cơ mới. Một mặt, nó cho phép mọi người kết nối và chia sẻ thông tin nhanh chóng hơn bao giờ hết. Mặt khác, nó cũng là mảnh đất màu mỡ cho việc lan truyền thông tin sai lệch và ngôn từ thù hận.", "en": "The development of social media has created both new opportunities and new risks. On the one hand, it enables people to connect and share information faster than ever before. On the other hand, it has also become a fertile ground for the spread of misinformation and hate speech.", "explain": "'On the one hand ... On the other hand' = Một mặt ... Mặt khác. 'misinformation' = thông tin sai lệch. 'fertile ground' = mảnh đất màu mỡ (ẩn dụ)."},
+                    {"vi": "Làm việc từ xa đã trở nên phổ biến hơn đáng kể kể từ đại dịch COVID-19. Mô hình làm việc linh hoạt này mang lại nhiều lợi ích như tiết kiệm thời gian đi lại và tăng sự cân bằng giữa công việc và cuộc sống, nhưng cũng đặt ra những thách thức trong việc duy trì sự gắn kết nhóm và quản lý năng suất.", "en": "Remote working has become significantly more prevalent since the COVID-19 pandemic. This flexible working model offers several benefits such as saving commuting time and improving work-life balance, but also poses challenges in maintaining team cohesion and managing productivity.", "explain": "'prevalent' = phổ biến. 'work-life balance' = cân bằng công việc-cuộc sống. 'team cohesion' = sự gắn kết nhóm."},
+                    {"vi": "Tự động hóa và trí tuệ nhân tạo đang thay thế ngày càng nhiều công việc lặp đi lặp lại trong nhiều ngành. Điều này đặt ra câu hỏi cấp bách về việc đào tạo lại lực lượng lao động và đảm bảo rằng những lợi ích của tiến bộ công nghệ được phân bổ công bằng trong xã hội.", "en": "Automation and artificial intelligence are replacing an increasing number of repetitive jobs across many industries. This raises an urgent question about retraining the workforce and ensuring that the benefits of technological progress are equitably distributed across society.", "explain": "'retraining' = đào tạo lại. 'equitably distributed' = phân bổ công bằng. 'across society' = trong toàn xã hội."},
+                ],
+            },
+        ],
+    },
+
+    # ────────────────────────────────────────────────────────────────────────
+    # BƯỚC 4 – Dịch đoạn văn Band 8.0
+    # ────────────────────────────────────────────────────────────────────────
+    {
+        "title": "Dịch đoạn văn Band 8.0",
+        "description": "Thử thách dịch các đoạn văn phức tạp, yêu cầu sử dụng từ vựng ít phổ biến và cấu trúc câu linh hoạt của Band 8.0.",
+        "badge_label": "BAND 8.0",
+        "badge_color": "orange",
+        "icon_emoji": "🏆",
+        "topics": [
+            {
+                "title": "Luận điểm nâng cao: Giáo dục & Xã hội",
+                "description": "Dịch các đoạn lập luận phức tạp về giáo dục và xã hội ở mức Band 8.0.",
+                "sentences": [
+                    {"vi": "Có một quan điểm ngày càng phổ biến rằng các phương pháp sư phạm truyền thống, vốn đặt giáo viên làm trung tâm và nhấn mạnh vào việc tiếp thu kiến thức thụ động, đang ngăn cản học sinh phát triển tư duy độc lập và kỹ năng giải quyết vấn đề — những năng lực thiết yếu trong thế kỷ 21.", "en": "There is a growing consensus that traditional pedagogical approaches, which are teacher-centred and emphasise passive knowledge acquisition, are inhibiting students from developing independent thinking and problem-solving abilities — competencies that are indispensable in the twenty-first century.", "explain": "'pedagogical' = thuộc sư phạm. 'inhibiting' = ngăn cản. 'indispensable' = thiết yếu/không thể thiếu (C2)."},
+                    {"vi": "Mặc dù nhiều người lập luận rằng toàn cầu hóa đã thúc đẩy trao đổi văn hóa và hiểu biết lẫn nhau, nhưng không thể phủ nhận rằng nó cũng đã làm xói mòn bản sắc văn hóa địa phương và gia tăng sự phụ thuộc kinh tế của các quốc gia đang phát triển vào các nền kinh tế phát triển.", "en": "While many argue that globalisation has promoted cultural exchange and mutual understanding, it cannot be denied that it has also eroded local cultural identities and increased the economic dependence of developing nations on developed economies.", "explain": "'erode' = xói mòn (hình tượng). 'mutual understanding' = hiểu biết lẫn nhau. 'economic dependence' = phụ thuộc kinh tế."},
+                    {"vi": "Cuộc khủng hoảng khí hậu không đơn thuần là một vấn đề môi trường mà còn là một cuộc khủng hoảng công bằng xã hội sâu sắc. Những cộng đồng dễ bị tổn thương nhất, đặc biệt là ở các nước đang phát triển, phải gánh chịu những hậu quả nặng nề nhất của một vấn đề mà họ chỉ đóng góp rất ít vào nguyên nhân gây ra.", "en": "The climate crisis is not merely an environmental issue but also a profound social justice crisis. The most vulnerable communities, particularly in developing nations, bear the heaviest consequences of a problem to which they have contributed the least.", "explain": "'profound' = sâu sắc. 'bear the consequences' = gánh chịu hậu quả. 'vulnerable' = dễ bị tổn thương."},
+                    {"vi": "Trong khi những tiến bộ trong y học đã kéo dài đáng kể tuổi thọ con người, vẫn còn những câu hỏi đạo đức phức tạp xung quanh việc phân bổ nguồn lực y tế khan hiếm. Câu hỏi liệu có nên ưu tiên các biện pháp điều trị kéo dài sự sống tốn kém hay tập trung vào chăm sóc sức khỏe phòng ngừa chi phí thấp cho đông đảo dân số hơn vẫn còn là chủ đề tranh luận gay gắt.", "en": "While advances in medicine have significantly extended human lifespans, complex ethical questions remain surrounding the allocation of scarce medical resources. Whether priority should be given to expensive life-prolonging treatments or to low-cost preventive healthcare for a larger proportion of the population remains a contentious subject.", "explain": "'scarce resources' = nguồn lực khan hiếm. 'allocation' = phân bổ. 'contentious' = gây tranh cãi (C2)."},
+                    {"vi": "Một số nhà kinh tế học lập luận rằng sự gia tăng của bất bình đẳng kinh tế ở các xã hội hiện đại không phải là một hiện tượng ngẫu nhiên mà là kết quả tất yếu của các chính sách thuế ưu đãi cho vốn hơn lao động, sự suy yếu của công đoàn và việc tự động hóa ưu tiên thay thế lao động giản đơn.", "en": "Some economists argue that the rise of economic inequality in modern societies is not a random phenomenon but rather an inevitable consequence of tax policies favouring capital over labour, the weakening of trade unions, and automation that disproportionately displaces low-skilled workers.", "explain": "'disproportionately' = không cân xứng. 'trade unions' = công đoàn. 'inevitable consequence' = hậu quả tất yếu."},
+                ],
+            },
+            {
+                "title": "Phân tích chuyên sâu: Khoa học & Đổi mới",
+                "description": "Dịch các đoạn văn mang tính học thuật cao về khoa học và công nghệ ở Band 8.0.",
+                "sentences": [
+                    {"vi": "Sự hội tụ của trí tuệ nhân tạo, điện toán lượng tử và công nghệ sinh học đang mở ra những khả năng mà trước đây chỉ tồn tại trong lĩnh vực khoa học viễn tưởng. Tuy nhiên, tốc độ phát triển của những công nghệ này đang vượt xa khả năng của các khung pháp lý hiện hành trong việc giải quyết các rủi ro và tác động đạo đức liên quan.", "en": "The convergence of artificial intelligence, quantum computing, and biotechnology is unlocking possibilities that previously existed only in the realm of science fiction. However, the pace of development of these technologies is far outstripping the capacity of existing regulatory frameworks to address the associated risks and ethical implications.", "explain": "'convergence' = sự hội tụ. 'outstrip' = vượt xa. 'regulatory frameworks' = khung pháp lý."},
+                    {"vi": "Dữ liệu lớn đã trở thành nguồn tài nguyên chiến lược quan trọng nhất của thế kỷ 21, đôi khi được ví như dầu mỏ của kỷ nguyên số. Sức mạnh kinh tế và chính trị ngày càng tập trung vào tay các công ty công nghệ khổng lồ có khả năng thu thập, phân tích và khai thác lượng dữ liệu khổng lồ về hành vi của hàng tỷ người dùng.", "en": "Big data has become the most strategically important resource of the twenty-first century, often likened to the oil of the digital era. Economic and political power is increasingly concentrated in the hands of technology giants with the capacity to collect, analyse, and exploit vast amounts of data about the behaviour of billions of users.", "explain": "'likened to' = được ví như. 'strategically important' = quan trọng về mặt chiến lược. 'exploit' = khai thác."},
+                    {"vi": "Cuộc tranh luận về vai trò của nhà nước trong việc quản lý các nền tảng truyền thông xã hội phản ánh sự căng thẳng cơ bản giữa hai giá trị cốt lõi của xã hội dân chủ: tự do ngôn luận và bảo vệ cộng đồng khỏi nội dung có hại. Không có giải pháp nào hoàn hảo cho sự đánh đổi này, và mọi can thiệp đều kéo theo những rủi ro không lường trước được.", "en": "The debate over the role of the state in regulating social media platforms reflects a fundamental tension between two core values of democratic society: freedom of expression and the protection of communities from harmful content. No perfect solution exists for this trade-off, and every intervention carries unforeseen risks.", "explain": "'trade-off' = sự đánh đổi. 'unforeseen' = không lường trước được. 'fundamental tension' = sự căng thẳng cơ bản."},
+                    {"vi": "Mặc dù cải cách giáo dục thường được coi là chìa khóa giải quyết bất bình đẳng kinh tế, nhưng bằng chứng thực nghiệm cho thấy tác động của giáo dục đến tính di động xã hội bị hạn chế đáng kể bởi các yếu tố cấu trúc rộng hơn như sự tập trung của cải, sự phân tầng địa lý và phân biệt đối xử có hệ thống.", "en": "Although educational reform is often regarded as the key to addressing economic inequality, empirical evidence suggests that education's impact on social mobility is significantly constrained by broader structural factors such as wealth concentration, geographical stratification, and systemic discrimination.", "explain": "'empirical evidence' = bằng chứng thực nghiệm. 'social mobility' = tính di động xã hội. 'systemic' = có hệ thống."},
+                    {"vi": "Khủng hoảng đa dạng sinh học mà hành tinh chúng ta đang phải đối mặt — với tốc độ tuyệt chủng ước tính cao hơn 1.000 lần so với mức nền tự nhiên — là minh chứng bi thảm nhất cho tác động của hoạt động con người đến hệ sinh thái toàn cầu. Mất mát không thể khắc phục này không chỉ là thảm họa sinh thái mà còn đe dọa trực tiếp đến an ninh lương thực, sức khỏe cộng đồng và sự ổn định của khí hậu.", "en": "The biodiversity crisis facing our planet — with extinction rates estimated to be 1,000 times higher than natural background levels — is the most tragic testament to the impact of human activity on global ecosystems. This irreversible loss is not merely an ecological catastrophe but also poses a direct threat to food security, public health, and climate stability.", "explain": "'testament to' = minh chứng cho. 'irreversible' = không thể khắc phục. 'ecological catastrophe' = thảm họa sinh thái."},
+                ],
+            },
+        ],
+    },
+
+    # ────────────────────────────────────────────────────────────────────────
+    # BƯỚC 5 – Dịch Essay hoàn chỉnh (IELTS Task 2 style)
+    # ──────────────────────────────────────────────────────────────��─────────
+    {
+        "title": "Dịch Essay hoàn chỉnh",
+        "description": "Luyện dịch nguyên một đoạn bài Essay từ dàn ý tiếng Việt sang bài viết tiếng Anh học thuật hoàn chỉnh ở mức Band 8.0+.",
+        "badge_label": "PREMIUM",
+        "badge_color": "purple",
+        "icon_emoji": "🎓",
+        "topics": [
+            {
+                "title": "Essay Task 2: Mở bài & Thân bài — Giáo dục",
+                "description": "Dịch từng phần của bài IELTS Task 2 về chủ đề giáo dục.",
+                "sentences": [
+                    {"vi": "Ngày nay, câu hỏi liệu chính phủ có nên chịu trách nhiệm chính trong việc tài trợ cho giáo dục đại học hay chi phí này nên được chuyển sang cho cá nhân sinh viên là một chủ đề gây tranh luận sôi nổi. Mặc dù có lập luận thuyết phục cho cả hai quan điểm, tôi tin rằng một hệ thống lai kết hợp tài trợ công và đóng góp của sinh viên là giải pháp thực tế nhất.", "en": "In today's world, the question of whether governments should bear the primary responsibility for funding higher education, or whether this cost should be shifted to individual students, is a hotly contested topic. While there are compelling arguments on both sides, I believe that a hybrid system combining public funding and student contributions represents the most pragmatic solution.", "explain": "'hotly contested' = gây tranh cãi gay gắt. 'compelling arguments' = lập luận thuyết phục. 'pragmatic' = thực tế, thực dụng."},
+                    {"vi": "Những người ủng hộ giáo dục đại học miễn phí lập luận rằng đây là điều kiện cần thiết để đảm bảo bình đẳng cơ hội trong xã hội. Khi chi phí học phí cao cản trở những sinh viên có tài năng nhưng xuất thân từ các gia đình thu nhập thấp, điều đó không chỉ là bất công với cá nhân mà còn là sự lãng phí tiềm năng nhân lực to lớn của quốc gia.", "en": "Proponents of free higher education argue that it is a prerequisite for ensuring equality of opportunity within society. When high tuition fees deter talented students from low-income backgrounds, this constitutes not only an injustice to the individual but also a significant waste of a nation's human potential.", "explain": "'proponents' = những người ủng hộ. 'prerequisite' = điều kiện tiên quyết. 'deter' = cản trở, làm nản lòng."},
+                    {"vi": "Tuy nhiên, quan điểm cho rằng gánh nặng chi phí giáo dục đại học chỉ nên do người nộp thuế chịu là không hoàn toàn thuyết phục. Những cá nhân có bằng đại học thường thu nhập cao hơn đáng kể so với những người không có bằng, điều đó có nghĩa là họ sẽ đóng góp nhiều hơn vào ngân sách nhà nước thông qua thuế thu nhập. Do đó, có cơ sở hợp lý để yêu cầu những người hưởng lợi trực tiếp nhất đóng góp một phần chi phí.", "en": "However, the view that the cost of higher education should be borne entirely by taxpayers is not entirely convincing. University graduates typically earn significantly more than those without degrees, meaning they will contribute more to public finances through income tax. There is therefore a reasonable basis for requiring those who benefit most directly to contribute towards the cost.", "explain": "'bear the cost' = chịu gánh nặng chi phí. 'taxpayers' = người nộp thuế. 'reasonable basis' = cơ sở hợp lý."},
+                    {"vi": "Từ quan điểm thực tiễn, một mô hình học phí hoãn nợ — trong đó sinh viên chỉ bắt đầu hoàn trả sau khi thu nhập của họ vượt ngưỡng nhất định — có thể giải quyết được cả mối lo ngại về bình đẳng lẫn tính bền vững tài chính. Mô hình này, được áp dụng thành công ở Úc và Vương quốc Anh, đảm bảo rằng gánh nặng tài chính không bao giờ trở nên không thể chịu đựng được đối với bất kỳ cá nhân nào.", "en": "From a practical standpoint, a deferred tuition model — in which students begin repayments only once their income exceeds a certain threshold — can address both concerns of equity and financial sustainability. This model, successfully implemented in Australia and the United Kingdom, ensures that the financial burden never becomes unbearable for any individual.", "explain": "'deferred' = hoãn lại. 'threshold' = ngưỡng. 'equity' = sự công bằng (formal, ≠ equality)."},
+                    {"vi": "Tóm lại, mặc dù giáo dục đại học hoàn toàn miễn phí là một lý tưởng hấp dẫn, nhưng trong bối cảnh nguồn lực công hạn chế, một hệ thống phân chia chi phí công bằng và linh hoạt sẽ phục vụ xã hội tốt hơn. Điều quan trọng nhất là đảm bảo rằng không có sinh viên tài năng nào bị loại ra khỏi giáo dục đại học chỉ vì lý do tài chính.", "en": "In conclusion, while entirely free higher education is an appealing ideal, a fair and flexible cost-sharing system would serve society better given limited public resources. The most important objective is to ensure that no talented student is excluded from higher education purely on financial grounds.", "explain": "'on financial grounds' = vì lý do tài chính. 'appealing ideal' = lý tưởng hấp dẫn. 'cost-sharing' = phân chia chi phí."},
+                ],
+            },
+            {
+                "title": "Essay Task 2: Mở bài & Thân bài — Môi trường",
+                "description": "Dịch từng phần của bài IELTS Task 2 về biến đổi khí hậu và trách nhiệm cá nhân vs. chính phủ.",
+                "sentences": [
+                    {"vi": "Biến đổi khí hậu là thách thức nghiêm trọng nhất mà nhân loại đang phải đối mặt trong thế kỷ này. Trong khi một số người cho rằng chính phủ phải chịu trách nhiệm chính trong việc giải quyết vấn đề này thông qua chính sách và quy định, những người khác lại khẳng định rằng hành động của mỗi cá nhân là yếu tố then chốt để tạo ra sự thay đổi thực sự. Quan điểm của tôi là cả hai đều không thể thiếu và phải hành động song song.", "en": "Climate change is the most formidable challenge facing humanity in this century. While some contend that governments bear the primary responsibility for tackling this issue through policy and regulation, others maintain that individual action is the pivotal factor in bringing about genuine change. My view is that both are indispensable and must act in concert.", "explain": "'formidable' = ghê gớm, đáng sợ. 'contend' = cho rằng, lập luận. 'in concert' = song song, phối hợp."},
+                    {"vi": "Không thể phủ nhận rằng các chính phủ có đòn bẩy chính sách mà không một cá nhân nào có thể sở hữu. Các cơ chế như thuế carbon, quy định về tiêu chuẩn phát thải và đầu tư vào cơ sở hạ tầng năng lượng tái tạo có thể tạo ra thay đổi có hệ thống ở quy mô mà hành vi cá nhân không bao giờ có thể đạt được. Nếu không có sự can thiệp của nhà nước, thị trường sẽ không tự nhiên chuyển hướng sang các giải pháp thân thiện với môi trường.", "en": "It is undeniable that governments possess policy levers that no individual can wield. Mechanisms such as carbon taxes, emission standards regulations, and investment in renewable energy infrastructure can drive systemic change at a scale that individual behaviour can never achieve. Without state intervention, markets will not naturally transition towards environmentally friendly solutions.", "explain": "'levers' = đòn bẩy (ẩn dụ). 'wield' = sử dụng, thi hành. 'systemic change' = thay đổi có hệ thống."},
+                    {"vi": "Đồng thời, hành động tập thể của hàng tỷ cá nhân có sức mạnh biến đổi không thể xem thường. Khi người tiêu dùng thay đổi thói quen — giảm tiêu thụ thịt, chọn phương tiện giao thông xanh, ủng hộ các thương hiệu có trách nhiệm với môi trường — họ gửi tín hiệu thị trường mạnh mẽ và góp phần xây dựng áp lực chính trị để buộc các chính phủ hành động quyết liệt hơn.", "en": "At the same time, the collective action of billions of individuals has a transformative power that cannot be underestimated. When consumers change their habits — reducing meat consumption, choosing green transportation, supporting environmentally responsible brands — they send powerful market signals and contribute to building political pressure that compels governments to take more decisive action.", "explain": "'collective action' = hành động tập thể. 'compel' = buộc phải. 'decisive' = quyết liệt, dứt khoát."},
+                    {"vi": "Điều quan trọng cần nhận ra là trách nhiệm cá nhân và chính sách chính phủ không phải là hai lựa chọn đối lập mà là hai trụ cột bổ trợ cho nhau trong cuộc chiến chống biến đổi khí hậu. Các chính phủ cần tạo ra môi trường chính sách thuận lợi, trong khi cá nhân cần đưa ra những lựa chọn có trách nhiệm hơn trong phạm vi mà chính sách đó cho phép.", "en": "It is crucial to recognise that individual responsibility and government policy are not opposing alternatives but rather two complementary pillars in the fight against climate change. Governments need to create a favourable policy environment, while individuals need to make more responsible choices within the space that such policies enable.", "explain": "'complementary pillars' = các trụ cột bổ trợ. 'favourable policy environment' = môi trường chính sách thuận lợi."},
+                    {"vi": "Để kết luận, cuộc khủng hoảng khí hậu đòi hỏi một phản ứng đồng bộ ở mọi cấp độ của xã hội. Trong khi chính phủ phải dẫn đầu thông qua các chính sách táo bạo và bắt buộc, mỗi cá nhân cũng phải nhận thức được rằng những lựa chọn hàng ngày của mình có hệ quả thực sự đối với thế giới mà các thế hệ tương lai sẽ thừa hưởng.", "en": "To conclude, the climate crisis demands a coordinated response at every level of society. While governments must take the lead through bold and mandatory policies, individuals must also recognise that their everyday choices have genuine consequences for the world that future generations will inherit.", "explain": "'coordinated response' = phản ứng đồng bộ. 'bold and mandatory' = táo bạo và bắt buộc. 'inherit' = thừa hưởng."},
+                ],
+            },
+        ],
+    },
+]

backend/app/db/models.py

@@ -40,6 +40,10 @@ class User(Base):
     locked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     lock_reason: Mapped[str | None] = mapped_column(Text)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    # OAuth / email verification
+    google_id: Mapped[str | None] = mapped_column(String(255), unique=True, nullable=True, index=True)
+    is_verified: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    auth_provider: Mapped[str] = mapped_column(String(20), default="email", nullable=False)
 
     profile:  Mapped["UserProfile"] = relationship("UserProfile", back_populates="user", uselist=False, cascade="all, delete-orphan")
     progress: Mapped[list["Progress"]] = relationship("Progress", back_populates="user", cascade="all, delete-orphan")
@@ -59,6 +63,9 @@ class User(Base):
     shadowing_history: Mapped[list["ShadowingUserHistory"]] = relationship(
         "ShadowingUserHistory", back_populates="user", cascade="all, delete-orphan"
     )
+    email_verifications: Mapped[list["EmailVerification"]] = relationship(
+        "EmailVerification", back_populates="user", cascade="all, delete-orphan"
+    )
     vocab_topics: Mapped[list["VocabTopic"]] = relationship(
         "VocabTopic", back_populates="user", cascade="all, delete-orphan"
     )
@@ -429,3 +436,99 @@ class Notification(Base):
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
 
     user: Mapped["User"] = relationship("User", back_populates="notifications")
+
+
+# ── Translation Practice ──────────────────────────────────────────────────────
+
+class TranslationStep(Base):
+    """Learning step (Bước 1 – Cấu trúc cơ bản, etc.)"""
+    __tablename__ = "translation_steps"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    order: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    title: Mapped[str] = mapped_column(String(200), nullable=False)
+    description: Mapped[str] = mapped_column(Text, nullable=False, default="")
+    badge_label: Mapped[str | None] = mapped_column(String(30))
+    badge_color: Mapped[str] = mapped_column(String(20), default="gray")
+    icon_emoji: Mapped[str] = mapped_column(String(10), default="📝")
+
+    topics: Mapped[list["TranslationTopic"]] = relationship(
+        "TranslationTopic", back_populates="step", cascade="all, delete-orphan",
+        order_by="TranslationTopic.order",
+    )
+
+
+class TranslationTopic(Base):
+    """A sub-topic within a step (e.g., 'Simple Present')"""
+    __tablename__ = "translation_topics"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    step_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("translation_steps.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    order: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    title: Mapped[str] = mapped_column(String(200), nullable=False)
+    description: Mapped[str] = mapped_column(Text, nullable=False, default="")
+
+    step: Mapped["TranslationStep"] = relationship("TranslationStep", back_populates="topics")
+    sentences: Mapped[list["TranslationSentence"]] = relationship(
+        "TranslationSentence", back_populates="topic", cascade="all, delete-orphan",
+        order_by="TranslationSentence.order",
+    )
+
+
+class TranslationSentence(Base):
+    """One Vietnamese sentence with its English model answer."""
+    __tablename__ = "translation_sentences"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    topic_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("translation_topics.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    order: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    vietnamese: Mapped[str] = mapped_column(Text, nullable=False)
+    english: Mapped[str] = mapped_column(Text, nullable=False)
+    explanation: Mapped[str | None] = mapped_column(Text)
+
+    topic: Mapped["TranslationTopic"] = relationship("TranslationTopic", back_populates="sentences")
+    attempts: Mapped[list["TranslationAttempt"]] = relationship(
+        "TranslationAttempt", back_populates="sentence", cascade="all, delete-orphan"
+    )
+
+
+class TranslationAttempt(Base):
+    """User's translation attempt with AI-graded score/feedback."""
+    __tablename__ = "translation_attempts"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    sentence_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("translation_sentences.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    user_translation: Mapped[str] = mapped_column(Text, nullable=False)
+    score: Mapped[float | None] = mapped_column(nullable=True)
+    feedback: Mapped[str | None] = mapped_column(Text)
+    model_answer: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+    sentence: Mapped["TranslationSentence"] = relationship("TranslationSentence", back_populates="attempts")
+
+
+# ── Email Verification ─────────────────────────────────────────────────────────
+
+class EmailVerification(Base):
+    """One-time 6-digit OTP for verifying a user's email address."""
+    __tablename__ = "email_verifications"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    code_hash: Mapped[str] = mapped_column(String(64), nullable=False)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+    user: Mapped["User"] = relationship("User", back_populates="email_verifications")

backend/app/main.py

@@ -42,6 +42,8 @@ from app.routers.vocabulary import router as vocabulary_router, annotations_rout
 from app.routers.leaderboard import router as leaderboard_router
 from app.routers.shadowing import router as shadowing_router
 from app.routers.mock_exams import router as mock_exams_router
+from app.routers.translation import router as translation_router
+from app.routers.pronunciation import router as pronunciation_router
 
 # ── Logging ──────────────────────────────────────────────────────────────────
 logging.basicConfig(
@@ -98,6 +100,19 @@ async def lifespan(app: FastAPI):
         logger.info("Mock data index warmed up (%d mock tests).", count)
     except Exception as exc:
         logger.warning("Mock data index warmup skipped: %s", exc)
+
+    # Seed translation practice data if tables are empty
+    try:
+        from app.db.database import AsyncSessionLocal
+        from app.services.translation_service import TranslationService
+
+        async with AsyncSessionLocal() as seed_db:
+            seeded = await TranslationService(seed_db).seed_if_empty()
+            if seeded:
+                logger.info("Translation practice seed data loaded.")
+    except Exception as exc:
+        logger.warning("Translation seed skipped: %s", exc)
+
     yield
     logger.info("Shutting down — disposing engine …")
     await engine.dispose()
@@ -108,8 +123,9 @@ app = FastAPI(
     title=settings.APP_NAME,
     description="IELTS Learning Platform API",
     version="1.0.0",
-    docs_url="/docs",
-    redoc_url="/redoc",
+    docs_url=None if settings.ENVIRONMENT == "production" else "/docs",
+    redoc_url=None if settings.ENVIRONMENT == "production" else "/redoc",
+    openapi_url=None if settings.ENVIRONMENT == "production" else "/openapi.json",
     lifespan=lifespan,
 )
 
@@ -133,14 +149,31 @@ class SecurityHeadersMiddleware(BaseHTTPMiddleware):
         response.headers["X-Frame-Options"] = "DENY"
         response.headers["X-XSS-Protection"] = "1; mode=block"
         response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
-        if request.url.scheme == "https":
+        if settings.ENVIRONMENT == "production":
+            response.headers["Content-Security-Policy"] = "default-src 'none'; frame-ancestors 'none'"
+        scheme = request.headers.get("x-forwarded-proto", request.url.scheme)
+        if scheme == "https" or settings.ENVIRONMENT == "production":
             response.headers["Strict-Transport-Security"] = (
                 "max-age=31536000; includeSubDomains"
             )
         return response
 
 
+class ProxyHeadersMiddleware(BaseHTTPMiddleware):
+    """Trust X-Forwarded-* from reverse proxy for scheme/client IP."""
+
+    async def dispatch(self, request, call_next):
+        forwarded_proto = request.headers.get("x-forwarded-proto")
+        if forwarded_proto:
+            request.scope["scheme"] = forwarded_proto.split(",", 1)[0].strip()
+        forwarded_host = request.headers.get("x-forwarded-host")
+        if forwarded_host:
+            request.scope["server"] = (forwarded_host.split(",", 1)[0].strip(), 443)
+        return await call_next(request)
+
+
 app.add_middleware(SecurityHeadersMiddleware)
+app.add_middleware(ProxyHeadersMiddleware)
 app.add_middleware(CsrfMiddleware)
 
 if settings.METRICS_ENABLED:
@@ -162,6 +195,11 @@ uploads_dir.mkdir(parents=True, exist_ok=True)
 if settings.STORAGE_BACKEND.lower() != "s3":
     app.mount("/uploads", StaticFiles(directory=str(uploads_dir)), name="uploads")
 
+# Serve locally-stored quiz images (UUID-named PNGs from data/assets/images)
+_data_images_dir = Path("data/assets/images")
+if _data_images_dir.exists():
+    app.mount("/data-assets/images", StaticFiles(directory=str(_data_images_dir)), name="data_images")
+
 # ── Routers ───────────────────────────────────────────────────────────────────
 app.include_router(auth.router)
 app.include_router(history.router)
@@ -176,6 +214,8 @@ app.include_router(leaderboard_router)
 app.include_router(shadowing_router)
 app.include_router(admin.router)
 app.include_router(mock_exams_router)
+app.include_router(translation_router)
+app.include_router(pronunciation_router)
 
 if settings.METRICS_ENABLED:
     from app.core.metrics import metrics_endpoint

backend/app/repositories/email_verification_repository.py

@@ -0,0 +1,53 @@
+"""
+app/repositories/email_verification_repository.py
+──────────────────────────────────────────────────
+CRUD for email OTP verification tokens.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import EmailVerification
+
+
+class EmailVerificationRepository:
+    def __init__(self, db: AsyncSession) -> None:
+        self._db = db
+
+    async def create(self, user_id: int, code_hash: str, expires_at: datetime) -> EmailVerification:
+        row = EmailVerification(user_id=user_id, code_hash=code_hash, expires_at=expires_at)
+        self._db.add(row)
+        await self._db.flush()
+        await self._db.refresh(row)
+        return row
+
+    async def get_latest_unused(self, user_id: int) -> EmailVerification | None:
+        """Return the most recent unused (not expired, not used) OTP for a user."""
+        now = datetime.now(timezone.utc)
+        result = await self._db.execute(
+            select(EmailVerification)
+            .where(
+                EmailVerification.user_id == user_id,
+                EmailVerification.used_at.is_(None),
+                EmailVerification.expires_at > now,
+            )
+            .order_by(EmailVerification.created_at.desc())
+            .limit(1)
+        )
+        return result.scalar_one_or_none()
+
+    async def mark_used(self, row: EmailVerification) -> None:
+        row.used_at = datetime.now(timezone.utc)
+        self._db.add(row)
+        await self._db.flush()
+
+    async def invalidate_all_for_user(self, user_id: int) -> None:
+        """Expire all existing OTPs for a user before issuing a new one."""
+        await self._db.execute(
+            delete(EmailVerification).where(EmailVerification.user_id == user_id)
+        )
+        await self._db.flush()

backend/app/repositories/profile_repository.py

@@ -25,8 +25,13 @@ class ProfileRepository:
         result = await self._db.execute(select(UserProfile).where(UserProfile.user_id == user_id))
         return result.scalar_one_or_none()
 
-    async def create_empty(self, user_id: int, full_name: str | None = None) -> UserProfile:
-        profile = UserProfile(user_id=user_id, full_name=full_name)
+    async def create_empty(
+        self,
+        user_id: int,
+        full_name: str | None = None,
+        avatar_url: str | None = None,
+    ) -> UserProfile:
+        profile = UserProfile(user_id=user_id, full_name=full_name, avatar_url=avatar_url)
         self._db.add(profile)
         await self._db.flush()
         await self._db.refresh(profile)

backend/app/repositories/translation_repository.py

@@ -0,0 +1,189 @@
+"""
+Translation Practice repository — pure data access layer.
+"""
+from __future__ import annotations
+
+from sqlalchemy import select, func
+from sqlalchemy.orm import selectinload
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import (
+    TranslationStep,
+    TranslationTopic,
+    TranslationSentence,
+    TranslationAttempt,
+)
+
+
+class TranslationRepository:
+    def __init__(self, db: AsyncSession) -> None:
+        self._db = db
+
+    # ── Steps ────────────────────────────────────────────────────────────────
+
+    async def list_steps(self) -> list[TranslationStep]:
+        result = await self._db.execute(
+            select(TranslationStep).order_by(TranslationStep.order)
+        )
+        return list(result.scalars().all())
+
+    async def get_step(self, step_id: int) -> TranslationStep | None:
+        result = await self._db.execute(
+            select(TranslationStep)
+            .where(TranslationStep.id == step_id)
+            .options(selectinload(TranslationStep.topics))
+        )
+        return result.scalar_one_or_none()
+
+    async def count_steps(self) -> int:
+        result = await self._db.execute(select(func.count()).select_from(TranslationStep))
+        return result.scalar_one()
+
+    # ── Topics ───────────────────────────────────────────────────────────────
+
+    async def list_topics_for_step(self, step_id: int) -> list[TranslationTopic]:
+        result = await self._db.execute(
+            select(TranslationTopic)
+            .where(TranslationTopic.step_id == step_id)
+            .order_by(TranslationTopic.order)
+        )
+        return list(result.scalars().all())
+
+    async def get_topic(self, topic_id: int) -> TranslationTopic | None:
+        result = await self._db.execute(
+            select(TranslationTopic).where(TranslationTopic.id == topic_id)
+        )
+        return result.scalar_one_or_none()
+
+    async def count_sentences_in_topic(self, topic_id: int) -> int:
+        result = await self._db.execute(
+            select(func.count())
+            .select_from(TranslationSentence)
+            .where(TranslationSentence.topic_id == topic_id)
+        )
+        return result.scalar_one()
+
+    # ── Sentences ────────────────────────────────────────────────────────────
+
+    async def list_sentences_for_topic(self, topic_id: int) -> list[TranslationSentence]:
+        result = await self._db.execute(
+            select(TranslationSentence)
+            .where(TranslationSentence.topic_id == topic_id)
+            .order_by(TranslationSentence.order)
+        )
+        return list(result.scalars().all())
+
+    async def get_sentence(self, sentence_id: int) -> TranslationSentence | None:
+        result = await self._db.execute(
+            select(TranslationSentence).where(TranslationSentence.id == sentence_id)
+        )
+        return result.scalar_one_or_none()
+
+    # ── Attempts ─────────────────────────────────────────────────────────────
+
+    async def create_attempt(
+        self,
+        user_id: int,
+        sentence_id: int,
+        user_translation: str,
+        score: float | None,
+        feedback: str | None,
+        model_answer: str | None,
+    ) -> TranslationAttempt:
+        attempt = TranslationAttempt(
+            user_id=user_id,
+            sentence_id=sentence_id,
+            user_translation=user_translation,
+            score=score,
+            feedback=feedback,
+            model_answer=model_answer,
+        )
+        self._db.add(attempt)
+        await self._db.flush()
+        await self._db.refresh(attempt)
+        return attempt
+
+    async def get_user_attempt_for_sentence(
+        self, user_id: int, sentence_id: int
+    ) -> TranslationAttempt | None:
+        """Return the latest attempt for a (user, sentence) pair."""
+        result = await self._db.execute(
+            select(TranslationAttempt)
+            .where(
+                TranslationAttempt.user_id == user_id,
+                TranslationAttempt.sentence_id == sentence_id,
+            )
+            .order_by(TranslationAttempt.created_at.desc())
+            .limit(1)
+        )
+        return result.scalar_one_or_none()
+
+    async def count_completed_sentences(self, user_id: int, topic_id: int) -> int:
+        """How many distinct sentences in this topic the user has attempted."""
+        subq = (
+            select(TranslationSentence.id)
+            .where(TranslationSentence.topic_id == topic_id)
+            .scalar_subquery()
+        )
+        result = await self._db.execute(
+            select(func.count(func.distinct(TranslationAttempt.sentence_id)))
+            .where(
+                TranslationAttempt.user_id == user_id,
+                TranslationAttempt.sentence_id.in_(subq),
+            )
+        )
+        return result.scalar_one()
+
+    # ── Seed helpers ─────────────────────────────────────────────────────────
+
+    async def create_step(
+        self,
+        order: int,
+        title: str,
+        description: str,
+        badge_label: str | None,
+        badge_color: str,
+        icon_emoji: str,
+    ) -> TranslationStep:
+        step = TranslationStep(
+            order=order,
+            title=title,
+            description=description,
+            badge_label=badge_label,
+            badge_color=badge_color,
+            icon_emoji=icon_emoji,
+        )
+        self._db.add(step)
+        await self._db.flush()
+        await self._db.refresh(step)
+        return step
+
+    async def create_topic(
+        self, step_id: int, order: int, title: str, description: str
+    ) -> TranslationTopic:
+        topic = TranslationTopic(
+            step_id=step_id, order=order, title=title, description=description
+        )
+        self._db.add(topic)
+        await self._db.flush()
+        await self._db.refresh(topic)
+        return topic
+
+    async def create_sentence(
+        self,
+        topic_id: int,
+        order: int,
+        vietnamese: str,
+        english: str,
+        explanation: str | None,
+    ) -> TranslationSentence:
+        sentence = TranslationSentence(
+            topic_id=topic_id,
+            order=order,
+            vietnamese=vietnamese,
+            english=english,
+            explanation=explanation,
+        )
+        self._db.add(sentence)
+        await self._db.flush()
+        return sentence

backend/app/repositories/user_repository.py

@@ -16,20 +16,50 @@ class UserRepository:
         self._db = db
 
     async def get_by_id(self, user_id: int) -> User | None:
-        """Fetch a user by primary key."""
         result = await self._db.execute(select(User).where(User.id == user_id))
         return result.scalar_one_or_none()
 
     async def get_by_email(self, email: str) -> User | None:
-        """Fetch a user by email address (case-sensitive)."""
         result = await self._db.execute(select(User).where(User.email == email))
         return result.scalar_one_or_none()
 
-    async def create(self, email: str, password_hash: str, role: str = "user") -> User:
-        """Insert a new user row and return the persisted object."""
-        user = User(email=email, password_hash=password_hash, role=role)
+    async def get_by_google_id(self, google_id: str) -> User | None:
+        result = await self._db.execute(select(User).where(User.google_id == google_id))
+        return result.scalar_one_or_none()
+
+    async def create(
+        self,
+        email: str,
+        password_hash: str,
+        role: str = "user",
+        google_id: str | None = None,
+        is_verified: bool = False,
+        auth_provider: str = "email",
+    ) -> User:
+        user = User(
+            email=email,
+            password_hash=password_hash,
+            role=role,
+            google_id=google_id,
+            is_verified=is_verified,
+            auth_provider=auth_provider,
+        )
+        self._db.add(user)
+        await self._db.flush()
+        await self._db.refresh(user)
+        return user
+
+    async def mark_verified(self, user: User) -> User:
+        user.is_verified = True
         self._db.add(user)
-        await self._db.flush()   # get auto-assigned id without committing
+        await self._db.flush()
+        await self._db.refresh(user)
+        return user
+
+    async def update_google_id(self, user: User, google_id: str) -> User:
+        user.google_id = google_id
+        self._db.add(user)
+        await self._db.flush()
         await self._db.refresh(user)
         return user
 

backend/app/routers/auth.py

@@ -1,8 +1,8 @@
 """
 app/routers/auth.py
 ────────────────────
-Auth endpoints: register and login.
-No JWT required — these are public routes.
+Auth endpoints: register, login, refresh, logout,
+email verification, Google OAuth.
 """
 
 from fastapi import APIRouter, Depends, Request, status
@@ -20,7 +20,10 @@ from app.schemas import (
     AuthLogoutRequest,
     AuthRefreshRequest,
     ForgotPasswordRequest,
+    GoogleAuthRequest,
     MessageResponse,
+    RegisterResponse,
+    ResendVerificationRequest,
     ResetPasswordRequest,
     Token,
     UserCreate,
@@ -34,18 +37,64 @@ router = APIRouter(prefix="/auth", tags=["Authentication"])
 
 @router.post(
     "/register",
-    response_model=Token,
+    response_model=RegisterResponse,
     status_code=status.HTTP_201_CREATED,
-    summary="Register a new user",
+    summary="Register a new user (requires email verification)",
 )
 @limiter.limit("5/minute")
 async def register(
     request: Request,
     payload: UserCreate,
     db: AsyncSession = Depends(get_db),
+) -> RegisterResponse:
+    service = AuthService(db)
+    return await service.register(payload)
+
+
+@router.post(
+    "/verify-email",
+    response_model=Token,
+    summary="Verify email OTP and receive a token pair",
+)
+@limiter.limit("10/minute")
+async def verify_email(
+    request: Request,
+    payload: VerifyEmailRequest,
+    db: AsyncSession = Depends(get_db),
+) -> JSONResponse:
+    service = AuthService(db)
+    token = await service.verify_email_otp(payload)
+    return attach_auth_cookies(token)
+
+
+@router.post(
+    "/resend-verification",
+    response_model=MessageResponse,
+    summary="Re-send the email verification OTP",
+)
+@limiter.limit("3/minute")
+async def resend_verification(
+    request: Request,
+    payload: ResendVerificationRequest,
+    db: AsyncSession = Depends(get_db),
+) -> MessageResponse:
+    service = AuthService(db)
+    return await service.resend_verification(payload)
+
+
+@router.post(
+    "/google",
+    response_model=Token,
+    summary="Exchange Google authorization code for a token pair",
+)
+@limiter.limit("10/minute")
+async def google_auth(
+    request: Request,
+    payload: GoogleAuthRequest,
+    db: AsyncSession = Depends(get_db),
 ) -> JSONResponse:
     service = AuthService(db)
-    token = await service.register(payload)
+    token = await service.google_auth(payload)
     return attach_auth_cookies(token)
 
 
@@ -80,7 +129,6 @@ async def refresh(
     refresh_token = read_refresh_token(request, body_token)
     if not refresh_token:
         from fastapi import HTTPException
-
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing refresh token")
     service = AuthService(db)
     token = await service.refresh(refresh_token)
@@ -107,15 +155,6 @@ async def logout(
     return response
 
 
-@router.post(
-    "/verify-email",
-    response_model=MessageResponse,
-    summary="Verify email token (mock in local dev)",
-)
-async def verify_email(_: VerifyEmailRequest) -> MessageResponse:
-    return MessageResponse(message="Email verified (mock)")
-
-
 @router.post(
     "/forgot-password",
     response_model=MessageResponse,

backend/app/routers/history.py

@@ -5,7 +5,7 @@ History endpoints: list practice attempts (paginated) and save new results.
 All routes require a valid JWT bearer token.
 """
 
-from fastapi import APIRouter, Depends, Query, Request, status
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.dependencies import get_current_user
@@ -59,8 +59,13 @@ async def save_history(
 
     This is the key integration endpoint called after every learning session.
     """
-    service = HistoryService(db)
-    return await service.save_practice_result(current_user, payload)
+    raise HTTPException(
+        status_code=status.HTTP_410_GONE,
+        detail=(
+            "Direct history submission is disabled. Use the skill-specific submit "
+            "endpoints so scores, bands, XP, and progress are computed server-side."
+        ),
+    )
 
 
 @router.get(

backend/app/routers/pronunciation.py

@@ -0,0 +1,88 @@
+"""Word-level pronunciation scoring (Wav2Vec2 + CMU phonemes)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
+
+from app.core.dependencies import get_current_user
+from app.core.rate_limit import limiter
+from app.core.upload import ALLOWED_AUDIO_EXTENSIONS, MAX_AUDIO_UPLOAD_SIZE, read_upload_limited
+from app.db.models import User
+from app.services.phoneme_scorer import get_expected_word_info, get_phoneme_scorer
+from app.services.pronunciation_audio import audio_bytes_to_waveform
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/pronunciation", tags=["Pronunciation"])
+
+
+def _clean_word(word: str) -> str:
+    return re.sub(r"[^a-zA-Z'-]", "", (word or "").strip())
+
+
+@router.get("/word/{word}/expected")
+async def get_word_expected_phonemes(
+    word: str,
+    _user: User = Depends(get_current_user),
+):
+    """Return expected CMU phonemes/IPA for display before recording."""
+    cleaned = _clean_word(word)
+    if not cleaned:
+        raise HTTPException(status_code=400, detail="word is required")
+    info = get_expected_word_info(cleaned)
+    if not info:
+        raise HTTPException(
+            status_code=422,
+            detail=f"Từ '{cleaned}' không có trong CMU Pronouncing Dictionary.",
+        )
+    return info
+
+
+@limiter.limit("20/minute")
+@router.post("/word")
+async def score_word_pronunciation(
+    request: Request,
+    word: str = Form(...),
+    audio: UploadFile = File(...),
+    _user: User = Depends(get_current_user),
+):
+    """Score single-word pronunciation from browser-recorded audio."""
+    cleaned = _clean_word(word)
+    if not cleaned:
+        raise HTTPException(status_code=400, detail="word is required")
+
+    if not get_expected_word_info(cleaned):
+        raise HTTPException(
+            status_code=422,
+            detail=f"Từ '{cleaned}' không có trong CMU Pronouncing Dictionary.",
+        )
+
+    suffix = (audio.filename or "audio.webm").rsplit(".", 1)
+    ext = f".{suffix[-1].lower()}" if len(suffix) > 1 else ".webm"
+    if ext not in ALLOWED_AUDIO_EXTENSIONS:
+        raise HTTPException(status_code=400, detail="Unsupported audio file type")
+
+    audio_bytes = await read_upload_limited(audio, MAX_AUDIO_UPLOAD_SIZE)
+
+    try:
+        waveform, sample_rate = await asyncio.to_thread(
+            audio_bytes_to_waveform,
+            audio_bytes,
+            audio.filename or "audio.webm",
+        )
+        result = await asyncio.to_thread(
+            get_phoneme_scorer().score_word,
+            waveform,
+            sample_rate,
+            cleaned,
+        )
+        return result.to_dict()
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except Exception as exc:
+        logger.exception("pronunciation/word failed for %s", cleaned)
+        raise HTTPException(status_code=500, detail=f"Kiểm tra phát âm thất bại: {exc}") from exc

backend/app/routers/shadowing.py

@@ -10,6 +10,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.core.config import settings
 from app.core.dependencies import get_current_user
 from app.core.rate_limit import limiter
+from app.core.upload import ALLOWED_AUDIO_EXTENSIONS, MAX_AUDIO_UPLOAD_SIZE, read_upload_limited
 from app.db.database import get_db
 from app.db.models import User
 from app.repositories.shadowing_repository import ShadowingRepository
@@ -63,6 +64,7 @@ async def process_video(
             level=body.level,
             translate=body.translate,
             user_id=user.id,
+            force_refresh=body.force_refresh,
         )
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e)) from e
@@ -168,23 +170,39 @@ async def translate_segment(
 
 
 @router.post("/pronunciation/check")
+@limiter.limit("10/minute")
 async def check_pronunciation(
+    request: Request,
     file: UploadFile = File(...),
     target_text: str = Form(...),
     _user: User = Depends(get_current_user),
 ):
-    """Whisper transcript + pron_scorer model vs target sentence."""
+    """Whisper transcript + pron_scorer model vs target sentence (same pipeline as speaking)."""
     if not (target_text or "").strip():
         raise HTTPException(status_code=400, detail="target_text is required")
+    if len(target_text) > 1000:
+        raise HTTPException(status_code=400, detail="target_text is too long")
+    suffix = (file.filename or "audio.webm").rsplit(".", 1)
+    ext = f".{suffix[-1].lower()}" if len(suffix) > 1 else ".webm"
+    if ext not in ALLOWED_AUDIO_EXTENSIONS:
+        raise HTTPException(status_code=400, detail="Unsupported audio file type")
+    audio_bytes = await read_upload_limited(file, MAX_AUDIO_UPLOAD_SIZE)
+    if len(audio_bytes) < 512:
+        raise HTTPException(status_code=422, detail="File ghi âm quá ngắn hoặc rỗng.")
     try:
         data = await check_pronunciation_from_bytes(
-            await file.read(),
+            audio_bytes,
             file.filename or "audio.webm",
             target_text.strip(),
         )
         return data
     except FileNotFoundError as e:
-        raise HTTPException(status_code=503, detail=str(e)) from e
+        raise HTTPException(
+            status_code=503,
+            detail="Mô hình phát âm chưa sẵn sàng. Đặt pron_scorer_best.pt vào backend/model/.",
+        ) from e
+    except ValueError as e:
+        raise HTTPException(status_code=422, detail=str(e)) from e
     except Exception as e:
         logger.exception("pronunciation check failed")
-        raise HTTPException(status_code=500, detail=str(e)) from e
+        raise HTTPException(status_code=500, detail=f"Kiểm tra phát âm thất bại: {e}") from e

backend/app/routers/speaking.py

@@ -7,7 +7,6 @@ import tempfile
 from pathlib import Path
 from typing import Any
 
-import httpx
 from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
@@ -16,14 +15,14 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.config import settings
 from app.core.dependencies import get_current_user
+from app.core.openrouter_client import chat_completion, has_openrouter_keys
 from app.core.rate_limit import limiter
+from app.core.upload import ALLOWED_AUDIO_EXTENSIONS, MAX_AUDIO_UPLOAD_SIZE, read_upload_limited
 from app.db.database import get_db
 from app.db.models import History, User
 from app.repositories.profile_repository import ProfileRepository
 from app.services.speaking_ai_helpers import (
-    AI_MODEL,
     OPENROUTER_KEY,
-    OPENROUTER_URL,
     _call_language_cards,
     _normalize_grammar_analysis,
     _normalize_vocabulary_analysis,
@@ -61,8 +60,8 @@ Use short sections with bullets:
 Avoid long essays unless the user explicitly asks for full sample answer."""
 
 
-@router.post("/chat")
 @limiter.limit("30/minute")
+@router.post("/chat")
 async def speaking_chat(
     request: Request,
     body: ChatRequest,
@@ -70,7 +69,7 @@ async def speaking_chat(
 ):
     """Proxy chat messages to OpenRouter for speaking coaching (JWT required)."""
     _ = current_user
-    if not OPENROUTER_KEY:
+    if not has_openrouter_keys():
         return JSONResponse(
             status_code=503,
             content={"error": "AI service unavailable: OPENROUTER_API_KEY is missing"},
@@ -83,27 +82,18 @@ async def speaking_chat(
             "content": f'Current IELTS Speaking question the student is practising: "{body.question_text}"',
         })
     for m in body.history[-10:]:
-        messages.append({"role": m.role, "content": m.content})
+        role = m.role if m.role in {"user", "assistant"} else "user"
+        messages.append({"role": role, "content": m.content})
     messages.append({"role": "user", "content": body.user_message})
 
-    payload = {
-        "model": AI_MODEL,
-        "messages": messages,
-        "temperature": 0.7,
-        "max_tokens": 800,
-    }
-    headers = {
-        "Authorization": f"Bearer {OPENROUTER_KEY}",
-        "HTTP-Referer": "http://localhost:3000",
-        "Content-Type": "application/json",
-        "X-Title": "LinguaIELTS",
-    }
-
     try:
-        async with httpx.AsyncClient(timeout=60.0) as client:
-            resp = await client.post(OPENROUTER_URL, json=payload, headers=headers)
-            resp.raise_for_status()
-        reply = resp.json()["choices"][0]["message"]["content"]
+        reply, _model = await chat_completion(
+            messages,
+            max_tokens=800,
+            temperature=0.7,
+            timeout=60.0,
+            title="LinguaIELTS Speaking Coach",
+        )
         return {"reply": reply}
     except Exception as exc:
         logger.warning("Speaking chat OpenRouter error: %s", exc)
@@ -113,8 +103,8 @@ async def speaking_chat(
         )
 
 
-@router.post("/analyze-language")
 @limiter.limit("20/minute")
+@router.post("/analyze-language")
 async def analyze_language(
     request: Request,
     body: TranscriptAnalyzeRequest,
@@ -163,9 +153,12 @@ async def evaluate_speaking(
     """HTTP handler: save upload, optionally dispatch Celery, else run pipeline inline."""
     await ProfileRepository(db).ensure_speaking_eval_allowed(current_user.id)
 
-    suffix = Path(file.filename or "audio.webm").suffix or ".webm"
+    suffix = (Path(file.filename or "audio.webm").suffix or ".webm").lower()
+    if suffix not in ALLOWED_AUDIO_EXTENSIONS:
+        raise HTTPException(status_code=400, detail="Unsupported audio file type")
+    audio_bytes = await read_upload_limited(file, MAX_AUDIO_UPLOAD_SIZE)
     with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as tmp:
-        tmp.write(await file.read())
+        tmp.write(audio_bytes)
         tmp_path = tmp.name
 
     if settings.CELERY_ENABLED:

backend/app/routers/translation.py

@@ -0,0 +1,71 @@
+"""
+Translation Practice router — /translation/*
+"""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+from fastapi import APIRouter, Depends, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.dependencies import get_current_user
+from app.core.rate_limit import limiter
+from app.db.database import get_db
+from app.db.models import User
+from app.services.translation_service import TranslationService
+
+router = APIRouter(prefix="/translation", tags=["Translation Practice"])
+
+
+class TranslationCheckRequest(BaseModel):
+    sentence_id: int = Field(gt=0)
+    user_translation: str = Field(min_length=1, max_length=2000)
+
+
+def _svc(db: AsyncSession = Depends(get_db)) -> TranslationService:
+    return TranslationService(db)
+
+
+@router.get("/steps")
+async def list_steps(svc: TranslationService = Depends(_svc)) -> dict:
+    """List all learning steps with topic and sentence counts."""
+    steps = await svc.list_steps_with_counts()
+    return {"code": 0, "data": steps}
+
+
+@router.get("/steps/{step_id}/topics")
+async def list_topics(
+    step_id: int,
+    current_user: User = Depends(get_current_user),
+    svc: TranslationService = Depends(_svc),
+) -> dict:
+    """List all topics within a step, with user progress."""
+    topics = await svc.list_topics_for_step(step_id, current_user.id)
+    return {"code": 0, "data": topics}
+
+
+@router.get("/topics/{topic_id}/sentences")
+async def list_sentences(
+    topic_id: int,
+    current_user: User = Depends(get_current_user),
+    svc: TranslationService = Depends(_svc),
+) -> dict:
+    """List all sentences in a topic with hint words and previous attempt info."""
+    sentences = await svc.list_sentences_for_topic(topic_id, current_user.id)
+    return {"code": 0, "data": sentences}
+
+
+@limiter.limit("20/minute")
+@router.post("/check")
+async def check_translation(
+    request: Request,
+    body: TranslationCheckRequest,
+    current_user: User = Depends(get_current_user),
+    svc: TranslationService = Depends(_svc),
+) -> dict:
+    """Grade user's translation with AI. Returns score, feedback, model_answer."""
+    result = await svc.check_translation(
+        user_id=current_user.id,
+        sentence_id=body.sentence_id,
+        user_translation=body.user_translation,
+    )
+    return {"code": 0, "data": result}

backend/app/routers/users.py

@@ -1,10 +1,9 @@
-import httpx
 from fastapi import APIRouter, Depends, File, HTTPException, Request, UploadFile, status
 from pydantic import BaseModel
 from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.core.config import settings
+from app.core.openrouter_client import chat_completion, has_openrouter_keys
 from app.core.dependencies import get_current_user
 from app.core.rate_limit import limiter
 from app.core.upload import validate_and_read_image
@@ -38,9 +37,6 @@ from app.services.users_service import UsersService
 
 router = APIRouter(prefix="/users", tags=["Users"])
 
-_OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
-_OPENROUTER_MODEL = "anthropic/claude-3-haiku"
-
 
 class DashboardChatMessage(BaseModel):
     role: str
@@ -327,8 +323,8 @@ async def toggle_task_complete(
         raise HTTPException(status_code=404, detail=str(exc)) from exc
 
 
-@router.post("/me/chat")
 @limiter.limit("10/minute")
+@router.post("/me/chat")
 async def dashboard_chat(
     request: Request,
     body: DashboardChatRequest,
@@ -340,7 +336,7 @@ async def dashboard_chat(
     """
     await ProfileRepository(db).ensure_tutor_chat_allowed(current_user.id)
 
-    if not settings.OPENROUTER_API_KEY:
+    if not has_openrouter_keys():
         return {"error": "OPENROUTER_API_KEY is missing in backend environment."}
 
     profile_rs = await db.execute(select(UserProfile).where(UserProfile.user_id == current_user.id))
@@ -389,26 +385,18 @@ async def dashboard_chat(
         {"role": "system", "content": context_prompt},
     ]
     for m in body.history[-8:]:
-        messages.append({"role": m.role, "content": m.content})
+        role = m.role if m.role in {"user", "assistant"} else "user"
+        messages.append({"role": role, "content": m.content})
     messages.append({"role": "user", "content": body.user_message})
 
-    payload = {
-        "model": _OPENROUTER_MODEL,
-        "messages": messages,
-        "temperature": 0.5,
-        "max_tokens": 700,
-    }
-    headers = {
-        "Authorization": f"Bearer {settings.OPENROUTER_API_KEY}",
-        "HTTP-Referer": "http://localhost:5173",
-        "X-Title": "LinguaIELTS Dashboard Coach",
-        "Content-Type": "application/json",
-    }
     try:
-        async with httpx.AsyncClient(timeout=20.0) as client:
-            resp = await client.post(_OPENROUTER_URL, json=payload, headers=headers)
-            resp.raise_for_status()
-        reply = resp.json()["choices"][0]["message"]["content"]
+        reply, _model = await chat_completion(
+            messages,
+            max_tokens=700,
+            temperature=0.5,
+            timeout=20.0,
+            title="LinguaIELTS Dashboard Coach",
+        )
         await ProfileRepository(db).increment_tutor_chat(current_user.id)
         return {"reply": reply}
     except Exception as exc:

backend/app/routers/writing.py

@@ -1,12 +1,11 @@
 from __future__ import annotations
 
-import httpx
 from fastapi import APIRouter, Depends, Query, Request
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 
-from app.core.config import settings
 from app.core.dependencies import get_current_user
+from app.core.openrouter_client import chat_completion, has_openrouter_keys
 from app.core.rate_limit import limiter
 from app.core.usage_counters import check_and_increment_writing_chat
 from app.db.database import get_db
@@ -18,8 +17,6 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 router = APIRouter(prefix="", tags=["Writing"])
 
-_OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
-
 _WRITING_SYSTEM = (
     "You are Catbot, an expert IELTS Writing coach with 10+ years of experience. "
     "You help students improve their Task 1 and Task 2 writing skills. "
@@ -40,8 +37,8 @@ class _WritingChatReq(BaseModel):
     history: list[_ChatMsg] = []
 
 
-@router.post("/writing/chat")
 @limiter.limit("30/minute")
+@router.post("/writing/chat")
 async def writing_chat(
     request: Request,
     body: _WritingChatReq,
@@ -49,6 +46,9 @@ async def writing_chat(
 ):
     """Proxy chat to OpenRouter for writing coaching, with topic context (JWT required)."""
     check_and_increment_writing_chat(current_user.id)
+    if not has_openrouter_keys():
+        return JSONResponse(status_code=503, content={"error": "AI service unavailable: OPENROUTER_API_KEY is missing"})
+
     messages: list[dict] = [{"role": "system", "content": _WRITING_SYSTEM}]
     if body.prompt_text:
         messages.append({
@@ -56,26 +56,18 @@ async def writing_chat(
             "content": f'Current IELTS Writing task the student is working on: "{body.prompt_text}"',
         })
     for m in body.history[-10:]:
-        messages.append({"role": m.role, "content": m.content})
+        role = m.role if m.role in {"user", "assistant"} else "user"
+        messages.append({"role": role, "content": m.content})
     messages.append({"role": "user", "content": body.user_message})
 
-    payload = {
-        "model":       "anthropic/claude-3-haiku",
-        "messages":    messages,
-        "max_tokens":  800,
-        "temperature": 0.6,
-    }
-    headers = {
-        "Authorization": f"Bearer {settings.OPENROUTER_API_KEY}",
-        "Content-Type":  "application/json",
-        "HTTP-Referer":  "https://cathoven-clone.local",
-        "X-Title":       "Writing Coach",
-    }
     try:
-        async with httpx.AsyncClient(timeout=15.0) as client:
-            resp = await client.post(_OPENROUTER_URL, json=payload, headers=headers)
-            resp.raise_for_status()
-        reply = resp.json()["choices"][0]["message"]["content"]
+        reply, _model = await chat_completion(
+            messages,
+            max_tokens=800,
+            temperature=0.6,
+            timeout=15.0,
+            title="Writing Coach",
+        )
         return {"reply": reply}
     except Exception as exc:
         return JSONResponse(status_code=502, content={"error": f"AI service unavailable: {exc}"})

backend/app/schemas.py

@@ -11,12 +11,12 @@ from pydantic import BaseModel, EmailStr, Field
 # ═══ Auth ════════════════════════════════════
 class UserCreate(BaseModel):
     email: EmailStr
-    password: str = Field(min_length=6, max_length=128)
+    password: str = Field(min_length=10, max_length=128)
     full_name: Optional[str] = None
 
 class UserLogin(BaseModel):
     email: EmailStr
-    password: str = Field(min_length=6, max_length=128)
+    password: str = Field(min_length=1, max_length=128)
 
 class Token(BaseModel):
     access_token: str
@@ -67,7 +67,25 @@ class AuthLogoutRequest(BaseModel):
 
 
 class VerifyEmailRequest(BaseModel):
-    token: str
+    email: EmailStr
+    code: str = Field(min_length=6, max_length=6)
+
+
+class ResendVerificationRequest(BaseModel):
+    email: EmailStr
+
+
+class RegisterResponse(BaseModel):
+    """Returned after email registration — directs user to verify inbox."""
+    needs_verification: bool = True
+    email: str
+    message: str = "Mã xác minh đã được gửi đến email của bạn."
+
+
+class GoogleAuthRequest(BaseModel):
+    """Frontend sends the authorization code received from Google."""
+    code: str
+    redirect_uri: str
 
 
 class ForgotPasswordRequest(BaseModel):
@@ -76,7 +94,7 @@ class ForgotPasswordRequest(BaseModel):
 
 class ResetPasswordRequest(BaseModel):
     token: str
-    new_password: str = Field(min_length=6, max_length=128)
+    new_password: str = Field(min_length=10, max_length=128)
 
 
 # ═══ Progress ════════════════════════════════
@@ -191,8 +209,8 @@ class UserMeUpdateRequest(BaseModel):
 
 
 class ChangePasswordRequest(BaseModel):
-    current_password: str = Field(min_length=6, max_length=128)
-    new_password: str = Field(min_length=6, max_length=128)
+    current_password: str = Field(min_length=1, max_length=128)
+    new_password: str = Field(min_length=10, max_length=128)
 
 
 class WritingSubmitRequest(BaseModel):
@@ -821,6 +839,7 @@ class ShadowingProcessVideoRequest(BaseModel):
     url: str = Field(..., min_length=8)
     level: str = Field(default="Intermediate", max_length=50)
     translate: bool = Field(default=True)
+    force_refresh: bool = Field(default=False)
 
 
 class ShadowingTranslateRequest(BaseModel):

backend/app/services/admin_content_service.py

@@ -11,6 +11,7 @@ from typing import Any
 
 from fastapi import HTTPException, UploadFile, status
 
+from app.core.upload import MAX_ADMIN_IMAGE_SIZE, read_upload_limited
 from app.schemas import (
     AdminContentListResponse,
     AdminContentResponse,
@@ -69,11 +70,9 @@ class AdminContentService:
                 status_code=status.HTTP_400_BAD_REQUEST,
                 detail="Only PNG, JPG, JPEG, and WEBP images are supported",
             )
-        content = await upload.read()
+        content = await read_upload_limited(upload, MAX_ADMIN_IMAGE_SIZE)
         if not content:
             raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Image file is empty")
-        if len(content) > 5 * 1024 * 1024:
-            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Image file must be 5MB or smaller")
         image_id = uuid.uuid4().hex
         image_dir = self._data_root / "assets" / "images"
         image_dir.mkdir(parents=True, exist_ok=True)

backend/app/services/auth_service.py

@@ -1,18 +1,23 @@
 """
 app/services/auth_service.py
 ──────────────────────────────
-Business logic for registration and login.
+Business logic for registration, login, Google OAuth, and email verification.
 Orchestrates UserRepository + ProfileRepository and issues JWT tokens.
 """
 
+from __future__ import annotations
+
+import hashlib
 import logging
 import secrets
 from datetime import datetime, timedelta, timezone
 
+import httpx
 from fastapi import HTTPException, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.core.config import admin_email_set, settings
+from app.core.config import settings
+from app.core.password_policy import assert_password_strength
 from app.core.security import (
     create_access_token,
     create_refresh_token,
@@ -21,31 +26,52 @@ from app.core.security import (
     hash_token,
     verify_password,
 )
+from app.repositories.email_verification_repository import EmailVerificationRepository
 from app.repositories.password_reset_repository import PasswordResetRepository
 from app.repositories.profile_repository import ProfileRepository
 from app.repositories.refresh_token_repository import RefreshTokenRepository
 from app.repositories.user_repository import UserRepository
-from app.schemas import ForgotPasswordRequest, MessageResponse, ResetPasswordRequest, Token, UserCreate, UserLogin
-from app.services.email_service import send_password_reset_email, smtp_configured
+from app.schemas import (
+    ForgotPasswordRequest,
+    GoogleAuthRequest,
+    MessageResponse,
+    RegisterResponse,
+    ResendVerificationRequest,
+    ResetPasswordRequest,
+    Token,
+    UserCreate,
+    UserLogin,
+    VerifyEmailRequest,
+)
+from app.services.email_service import send_verification_email, send_password_reset_email, smtp_configured
 
 logger = logging.getLogger(__name__)
 
+_GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token"
+_GOOGLE_USERINFO_URL = "https://www.googleapis.com/oauth2/v2/userinfo"
+
+
+def _hash_otp(code: str) -> str:
+    return hashlib.sha256(code.encode()).hexdigest()
+
 
 class AuthService:
     def __init__(self, db: AsyncSession) -> None:
+        self._db = db
         self._user_repo = UserRepository(db)
         self._profile_repo = ProfileRepository(db)
         self._refresh_repo = RefreshTokenRepository(db)
         self._reset_repo = PasswordResetRepository(db)
+        self._verify_repo = EmailVerificationRepository(db)
 
-    async def register(self, payload: UserCreate) -> Token:
+    async def register(self, payload: UserCreate) -> RegisterResponse:
         """
-        Register a new user:
+        Register a new user with email verification:
         1. Check email is not taken
         2. Hash password
-        3. Create user row
-        4. Create empty profile (with optional full_name)
-        5. Return JWT token so the user is immediately logged in
+        3. Create unverified user row + empty profile
+        4. Generate & send 6-digit OTP
+        5. Return needs_verification response
         """
         existing = await self._user_repo.get_by_email(payload.email)
         if existing:
@@ -54,6 +80,8 @@ class AuthService:
                 detail="Email already registered",
             )
 
+        assert_password_strength(payload.password)
+
         try:
             hashed = hash_password(payload.password)
         except (ValueError, RuntimeError) as exc:
@@ -62,21 +90,144 @@ class AuthService:
                 status_code=status.HTTP_400_BAD_REQUEST,
                 detail="Invalid password format",
             ) from exc
-        role = "admin" if payload.email.lower() in admin_email_set() else "user"
-        user = await self._user_repo.create(email=payload.email, password_hash=hashed, role=role)
+
+        user = await self._user_repo.create(
+            email=payload.email,
+            password_hash=hashed,
+            role="user",
+            is_verified=False,
+            auth_provider="email",
+        )
         await self._profile_repo.create_empty(user.id, full_name=payload.full_name)
+        await self._send_otp(user.id, user.email)
+
+        logger.info("New user registered (pending verification): id=%s email=%s", user.id, user.email)
+        return RegisterResponse(email=user.email)
 
-        logger.info("New user registered: id=%s email=%s", user.id, user.email)
+    async def verify_email_otp(self, payload: VerifyEmailRequest) -> Token:
+        """Validate the 6-digit OTP and issue a token pair on success."""
+        user = await self._user_repo.get_by_email(payload.email)
+        if not user:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Mã xác minh không hợp lệ.")
 
+        row = await self._verify_repo.get_latest_unused(user.id)
+        if not row or row.code_hash != _hash_otp(payload.code):
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Mã xác minh không đúng hoặc đã hết hạn.")
+
+        await self._verify_repo.mark_used(row)
+        await self._user_repo.mark_verified(user)
+
+        logger.info("Email verified for user id=%s", user.id)
         return await self._issue_token_pair(user.id)
 
-    async def login(self, payload: UserLogin) -> Token:
+    async def resend_verification(self, payload: ResendVerificationRequest) -> MessageResponse:
+        """Re-send the verification OTP (always returns generic message)."""
+        generic = MessageResponse(message="Nếu email tồn tại và chưa xác minh, chúng tôi đã gửi mã mới.")
+        user = await self._user_repo.get_by_email(payload.email)
+        if not user or user.is_verified:
+            return generic
+
+        await self._send_otp(user.id, user.email)
+        return generic
+
+    async def google_auth(self, payload: GoogleAuthRequest) -> Token:
         """
-        Authenticate a user:
-        1. Look up by email
-        2. Verify bcrypt password
-        3. Return JWT token
+        Exchange a Google authorization code for user info,
+        then find or create the user and issue a token pair.
         """
+        if not settings.GOOGLE_CLIENT_ID or not settings.GOOGLE_CLIENT_SECRET:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail="Google OAuth is not configured on this server.",
+            )
+
+        async with httpx.AsyncClient(timeout=10) as client:
+            token_resp = await client.post(
+                _GOOGLE_TOKEN_URL,
+                data={
+                    "code": payload.code,
+                    "client_id": settings.GOOGLE_CLIENT_ID,
+                    "client_secret": settings.GOOGLE_CLIENT_SECRET,
+                    "redirect_uri": payload.redirect_uri,
+                    "grant_type": "authorization_code",
+                },
+            )
+            if token_resp.status_code != 200:
+                google_err = token_resp.json() if token_resp.headers.get("content-type", "").startswith("application/json") else {}
+                google_err_code = google_err.get("error", "")
+                logger.warning("Google token exchange failed (%s): %s", token_resp.status_code, token_resp.text)
+                if google_err_code == "redirect_uri_mismatch":
+                    detail = "Redirect URI không khớp. Kiểm tra cấu hình Google Cloud Console."
+                elif google_err_code == "invalid_grant":
+                    detail = "Mã Google đã hết hạn hoặc đã được dùng. Vui lòng thử lại."
+                elif google_err_code == "invalid_client":
+                    detail = "Cấu hình Google OAuth không đúng (client_id/secret)."
+                else:
+                    detail = f"Không thể xác thực với Google ({google_err_code or token_resp.status_code}). Vui lòng thử lại."
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=detail,
+                )
+
+            google_access = token_resp.json().get("access_token")
+            if not google_access:
+                raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Google token invalid.")
+
+            info_resp = await client.get(
+                _GOOGLE_USERINFO_URL,
+                headers={"Authorization": f"Bearer {google_access}"},
+            )
+            if info_resp.status_code != 200:
+                raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Không lấy được thông tin Google.")
+
+        info = info_resp.json()
+        google_id: str = info.get("id", "")
+        email: str = info.get("email", "")
+        full_name: str = info.get("name", "")
+        avatar_url: str = info.get("picture", "")
+
+        if not google_id or not email:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Google trả về thông tin không đầy đủ.")
+
+        # Find existing account by google_id, then by email
+        user = await self._user_repo.get_by_google_id(google_id)
+        if not user:
+            user = await self._user_repo.get_by_email(email)
+            if user:
+                # Link Google ID to existing email account
+                await self._user_repo.update_google_id(user, google_id)
+                if not user.is_verified:
+                    await self._user_repo.mark_verified(user)
+                # Enrich profile with Google data if fields are missing
+                await self._update_profile_from_google(user.id, full_name, avatar_url)
+            else:
+                # Create brand-new Google-authenticated user
+                placeholder_hash = hash_password(secrets.token_urlsafe(32))
+                user = await self._user_repo.create(
+                    email=email,
+                    password_hash=placeholder_hash,
+                    google_id=google_id,
+                    is_verified=True,
+                    auth_provider="google",
+                )
+                await self._profile_repo.create_empty(
+                    user.id,
+                    full_name=full_name,
+                    avatar_url=avatar_url,
+                )
+        else:
+            # Returning Google user — refresh avatar/name if updated on Google side
+            await self._update_profile_from_google(user.id, full_name, avatar_url)
+
+        if not user.is_active:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Tài khoản đã bị khóa.")
+
+        logger.info("Google OAuth login: user id=%s email=%s", user.id, user.email)
+        return await self._issue_token_pair(user.id)
+
+    # ── Existing methods (unchanged) ─────────────────────────────────────────
+
+    async def login(self, payload: UserLogin) -> Token:
         user = await self._user_repo.get_by_email(payload.email)
         if not user or not verify_password(payload.password, user.password_hash):
             raise HTTPException(
@@ -85,16 +236,16 @@ class AuthService:
                 headers={"WWW-Authenticate": "Bearer"},
             )
         if not user.is_active:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Account is locked")
+
+        if not user.is_verified and settings.REQUIRE_EMAIL_VERIFICATION:
             raise HTTPException(
                 status_code=status.HTTP_403_FORBIDDEN,
-                detail="Account is locked",
+                detail="email_not_verified",
+                headers={"X-Email": user.email},
             )
-        if user.email.lower() in admin_email_set() and user.role != "admin":
-            user.role = "admin"
-            logger.info("Auto-promoted admin user: id=%s email=%s", user.id, user.email)
 
         logger.info("User logged in: id=%s", user.id)
-
         return await self._issue_token_pair(user.id)
 
     async def refresh(self, refresh_token: str) -> Token:
@@ -113,9 +264,6 @@ class AuthService:
             raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
         if not user.is_active:
             raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Account is locked")
-        if user.email.lower() in admin_email_set() and user.role != "admin":
-            user.role = "admin"
-
         await self._refresh_repo.revoke(active)
         return await self._issue_token_pair(user_id)
 
@@ -168,6 +316,8 @@ class AuthService:
         if not user:
             raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
 
+        assert_password_strength(payload.new_password)
+
         try:
             new_hash = hash_password(payload.new_password)
         except (ValueError, RuntimeError) as exc:
@@ -181,6 +331,45 @@ class AuthService:
         await self._refresh_repo.revoke_all_for_user(user.id)
         return MessageResponse(message="Đã đặt lại mật khẩu thành công. Vui lòng đăng nhập lại.")
 
+    async def _update_profile_from_google(
+        self, user_id: int, google_name: str, google_avatar: str
+    ) -> None:
+        """Enrich user profile with Google data only when local fields are missing."""
+        profile = await self._profile_repo.get_by_user_id(user_id)
+        if not profile:
+            await self._profile_repo.create_empty(
+                user_id, full_name=google_name, avatar_url=google_avatar
+            )
+            return
+        # Only update fields that are still empty — don't overwrite user's own edits
+        new_name   = google_name   if google_name   and not profile.full_name   else None
+        new_avatar = google_avatar if google_avatar and not profile.avatar_url  else None
+        if new_name is not None or new_avatar is not None:
+            await self._profile_repo.update(
+                profile,
+                full_name=new_name,
+                phone=None,
+                bio=None,
+                avatar_url=new_avatar,
+            )
+
+    async def _send_otp(self, user_id: int, email: str) -> None:
+        """Generate a 6-digit OTP, store its hash, and email the raw code."""
+        await self._verify_repo.invalidate_all_for_user(user_id)
+        code = f"{secrets.randbelow(1_000_000):06d}"
+        expires_at = datetime.now(timezone.utc) + timedelta(minutes=settings.EMAIL_VERIFY_EXPIRE_MINUTES)
+        await self._verify_repo.create(user_id=user_id, code_hash=_hash_otp(code), expires_at=expires_at)
+        try:
+            await send_verification_email(to_email=email, code=code)
+        except Exception:
+            if settings.DEBUG:
+                logger.warning("Dev OTP for %s: %s", email, code)
+            else:
+                raise HTTPException(
+                    status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                    detail="Không gửi được email xác minh. Vui lòng thử lại.",
+                ) from None
+
     async def _issue_token_pair(self, user_id: int) -> Token:
         access_token = create_access_token(subject=user_id)
         raw_refresh = create_refresh_token(subject=user_id)

backend/app/services/email_service.py

@@ -51,6 +51,45 @@ async def send_password_reset_email(*, to_email: str, reset_url: str) -> None:
         raise
 
 
+async def send_verification_email(*, to_email: str, code: str) -> None:
+    """Send a 6-digit OTP to verify the user's email address."""
+    subject = "LinguaIELTS — Xác minh địa chỉ email"
+    body = (
+        "Chào bạn,\n\n"
+        "Mã xác minh email LinguaIELTS của bạn là:\n\n"
+        f"    {code}\n\n"
+        f"Mã có hiệu lực trong 15 phút.\n"
+        "Nếu bạn không đăng ký tài khoản, hãy bỏ qua email này.\n\n"
+        "— LinguaIELTS"
+    )
+
+    if not smtp_configured():
+        logger.warning(
+            "SMTP not configured — verification code for %s: %s",
+            to_email,
+            code,
+        )
+        return
+
+    msg = EmailMessage()
+    msg["Subject"] = subject
+    msg["From"] = settings.SMTP_FROM
+    msg["To"] = to_email
+    msg.set_content(body)
+
+    try:
+        with smtplib.SMTP(settings.SMTP_HOST, settings.SMTP_PORT, timeout=15) as server:
+            if settings.SMTP_USE_TLS:
+                server.starttls()
+            if settings.SMTP_USER and settings.SMTP_PASSWORD:
+                server.login(settings.SMTP_USER, settings.SMTP_PASSWORD)
+            server.send_message(msg)
+        logger.info("Verification email sent to %s", to_email)
+    except Exception as exc:
+        logger.error("Failed to send verification email: %s", exc)
+        raise
+
+
 async def send_daily_study_reminder_email(
     *,
     to_email: str,

backend/app/services/phoneme_recognizer.py

@@ -0,0 +1,164 @@
+"""Acoustic phoneme recognition — Allosaurus (IPA) + Whisper word check."""
+
+from __future__ import annotations
+
+import logging
+import re
+import tempfile
+from difflib import SequenceMatcher
+from pathlib import Path
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+_ALLOSUARUS = None
+
+
+def _normalize_ipa(symbol: str) -> str:
+    s = symbol.strip().lower()
+    aliases = {
+        "g": "ɡ",
+        "ɾ": "r",
+        "ʔ": "",
+        "ɝ": "ɜːr",
+        "ɚ": "ɜːr",
+        "ɜ": "ɜːr",
+        "ɜː": "ɜːr",
+        "u": "uː",  # allosaurus often short; CMU uses uː for UW
+        "i": "iː",
+        "o": "oʊ",
+        "e": "eɪ",
+        "a": "ɑ",
+        "ə": "ʌ",   # schwa ↔ AH in many American words
+    }
+    return aliases.get(s, s)
+
+
+def waveform_to_wav_path(waveform_16k: np.ndarray) -> str:
+    from pydub import AudioSegment
+
+    samples = (np.clip(waveform_16k, -1.0, 1.0) * 32_767).astype(np.int16)
+    seg = AudioSegment(
+        samples.tobytes(),
+        frame_rate=16_000,
+        sample_width=2,
+        channels=1,
+    )
+    tmp = tempfile.NamedTemporaryFile(delete=False, suffix=".wav")
+    tmp_path = tmp.name
+    tmp.close()
+    seg.export(tmp_path, format="wav")
+    return tmp_path
+
+
+def safe_unlink(path: str) -> None:
+    try:
+        Path(path).unlink(missing_ok=True)
+    except OSError:
+        pass
+
+
+def _get_allosaurus():
+    global _ALLOSUARUS
+    if _ALLOSUARUS is None:
+        from allosaurus.app import read_recognizer
+
+        logger.info("Loading Allosaurus phoneme recognizer …")
+        _ALLOSUARUS = read_recognizer()
+        logger.info("Allosaurus ready.")
+    return _ALLOSUARUS
+
+
+def recognize_ipa_phonemes(wav_path: str) -> list[str]:
+    """Extract IPA phoneme sequence from audio (Allosaurus — ELSA-style acoustic check)."""
+    try:
+        model = _get_allosaurus()
+        raw = model.recognize(wav_path, lang_id="eng", timestamp=False) or ""
+        tokens = [_normalize_ipa(t) for t in raw.split() if t.strip()]
+        tokens = [t for t in tokens if t]
+        logger.info("Allosaurus IPA: %s", tokens)
+        return tokens
+    except Exception as exc:
+        logger.warning("Allosaurus phoneme recognition failed: %s", exc)
+        return []
+
+
+def _best_word_from_transcript(full_text: str, expected_clean: str) -> tuple[str, float]:
+    """Pick the token from Whisper output closest to the expected word."""
+    if not expected_clean:
+        return "", 0.0
+
+    full_clean = re.sub(r"[^a-z]", "", full_text.lower())
+    if full_clean == expected_clean:
+        return expected_clean, 1.0
+    if expected_clean in full_clean:
+        return expected_clean, 0.98
+
+    candidates = re.findall(r"[a-z]+", full_text.lower())
+    best_tok = full_clean
+    best_ratio = SequenceMatcher(None, expected_clean, full_clean).ratio() if full_clean else 0.0
+
+    for tok in candidates:
+        ratio = SequenceMatcher(None, expected_clean, tok).ratio()
+        if ratio > best_ratio:
+            best_ratio = ratio
+            best_tok = tok
+
+    return best_tok, best_ratio
+
+
+def transcribe_single_word(wav_path: str, expected_word: str) -> tuple[str, float]:
+    """Whisper single-word transcription; returns best-matching token + confidence 0-1."""
+    from ml.model_registry import get_whisper_model
+
+    expected_clean = re.sub(r"[^a-z]", "", expected_word.lower())
+
+    try:
+        model = get_whisper_model()
+        result = model.transcribe(
+            wav_path,
+            language="en",
+            word_timestamps=True,
+            verbose=False,
+            condition_on_previous_text=False,
+            fp16=False,
+            temperature=0,
+            no_speech_threshold=0.45,
+            logprob_threshold=-1.0,
+            compression_ratio_threshold=2.8,
+        )
+
+        full_text = (result.get("text") or "").strip()
+        best_tok, match_ratio = _best_word_from_transcript(full_text, expected_clean)
+
+        # Word-level probability from timestamps (if available)
+        ts_conf = 0.0
+        for seg in result.get("segments") or []:
+            for w in seg.get("words") or []:
+                w_clean = re.sub(r"[^a-z]", "", (w.get("word") or "").lower())
+                if not w_clean:
+                    continue
+                prob = float(w.get("probability") or 0.0)
+                r = SequenceMatcher(None, expected_clean, w_clean).ratio()
+                if r >= match_ratio - 0.05:
+                    ts_conf = max(ts_conf, min(prob, 1.0))
+
+        confidence = max(match_ratio, ts_conf)
+        if match_ratio >= 0.92:
+            confidence = max(confidence, 0.9)
+        elif match_ratio >= 0.78:
+            confidence = max(confidence, match_ratio * 0.88)
+
+        logger.info(
+            "Whisper raw=%r best=%r match=%.2f conf=%.2f",
+            full_text,
+            best_tok,
+            match_ratio,
+            confidence,
+        )
+        return best_tok, confidence
+
+    except Exception as exc:
+        logger.warning("Whisper word transcription failed: %s", exc)
+        return "", 0.0

backend/app/services/phoneme_scorer.py

@@ -0,0 +1,373 @@
+"""Word-level phoneme scoring — Allosaurus + CMU + Whisper (ELSA-style)."""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import asdict, dataclass, field
+from difflib import SequenceMatcher
+from typing import Any
+
+import numpy as np
+
+from app.services.phoneme_recognizer import (
+    recognize_ipa_phonemes,
+    safe_unlink,
+    transcribe_single_word,
+    waveform_to_wav_path,
+)
+from app.services.pronunciation_audio import prepare_speech_waveform
+from app.services.speaking_audio_utils import has_speech
+
+logger = logging.getLogger(__name__)
+
+ARPABET_TO_IPA: dict[str, str] = {
+    "AA": "ɑ",  "AE": "æ",  "AH": "ʌ",  "AO": "ɔ",  "AW": "aʊ", "AY": "aɪ",
+    "B":  "b",  "CH": "tʃ", "D":  "d",  "DH": "ð",  "EH": "ɛ",  "ER": "ɜːr",
+    "EY": "eɪ", "F":  "f",  "G":  "ɡ",  "HH": "h",  "IH": "ɪ",  "IY": "iː",
+    "JH": "dʒ", "K":  "k",  "L":  "l",  "M":  "m",  "N":  "n",  "NG": "ŋ",
+    "OW": "oʊ", "OY": "ɔɪ", "P":  "p",  "R":  "r",  "S":  "s",  "SH": "ʃ",
+    "T":  "t",  "TH": "θ",  "UH": "ʊ",  "UW": "uː", "V":  "v",  "W":  "w",
+    "Y":  "j",  "Z":  "z",  "ZH": "ʒ",
+}
+
+PHONEME_TIPS: dict[str, str] = {
+    "TH": "Đặt đầu lưỡi nhẹ giữa hai hàm răng, thổi hơi ra — không phát âm thành /t/ hay /d/",
+    "DH": "Giống /θ/ nhưng có tiếng vang (voiced) — lưỡi giữa răng + rung thanh quản",
+    "R":  "Cuộn lưỡi về phía sau, không chạm vòm miệng",
+    "V":  "Môi dưới chạm nhẹ răng trên, thổi hơi có tiếng — không phát âm thành /b/ hay /w/",
+    "AE": "Mở miệng rộng, kéo khóe miệng sang hai bên — 'cat' không phải 'cet'",
+    "ER": "Cuộn lưỡi giữa chừng, giữ nguyên — âm 'bird', 'her'",
+    "IY": "Kéo dài hơn /i/ trong tiếng Việt — 'see', 'feel'",
+}
+
+IPA_SIMILAR: set[frozenset[str]] = {
+    frozenset({"θ", "t", "f"}),
+    frozenset({"ð", "d", "v", "z"}),
+    frozenset({"ʃ", "s", "tʃ", "ʒ"}),
+    frozenset({"ɪ", "i", "iː", "iy", "ə"}),
+    frozenset({"ʊ", "u", "uː", "uw", "oʊ", "ow"}),
+    frozenset({"ʌ", "ə", "ɑ", "ah", "a", "ae", "æ"}),
+    frozenset({"ɛ", "e", "æ", "eh", "eɪ", "ey"}),
+    frozenset({"ɔ", "o", "ao", "oh", "ɔɪ", "oy"}),
+    frozenset({"r", "ɹ", "ɜːr", "er", "l"}),
+    frozenset({"ŋ", "n", "ng", "m"}),
+    frozenset({"b", "p"}),
+    frozenset({"g", "ɡ", "k"}),
+    frozenset({"f", "v"}),
+    frozenset({"s", "z"}),
+    frozenset({"w", "v", "u"}),
+    frozenset({"j", "y", "dʒ"}),
+    frozenset({"aɪ", "ay", "ɑɪ", "a"}),
+    frozenset({"aʊ", "aw"}),
+    frozenset({"oʊ", "ow", "ou", "o"}),
+    frozenset({"eɪ", "ey", "ei", "e"}),
+    frozenset({"ɔɪ", "oy", "oi"}),
+    frozenset({"tʃ", "ch", "ʃ"}),
+    frozenset({"dʒ", "jh", "j"}),
+}
+
+_CMUDICT: dict[str, list[list[str]]] | None = None
+
+
+def _base_symbol(symbol: str) -> str:
+    return re.sub(r"\d+$", "", symbol.upper())
+
+
+def _arpabet_to_ipa(symbol: str) -> str:
+    return ARPABET_TO_IPA.get(_base_symbol(symbol), symbol.lower())
+
+
+def _ipa_string(phonemes: list[str]) -> str:
+    if not phonemes:
+        return "/?/"
+    if phonemes[0].isupper():
+        parts = [_arpabet_to_ipa(p) for p in phonemes]
+    else:
+        parts = list(phonemes)
+    return "/" + "".join(parts) + "/"
+
+
+def _ensure_cmudict() -> dict[str, list[list[str]]]:
+    global _CMUDICT
+    if _CMUDICT is not None:
+        return _CMUDICT
+    import nltk
+    from nltk.corpus import cmudict
+
+    try:
+        nltk.data.find("corpora/cmudict")
+    except LookupError:
+        nltk.download("cmudict", quiet=True)
+    _CMUDICT = cmudict.dict()
+    return _CMUDICT
+
+
+def lookup_word_phonemes(word: str) -> list[str] | None:
+    cleaned = re.sub(r"[^a-z'-]", "", word.lower())
+    if not cleaned:
+        return None
+    pronunciations = _ensure_cmudict().get(cleaned)
+    return list(pronunciations[0]) if pronunciations else None
+
+
+def get_expected_word_info(word: str) -> dict[str, Any] | None:
+    phonemes = lookup_word_phonemes(word)
+    if not phonemes:
+        return None
+    ipa_list = [_arpabet_to_ipa(p) for p in phonemes]
+    return {"word": word.lower(), "ipa": _ipa_string(phonemes), "phonemes": phonemes, "ipa_list": ipa_list}
+
+
+def _ipa_similar(a: str, b: str) -> bool:
+    if not a or not b:
+        return False
+    if a == b:
+        return True
+    for group in IPA_SIMILAR:
+        if a in group and b in group:
+            return True
+    return False
+
+
+def _ipa_pair_score(expected: str, predicted: str | None) -> float:
+    if not predicted:
+        return 0.0
+    if expected == predicted:
+        return 1.0
+    if _ipa_similar(expected, predicted):
+        return 0.7
+    # partial: same first character (e.g. k/kw)
+    if expected and predicted and expected[0] == predicted[0]:
+        return 0.45
+    return 0.0
+
+
+def _align_ipa_scores(expected_ipa: list[str], predicted_ipa: list[str]) -> list[float]:
+    if not expected_ipa:
+        return []
+    if not predicted_ipa:
+        return [0.0] * len(expected_ipa)
+
+    matcher = SequenceMatcher(None, expected_ipa, predicted_ipa, autojunk=False)
+    scores = [0.0] * len(expected_ipa)
+
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        if tag == "equal":
+            for k in range(i2 - i1):
+                scores[i1 + k] = _ipa_pair_score(expected_ipa[i1 + k], predicted_ipa[j1 + k])
+        elif tag == "replace":
+            span = min(i2 - i1, j2 - j1)
+            for k in range(span):
+                scores[i1 + k] = _ipa_pair_score(expected_ipa[i1 + k], predicted_ipa[j1 + k])
+
+    return scores
+
+
+def _merge_scores(*score_lists: list[float]) -> list[float]:
+    if not score_lists:
+        return []
+    n = max(len(s) for s in score_lists)
+    merged = [0.0] * n
+    for scores in score_lists:
+        for i, s in enumerate(scores):
+            merged[i] = max(merged[i], s)
+    return merged
+
+
+def _phoneme_scores_to_letters(word: str, phoneme_scores: list[float]) -> list["LetterDetail"]:
+    n, m = len(word), len(phoneme_scores)
+    if n == 0:
+        return []
+    if m == 0:
+        return [LetterDetail(char=c, score=0.0, correct=False) for c in word]
+    return [
+        LetterDetail(
+            char=ch,
+            score=phoneme_scores[min(int(i * m / n), m - 1)],
+            correct=phoneme_scores[min(int(i * m / n), m - 1)] >= 0.65,
+        )
+        for i, ch in enumerate(word)
+    ]
+
+
+def _verdict(overall: float) -> str:
+    if overall >= 85:
+        return "Excellent "
+    if overall >= 70:
+        return "Good "
+    if overall >= 50:
+        return "Needs Practice "
+    return "Keep Trying "
+
+
+def _resample_if_needed(waveform: np.ndarray, sample_rate: int) -> np.ndarray:
+    if sample_rate == 16_000:
+        return waveform.astype(np.float32)
+    import librosa
+
+    return librosa.resample(waveform.astype(np.float32), orig_sr=sample_rate, target_sr=16_000)
+
+
+@dataclass
+class LetterDetail:
+    char: str
+    score: float
+    correct: bool
+
+
+@dataclass
+class PhonemeDetail:
+    symbol: str
+    ipa: str
+    expected: bool
+    score: float
+    correct: bool
+    tip: str | None = None
+
+
+@dataclass
+class PhonemeResult:
+    word: str
+    overall_score: float
+    phonemes: list[PhonemeDetail] = field(default_factory=list)
+    letters: list[LetterDetail] = field(default_factory=list)
+    decoded_text: str = ""
+    ipa_expected: str = ""
+    ipa_predicted: str = ""
+    verdict: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["phonemes"] = [
+            {"symbol": p.symbol, "ipa": p.ipa, "score": round(p.score, 2), "correct": p.correct, "tip": p.tip}
+            for p in self.phonemes
+        ]
+        data["letters"] = [
+            {"char": l.char, "score": round(l.score, 2), "correct": l.correct} for l in self.letters
+        ]
+        data["overall_score"] = round(self.overall_score, 1)
+        return data
+
+
+class PhonemeScorer:
+    """Score pronunciation: Allosaurus acoustic phonemes vs CMU, Whisper word sanity check."""
+
+    def score_word(
+        self,
+        waveform_np: np.ndarray,
+        sample_rate: int,
+        expected_word: str,
+    ) -> PhonemeResult:
+        expected_arpabet = lookup_word_phonemes(expected_word)
+        if not expected_arpabet:
+            raise ValueError(f"Từ '{expected_word}' không có trong CMU Pronouncing Dictionary.")
+
+        audio = _resample_if_needed(waveform_np, sample_rate)
+        audio = prepare_speech_waveform(audio, 16_000)
+        if audio.size == 0:
+            raise ValueError("Audio rỗng hoặc không hợp lệ.")
+        if not has_speech(audio):
+            raise ValueError("Không phát hiện giọng nói. Hãy nói to hơn hoặc kiểm tra micro.")
+
+        expected_clean = re.sub(r"[^a-z]", "", expected_word.lower())
+        expected_ipa = [_arpabet_to_ipa(p) for p in expected_arpabet]
+        n_expected = len(expected_ipa)
+
+        wav_path = waveform_to_wav_path(audio)
+        try:
+            acoustic_ipa = recognize_ipa_phonemes(wav_path)
+            whisper_text, whisper_conf = transcribe_single_word(wav_path, expected_clean)
+            word_match = (
+                SequenceMatcher(None, expected_clean, whisper_text).ratio()
+                if whisper_text
+                else 0.0
+            )
+
+            # Acoustic alignment (Allosaurus)
+            acoustic_scores = _align_ipa_scores(expected_ipa, acoustic_ipa)
+
+            # CMU alignment from heard word (Whisper)
+            heard_arpabet = lookup_word_phonemes(whisper_text) if whisper_text else None
+            heard_ipa = [_arpabet_to_ipa(p) for p in heard_arpabet] if heard_arpabet else []
+            whisper_scores = _align_ipa_scores(expected_ipa, heard_ipa) if heard_ipa else []
+
+            per_phoneme = _merge_scores(acoustic_scores, whisper_scores)
+            if len(per_phoneme) != n_expected:
+                per_phoneme = (per_phoneme + [0.0] * n_expected)[:n_expected]
+
+            # Whisper heard the right word → boost (short clips often confuse Allosaurus)
+            if word_match >= 0.95 or whisper_conf >= 0.88:
+                floor = min(0.82 + 0.15 * max(word_match, whisper_conf), 1.0)
+                per_phoneme = [max(s, floor) for s in per_phoneme]
+            elif word_match >= 0.82:
+                floor = min(0.68 + 0.22 * word_match, 1.0)
+                per_phoneme = [max(s, floor) for s in per_phoneme]
+            elif word_match >= 0.65:
+                floor = 0.5 + 0.25 * word_match
+                per_phoneme = [max(s, floor) for s in per_phoneme]
+
+            # Partial acoustic match — blend with current scores
+            if acoustic_ipa and acoustic_scores:
+                ac_mean = float(np.mean(acoustic_scores))
+                if ac_mean >= 0.35:
+                    whisper_pad = (
+                        whisper_scores
+                        if len(whisper_scores) == n_expected
+                        else [0.0] * n_expected
+                    )
+                    per_phoneme = [
+                        max(p, ac * 0.9)
+                        for p, ac in zip(per_phoneme, acoustic_scores, strict=False)
+                    ]
+
+            overall = float(np.mean(per_phoneme) * 100) if per_phoneme else 0.0
+
+            logger.info(
+                "SCORE word=%s acoustic=%s whisper=%s match=%.2f per=%s overall=%.1f",
+                expected_clean,
+                acoustic_ipa,
+                whisper_text,
+                word_match,
+                [round(s, 2) for s in per_phoneme],
+                overall,
+            )
+
+            details: list[PhonemeDetail] = []
+            for arpabet, ipa, score in zip(expected_arpabet, expected_ipa, per_phoneme, strict=False):
+                base = _base_symbol(arpabet)
+                correct = score >= 0.65
+                details.append(
+                    PhonemeDetail(
+                        symbol=arpabet,
+                        ipa=ipa,
+                        expected=True,
+                        score=score,
+                        correct=correct,
+                        tip=None if correct else PHONEME_TIPS.get(base),
+                    )
+                )
+
+            predicted_ipa_display = acoustic_ipa or heard_ipa
+            return PhonemeResult(
+                word=expected_word.lower(),
+                overall_score=overall,
+                phonemes=details,
+                letters=_phoneme_scores_to_letters(expected_word, per_phoneme),
+                decoded_text=whisper_text or (" ".join(acoustic_ipa) if acoustic_ipa else ""),
+                ipa_expected=_ipa_string(expected_arpabet),
+                ipa_predicted=_ipa_string(predicted_ipa_display),
+                verdict=_verdict(overall),
+            )
+        finally:
+            safe_unlink(wav_path)
+
+
+_SCORER: PhonemeScorer | None = None
+
+
+def get_phoneme_scorer() -> PhonemeScorer:
+    global _SCORER
+    if _SCORER is None:
+        _SCORER = PhonemeScorer()
+    return _SCORER

backend/app/services/pronunciation_audio.py

@@ -0,0 +1,76 @@
+"""Convert uploaded browser audio to mono float32 waveform for phoneme scoring."""
+
+from __future__ import annotations
+
+from io import BytesIO
+from pathlib import Path
+
+import numpy as np
+
+
+def prepare_speech_waveform(waveform: np.ndarray, sample_rate: int) -> np.ndarray:
+    """Peak-normalize, trim silence, pad short clips — helps Whisper/Allosaurus on browser recordings."""
+    from pydub import AudioSegment
+    from pydub.silence import detect_nonsilent
+
+    if waveform.size == 0:
+        return waveform
+
+    audio = waveform.astype(np.float32)
+    peak = float(np.max(np.abs(audio)))
+    if peak > 1e-6:
+        audio = (audio / peak) * 0.92
+
+    samples_int = (np.clip(audio, -1.0, 1.0) * 32_767).astype(np.int16)
+    seg = AudioSegment(
+        samples_int.tobytes(),
+        frame_rate=sample_rate,
+        sample_width=2,
+        channels=1,
+    )
+
+    try:
+        thresh = seg.dBFS - 14 if seg.dBFS != float("-inf") else -40
+        nonsilent = detect_nonsilent(seg, min_silence_len=100, silence_thresh=thresh, seek_step=10)
+        if nonsilent:
+            start = max(0, nonsilent[0][0] - 40)
+            end = min(len(seg), nonsilent[-1][1] + 60)
+            seg = seg[start:end]
+    except Exception:
+        pass
+
+    min_ms = 700
+    if len(seg) < min_ms:
+        seg = seg + AudioSegment.silent(duration=min_ms - len(seg), frame_rate=sample_rate)
+
+    out = np.array(seg.get_array_of_samples(), dtype=np.float32) / 32_767.0
+    return out.astype(np.float32)
+
+
+def audio_bytes_to_waveform(audio_bytes: bytes, filename: str) -> tuple[np.ndarray, int]:
+    """Load WebM/WAV/OGG bytes via pydub; validate duration; return (waveform, sample_rate)."""
+    from pydub import AudioSegment
+
+    if len(audio_bytes) < 64:
+        raise ValueError("File ghi âm quá ngắn hoặc rỗng.")
+
+    suffix = (Path(filename or "audio.webm").suffix or ".webm").lower().lstrip(".")
+    fmt = None if suffix in {"webm", "bin"} else suffix
+
+    seg = AudioSegment.from_file(BytesIO(audio_bytes), format=fmt)
+    duration_s = len(seg) / 1000.0
+    if duration_s < 0.3:
+        raise ValueError("Âm thanh quá ngắn (<0.3 giây). Hãy nói rõ hơn.")
+    if duration_s > 10.0:
+        raise ValueError("Âm thanh quá dài (>10 giây). Hãy chỉ nói một từ.")
+
+    if seg.channels > 1:
+        seg = seg.set_channels(1)
+
+    samples = np.array(seg.get_array_of_samples(), dtype=np.float32)
+    max_val = float(2 ** (8 * seg.sample_width - 1))
+    if max_val > 0:
+        samples /= max_val
+
+    samples = prepare_speech_waveform(samples, int(seg.frame_rate))
+    return samples, int(seg.frame_rate)