# mfreshad/japanese_mastery architecture

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

- Interactive diagram: https://gitdiagram.com/mfreshad/japanese_mastery
- Repository: https://github.com/mfreshad/japanese_mastery

## Overview

Japanese Mastery is a book-based Japanese vocabulary and kanji study system. Learners browse library material, study vocabulary or kanji, practice questions, and track progress; managers maintain books, chapters, items, imports, and review marks. The backend exposes these capabilities through FastAPI and stores study content and practice state in PostgreSQL. The graph preserves documented product branches, but sampled source supports only some request-to-service relationships; unsampled routes are represented without guessed internal call chains.

Main entry points: [`backend/app/main.py`](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/main.py) (API application), [`backend/app/api/review.py`](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/review.py) (Review API), [`backend/app/models/item.py`](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/models/item.py) (Content models), [`frontend/features/management/ReviewMarksScreen.tsx`](https://github.com/mfreshad/japanese_mastery/blob/main/frontend/features/management/ReviewMarksScreen.tsx) (Review marks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Learner and management UI"]
  node_library_ui["Library<br/>[Screen.tsx]"]
  node_study_ui["Study screens<br/>[Screen.tsx]"]
  node_practice_ui["Practice screen<br/>[Screen.tsx]"]
  node_progress_ui["Progress view<br/>[page.tsx]"]
  node_manage_ui["Content management<br/>[Screen.tsx]"]
  node_review_ui["Review marks"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_app["API application<br/>[main.py]"]
  node_books_api["Books API<br/>[books.py]"]
  node_items_api["Items API<br/>[items.py]"]
  node_imports_api["Imports API<br/>[imports.py]"]
  node_library_api["Library API<br/>[library.py]"]
  node_practice_api["Practice API<br/>[practice.py]"]
  node_review_api["Review API<br/>[review.py]"]
  node_other_api["Study and progress APIs<br/>[study.py]"]
end

subgraph group_domain["Study and content services"]
  node_items_service["Item management<br/>[item_management.py]"]
  node_practice_service["Practice engine<br/>[service.py]"]
  node_import_service["JSON import<br/>[service.py]"]
  node_content_ops["Books and library operations"]
end

subgraph group_state["Persistent study data"]
  node_models["Content models<br/>[item.py]"]
  node_practice_models["Progress and sessions<br/>[practice.py]"]
  node_db_session["Database session<br/>[session.py]"]
end

node_learner(("Learner / manager"))
node_database[("Neon PostgreSQL")]

node_learner -->|"browses"| node_library_ui
node_learner -->|"studies"| node_study_ui
node_learner -->|"practices"| node_practice_ui
node_learner -->|"tracks progress"| node_progress_ui
node_learner -->|"manages content"| node_manage_ui
node_learner -->|"reviews marks"| node_review_ui
node_review_ui -->|"requests data"| node_api_client
node_api_client -.->|"sends HTTP requests"| node_review_api
node_app -->|"registers route"| node_books_api
node_app -->|"registers route"| node_items_api
node_app -->|"registers route"| node_imports_api
node_app -->|"registers route"| node_library_api
node_app -->|"registers route"| node_practice_api
node_app -->|"registers route"| node_review_api
node_app -->|"registers routes"| node_other_api
node_items_api -->|"delegates to"| node_items_service
node_practice_api -->|"dispatches to"| node_practice_service
node_imports_api -->|"delegates to"| node_import_service
node_books_api -->|"delegates to"| node_content_ops
node_items_service -->|"updates"| node_models
node_practice_service -->|"persists sessions"| node_practice_models
node_review_api -->|"reads progress"| node_practice_models
node_review_api -->|"reads review items"| node_models
node_import_service -->|"imports content"| node_models
node_db_session -->|"connects to"| node_database

click node_library_ui "https://github.com/mfreshad/japanese_mastery/blob/main/frontend/features/library/Screen.tsx"
click node_study_ui "https://github.com/mfreshad/japanese_mastery/blob/main/frontend/features/study/Screen.tsx"
click node_practice_ui "https://github.com/mfreshad/japanese_mastery/blob/main/frontend/features/practice/Screen.tsx"
click node_progress_ui "https://github.com/mfreshad/japanese_mastery/blob/main/frontend/app/progress/page.tsx"
click node_manage_ui "https://github.com/mfreshad/japanese_mastery/blob/main/frontend/features/management/Screen.tsx"
click node_review_ui "https://github.com/mfreshad/japanese_mastery/blob/main/frontend/features/management/ReviewMarksScreen.tsx"
click node_api_client "https://github.com/mfreshad/japanese_mastery/blob/main/frontend/lib/api.ts"
click node_app "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/main.py"
click node_books_api "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/books.py"
click node_items_api "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/items.py"
click node_imports_api "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/imports.py"
click node_library_api "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/library.py"
click node_practice_api "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/practice.py"
click node_review_api "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/review.py"
click node_other_api "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/study.py"
click node_items_service "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/services/item_management.py"
click node_practice_service "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/services/practice/service.py"
click node_import_service "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/services/imports/service.py"
click node_content_ops "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/services/books_operations.py"
click node_models "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/models/item.py"
click node_practice_models "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/models/practice.py"
click node_db_session "https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/db/session.py"

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_library_ui,node_study_ui,node_practice_ui,node_progress_ui,node_manage_ui,node_review_ui,node_api_client toneBlue
class node_app,node_books_api,node_items_api,node_imports_api,node_library_api,node_practice_api,node_review_api,node_other_api,node_database toneAmber
class node_items_service,node_practice_service,node_import_service,node_content_ops toneMint
class node_models,node_practice_models,node_db_session toneRose
class node_learner toneIndigo
```

## Components

### Learner and management UI

- [Library](https://github.com/mfreshad/japanese_mastery/blob/main/frontend/features/library/Screen.tsx): `frontend/features/library/Screen.tsx`
- [Study screens](https://github.com/mfreshad/japanese_mastery/blob/main/frontend/features/study/Screen.tsx): `frontend/features/study/Screen.tsx`
- [Practice screen](https://github.com/mfreshad/japanese_mastery/blob/main/frontend/features/practice/Screen.tsx): `frontend/features/practice/Screen.tsx`
- [Progress view](https://github.com/mfreshad/japanese_mastery/blob/main/frontend/app/progress/page.tsx): `frontend/app/progress/page.tsx`
- [Content management](https://github.com/mfreshad/japanese_mastery/blob/main/frontend/features/management/Screen.tsx): `frontend/features/management/Screen.tsx`
- [Review marks](https://github.com/mfreshad/japanese_mastery/blob/main/frontend/features/management/ReviewMarksScreen.tsx): `frontend/features/management/ReviewMarksScreen.tsx`
- [API client](https://github.com/mfreshad/japanese_mastery/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Backend API

- [API application](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/main.py): `backend/app/main.py`
- [Books API](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/books.py): `backend/app/api/books.py`
- [Items API](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/items.py): `backend/app/api/items.py`
- [Imports API](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/imports.py): `backend/app/api/imports.py`
- [Library API](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/library.py): `backend/app/api/library.py`
- [Practice API](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/practice.py): `backend/app/api/practice.py`
- [Review API](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/review.py): `backend/app/api/review.py`
- [Study and progress APIs](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/api/study.py): `backend/app/api/study.py`

### Study and content services

- [Item management](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/services/item_management.py): `backend/app/services/item_management.py`
- [Practice engine](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/services/practice/service.py): `backend/app/services/practice/service.py`
- [JSON import](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/services/imports/service.py): `backend/app/services/imports/service.py`
- [Books and library operations](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/services/books_operations.py): `backend/app/services/books_operations.py`

### Persistent study data

- [Content models](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/models/item.py): `backend/app/models/item.py`
- [Progress and sessions](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/models/practice.py): `backend/app/models/practice.py`
- [Database session](https://github.com/mfreshad/japanese_mastery/blob/main/backend/app/db/session.py): `backend/app/db/session.py`

### Other components

- **Learner / manager**
- **Neon PostgreSQL**

## Connections

- Learner / manager → Library: browses (evidence: `README.md`)
- Learner / manager → Study screens: studies (evidence: `README.md`)
- Learner / manager → Practice screen: practices (evidence: `README.md`)
- Learner / manager → Progress view: tracks progress (evidence: `README.md`)
- Learner / manager → Content management: manages content (evidence: `README.md`)
- Learner / manager → Review marks: reviews marks
- Review marks → API client: requests data (evidence: `frontend/features/management/ReviewMarksScreen.tsx`)
- API client → Review API: sends HTTP requests
- API application → Books API: registers route (evidence: `backend/app/main.py`)
- API application → Items API: registers route (evidence: `backend/app/main.py`)
- API application → Imports API: registers route (evidence: `backend/app/main.py`)
- API application → Library API: registers route (evidence: `backend/app/main.py`)
- API application → Practice API: registers route (evidence: `backend/app/main.py`)
- API application → Review API: registers route (evidence: `backend/app/main.py`)
- API application → Study and progress APIs: registers routes (evidence: `backend/app/main.py`)
- Items API → Item management: delegates to (evidence: `backend/app/api/items.py`)
- Practice API → Practice engine: dispatches to (evidence: `backend/app/api/practice.py`)
- Imports API → JSON import: delegates to (evidence: `backend/app/api/imports.py`)
- Books API → Books and library operations: delegates to (evidence: `backend/app/api/books.py`)
- Item management → Content models: updates (evidence: `backend/app/services/item_management.py`)
- Practice engine → Progress and sessions: persists sessions (evidence: `backend/app/services/practice/service.py`)
- Review API → Progress and sessions: reads progress (evidence: `backend/app/api/review.py`)
- Review API → Content models: reads review items (evidence: `backend/app/api/review.py`)
- JSON import → Content models: imports content (evidence: `backend/app/services/imports/service.py`)
- Database session → Neon PostgreSQL: connects to (evidence: `backend/app/db/session.py`)
