# minhanhjr/luatganban_mvp architecture

> Architecture diagram of the GitHub repository minhanhjr/luatganban_mvp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/minhanhjr/luatganban_mvp
- Repository: https://github.com/minhanhjr/luatganban_mvp

## Overview

LUẬT GẦN BẢN is a voice-first legal-procedure assistant for Hmong-speaking residents. The main workflow takes a spoken question through speech recognition, two-stage procedure routing, plain-language guidance, translation and speech playback; uncertain cases can be handed to staff. Staff also manage procedure data, review generated answers and administer accounts. The graph retains documented language and audio capabilities. Some UI-to-core calls are supported by the SOURCE INDEX rather than complete excerpts; unsampled implementation details are not inferred.

Main entry points: [`giao_dien/cong_dan.py`](https://github.com/minhanhjr/luatganban_mvp/blob/main/giao_dien/cong_dan.py) (Citizen portal), [`core/llm.py`](https://github.com/minhanhjr/luatganban_mvp/blob/main/core/llm.py) (Gemini client), [`giao_dien/quan_tri.py`](https://github.com/minhanhjr/luatganban_mvp/blob/main/giao_dien/quan_tri.py) (Procedure administration), [`app.py`](https://github.com/minhanhjr/luatganban_mvp/blob/main/app.py) (App navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application"]
  node_app["App navigation<br/>[app.py]"]
end

subgraph group_citizen["Resident assistance"]
  node_citizen_ui["Citizen portal<br/>[cong_dan.py]"]
  node_intro["Introduction<br/>[gioi_thieu.py]"]
end

subgraph group_services["Language and AI"]
  node_stt["Speech recognition<br/>[stt.py]"]
  node_routing["Intent routing<br/>[router.py]"]
  node_kb[("Procedure knowledge<br/>[kb.py]")]
  node_simplify["Legal simplification<br/>[simplify.py]"]
  node_translate["Translation<br/>[translate.py]"]
  node_rpa["Hmong transcription<br/>[rpa_vi.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
  node_llm["Gemini client<br/>[llm.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_manifest[("Procedure catalog<br/>[manifest.json]")]
end

subgraph group_staff["Staff operations"]
  node_admin_ui["Procedure administration<br/>[quan_tri.py]"]
  node_accounts_ui["Account management<br/>[tai_khoan.py]"]
  node_auth["Authentication and roles<br/>[auth.py]"]
  node_overrides[("Staff catalog overrides<br/>[kho_ghi_de.json]")]
  node_answer_cache[("Reviewed answers cache")]
  node_user_store[("User records<br/>[users.json]")]
end

node_resident(("Resident"))
node_gemini_service{{"Google Gemini"}}
node_speech_service{{"SpeechRecognition fallback"}}

node_resident -->|"asks aloud"| node_citizen_ui
node_app -->|"routes to"| node_citizen_ui
node_app -->|"routes to"| node_admin_ui
node_app -->|"routes to"| node_intro
node_citizen_ui -->|"recognizes speech"| node_stt
node_citizen_ui -->|"routes question"| node_routing
node_routing -->|"selects procedure"| node_kb
node_kb -->|"loads catalog"| node_manifest
node_citizen_ui -->|"gets guidance"| node_simplify
node_citizen_ui -->|"translates answer"| node_translate
node_translate -->|"converts script"| node_rpa
node_citizen_ui -->|"requests playback"| node_tts
node_tts -->|"phonetic fallback"| node_rpa
node_routing -->|"classifies intent"| node_llm
node_simplify -->|"generates guidance"| node_llm
node_translate -->|"translates with"| node_llm
node_llm -->|"calls API"| node_gemini_service
node_stt -->|"uses recognition model"| node_llm
node_stt -.->|"fallback recognition"| node_speech_service
node_admin_ui -->|"edits catalog"| node_kb
node_admin_ui -->|"prewarms answers"| node_simplify
node_admin_ui -->|"reviews answers"| node_answer_cache
node_admin_ui -.->|"saves edits"| node_overrides
node_accounts_ui -->|"manages accounts"| node_auth
node_app -->|"checks access"| node_auth
node_auth -->|"reads and writes"| node_user_store
node_routing -->|"uses thresholds"| node_config
node_llm -->|"uses model settings"| node_config

click node_app "https://github.com/minhanhjr/luatganban_mvp/blob/main/app.py"
click node_citizen_ui "https://github.com/minhanhjr/luatganban_mvp/blob/main/giao_dien/cong_dan.py"
click node_intro "https://github.com/minhanhjr/luatganban_mvp/blob/main/giao_dien/gioi_thieu.py"
click node_stt "https://github.com/minhanhjr/luatganban_mvp/blob/main/core/stt.py"
click node_routing "https://github.com/minhanhjr/luatganban_mvp/blob/main/core/router.py"
click node_kb "https://github.com/minhanhjr/luatganban_mvp/blob/main/core/kb.py"
click node_simplify "https://github.com/minhanhjr/luatganban_mvp/blob/main/core/simplify.py"
click node_translate "https://github.com/minhanhjr/luatganban_mvp/blob/main/core/translate.py"
click node_rpa "https://github.com/minhanhjr/luatganban_mvp/blob/main/core/hmong/rpa_vi.py"
click node_tts "https://github.com/minhanhjr/luatganban_mvp/blob/main/core/tts.py"
click node_llm "https://github.com/minhanhjr/luatganban_mvp/blob/main/core/llm.py"
click node_config "https://github.com/minhanhjr/luatganban_mvp/blob/main/core/config.py"
click node_admin_ui "https://github.com/minhanhjr/luatganban_mvp/blob/main/giao_dien/quan_tri.py"
click node_accounts_ui "https://github.com/minhanhjr/luatganban_mvp/blob/main/giao_dien/tai_khoan.py"
click node_auth "https://github.com/minhanhjr/luatganban_mvp/blob/main/core/auth.py"
click node_manifest "https://github.com/minhanhjr/luatganban_mvp/blob/main/data/manifest.json"
click node_overrides "https://github.com/minhanhjr/luatganban_mvp/blob/main/data/kho_ghi_de.json"
click node_answer_cache "https://github.com/minhanhjr/luatganban_mvp/tree/main/data/cache/simplified"
click node_user_store "https://github.com/minhanhjr/luatganban_mvp/blob/main/data/users.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app toneBlue
class node_citizen_ui,node_intro toneAmber
class node_stt,node_routing,node_kb,node_simplify,node_translate,node_rpa,node_tts,node_llm,node_config,node_manifest toneMint
class node_admin_ui,node_accounts_ui,node_auth,node_overrides,node_answer_cache,node_user_store toneRose
class node_resident,node_gemini_service,node_speech_service toneIndigo
```

## Components

### Application

- [App navigation](https://github.com/minhanhjr/luatganban_mvp/blob/main/app.py): `app.py`

### Resident assistance

- [Citizen portal](https://github.com/minhanhjr/luatganban_mvp/blob/main/giao_dien/cong_dan.py): `giao_dien/cong_dan.py`
- [Introduction](https://github.com/minhanhjr/luatganban_mvp/blob/main/giao_dien/gioi_thieu.py): `giao_dien/gioi_thieu.py`

### Language and AI

- [Speech recognition](https://github.com/minhanhjr/luatganban_mvp/blob/main/core/stt.py): `core/stt.py`
- [Intent routing](https://github.com/minhanhjr/luatganban_mvp/blob/main/core/router.py): `core/router.py`
- [Procedure knowledge](https://github.com/minhanhjr/luatganban_mvp/blob/main/core/kb.py): `core/kb.py`
- [Legal simplification](https://github.com/minhanhjr/luatganban_mvp/blob/main/core/simplify.py): `core/simplify.py`
- [Translation](https://github.com/minhanhjr/luatganban_mvp/blob/main/core/translate.py): `core/translate.py`
- [Hmong transcription](https://github.com/minhanhjr/luatganban_mvp/blob/main/core/hmong/rpa_vi.py): `core/hmong/rpa_vi.py`
- [Speech synthesis](https://github.com/minhanhjr/luatganban_mvp/blob/main/core/tts.py): `core/tts.py`
- [Gemini client](https://github.com/minhanhjr/luatganban_mvp/blob/main/core/llm.py): `core/llm.py`
- [Runtime configuration](https://github.com/minhanhjr/luatganban_mvp/blob/main/core/config.py): `core/config.py`
- [Procedure catalog](https://github.com/minhanhjr/luatganban_mvp/blob/main/data/manifest.json): `data/manifest.json`

### Staff operations

- [Procedure administration](https://github.com/minhanhjr/luatganban_mvp/blob/main/giao_dien/quan_tri.py): `giao_dien/quan_tri.py`
- [Account management](https://github.com/minhanhjr/luatganban_mvp/blob/main/giao_dien/tai_khoan.py): `giao_dien/tai_khoan.py`
- [Authentication and roles](https://github.com/minhanhjr/luatganban_mvp/blob/main/core/auth.py): `core/auth.py`
- [Staff catalog overrides](https://github.com/minhanhjr/luatganban_mvp/blob/main/data/kho_ghi_de.json): `data/kho_ghi_de.json`
- [Reviewed answers cache](https://github.com/minhanhjr/luatganban_mvp/tree/main/data/cache/simplified): `data/cache/simplified`
- [User records](https://github.com/minhanhjr/luatganban_mvp/blob/main/data/users.json): `data/users.json`

### Other components

- **Resident**
- **Google Gemini**
- **SpeechRecognition fallback**

## Connections

- Resident → Citizen portal: asks aloud (evidence: `README.md`)
- App navigation → Citizen portal: routes to (evidence: `README.md`)
- App navigation → Procedure administration: routes to (evidence: `README.md`)
- App navigation → Introduction: routes to (evidence: `README.md`)
- Citizen portal → Speech recognition: recognizes speech (evidence: `giao_dien/cong_dan.py`)
- Citizen portal → Intent routing: routes question (evidence: `giao_dien/cong_dan.py`)
- Intent routing → Procedure knowledge: selects procedure (evidence: `core/router.py`)
- Procedure knowledge → Procedure catalog: loads catalog (evidence: `core/kb.py`)
- Citizen portal → Legal simplification: gets guidance (evidence: `giao_dien/cong_dan.py`)
- Citizen portal → Translation: translates answer (evidence: `giao_dien/cong_dan.py`)
- Translation → Hmong transcription: converts script (evidence: `core/translate.py`)
- Citizen portal → Speech synthesis: requests playback (evidence: `giao_dien/cong_dan.py`)
- Speech synthesis → Hmong transcription: phonetic fallback (evidence: `core/tts.py`)
- Intent routing → Gemini client: classifies intent (evidence: `core/router.py`)
- Legal simplification → Gemini client: generates guidance (evidence: `core/simplify.py`)
- Translation → Gemini client: translates with (evidence: `core/translate.py`)
- Gemini client → Google Gemini: calls API (evidence: `README.md`)
- Speech recognition → Gemini client: uses recognition model (evidence: `core/stt.py`)
- Speech recognition → SpeechRecognition fallback: fallback recognition (evidence: `README.md`)
- Procedure administration → Procedure knowledge: edits catalog (evidence: `giao_dien/quan_tri.py`)
- Procedure administration → Legal simplification: prewarms answers (evidence: `README.md`)
- Procedure administration → Reviewed answers cache: reviews answers (evidence: `giao_dien/quan_tri.py`)
- Procedure administration → Staff catalog overrides: saves edits (evidence: `README.md`)
- Account management → Authentication and roles: manages accounts (evidence: `giao_dien/tai_khoan.py`)
- App navigation → Authentication and roles: checks access (evidence: `app.py`)
- Authentication and roles → User records: reads and writes (evidence: `README.md`)
- Intent routing → Runtime configuration: uses thresholds (evidence: `core/router.py`)
- Gemini client → Runtime configuration: uses model settings (evidence: `core/llm.py`)
