# quang1907/kanji architecture

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

- Interactive diagram: https://gitdiagram.com/quang1907/kanji
- Repository: https://github.com/quang1907/kanji

## Overview

This is a Japanese-learning application: its backend exposes kanji, vocabulary, grammar, and lesson content APIs, while the frontend includes kanji browsing and offline synchronization. The sampled kanji path shows the request-to-storage workflow and frontend sync ownership. Other content domains are documented by routes and controllers in the tree, but their service/repository wiring was not sampled; their internal links are therefore omitted.

Main entry points: [`frontend/src/services/kanji-sync.service.ts`](https://github.com/quang1907/kanji/blob/main/frontend/src/services/kanji-sync.service.ts) (Kanji sync), [`backend/src/app.ts`](https://github.com/quang1907/kanji/blob/main/backend/src/app.ts) (Other content APIs), [`frontend/src/pages/user/KanjiPage.tsx`](https://github.com/quang1907/kanji/blob/main/frontend/src/pages/user/KanjiPage.tsx) (Kanji pages), [`frontend/src/services/kanji.service.ts`](https://github.com/quang1907/kanji/blob/main/frontend/src/services/kanji.service.ts) (Kanji service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend"]
  node_app["App shell<br/>[App.tsx]"]
  node_kanji_pages["Kanji pages<br/>[KanjiPage.tsx]"]
  node_kanji_service["Kanji service<br/>[kanji.service.ts]"]
  node_kanji_local["Local kanji store"]
  node_sync_service["Kanji sync"]
  node_sync_metadata["Sync metadata"]
  node_api_client["API client<br/>[apiClient.ts]"]
  node_kanji_api_repo["Kanji API adapter"]
  node_browser_db[("Browser database<br/>[db.ts]")]
  node_http_client["HTTP transport<br/>[api-client.ts]"]
end

subgraph group_server["Learning API"]
  node_api["Express API<br/>[app.ts]"]
  node_kanji_routes["Kanji routes<br/>[kanji.routes.ts]"]
  node_kanji_controller["Kanji controller"]
  node_kanji_service_backend["Kanji service<br/>[kanji.service.ts]"]
  node_kanji_repo["Kanji repository"]
  node_content_api["Other content APIs<br/>[app.ts]"]
  node_vocab_routes["Vocabulary routes"]
  node_grammar_routes["Grammar routes<br/>[grammar.routes.ts]"]
  node_lesson_routes["Lesson routes<br/>[lesson.routes.ts]"]
end

subgraph group_storage["Data storage"]
  node_mysql_pool[("MySQL pool<br/>[database.ts]")]
  node_schema["Learning schema<br/>[schema.ts]"]
end

node_learner(("Learner"))
node_mysql[("MySQL database")]

node_learner -->|"browses"| node_kanji_pages
node_kanji_pages -->|"requests kanji"| node_kanji_service
node_kanji_service -->|"reads local data"| node_kanji_local
node_app -->|"starts sync"| node_sync_service
node_sync_service -->|"fetches changes"| node_kanji_api_repo
node_sync_service -->|"reads/writes cursor"| node_sync_metadata
node_sync_service -->|"updates records"| node_browser_db
node_kanji_local -->|"reads/writes"| node_browser_db
node_kanji_api_repo -->|"calls"| node_api_client
node_api_client -->|"sends requests"| node_http_client
node_http_client -->|"HTTP"| node_api
node_api -->|"dispatches"| node_kanji_routes
node_kanji_routes -->|"routes requests"| node_kanji_controller
node_kanji_controller -->|"invokes"| node_kanji_service_backend
node_kanji_service_backend -->|"queries"| node_kanji_repo
node_kanji_repo -->|"executes SQL"| node_mysql_pool
node_mysql_pool -->|"connects"| node_mysql
node_api -->|"dispatches"| node_content_api
node_content_api -->|"routes vocabulary"| node_vocab_routes
node_content_api -->|"routes grammar"| node_grammar_routes
node_content_api -->|"routes lessons"| node_lesson_routes
node_schema -->|"defines schema"| node_mysql

click node_app "https://github.com/quang1907/kanji/blob/main/frontend/src/App.tsx"
click node_kanji_pages "https://github.com/quang1907/kanji/blob/main/frontend/src/pages/user/KanjiPage.tsx"
click node_kanji_service "https://github.com/quang1907/kanji/blob/main/frontend/src/services/kanji.service.ts"
click node_kanji_local "https://github.com/quang1907/kanji/blob/main/frontend/src/repositories/kanji-local.repository.ts"
click node_sync_service "https://github.com/quang1907/kanji/blob/main/frontend/src/services/kanji-sync.service.ts"
click node_sync_metadata "https://github.com/quang1907/kanji/blob/main/frontend/src/repositories/sync-metadata.repository.ts"
click node_api_client "https://github.com/quang1907/kanji/blob/main/frontend/src/services/api/apiClient.ts"
click node_kanji_api_repo "https://github.com/quang1907/kanji/blob/main/frontend/src/repositories/kanji-api.repository.ts"
click node_browser_db "https://github.com/quang1907/kanji/blob/main/frontend/src/database/db.ts"
click node_http_client "https://github.com/quang1907/kanji/blob/main/frontend/src/api/api-client.ts"
click node_api "https://github.com/quang1907/kanji/blob/main/backend/src/app.ts"
click node_kanji_routes "https://github.com/quang1907/kanji/blob/main/backend/src/routes/kanji.routes.ts"
click node_kanji_controller "https://github.com/quang1907/kanji/blob/main/backend/src/controllers/kanji.controller.ts"
click node_kanji_service_backend "https://github.com/quang1907/kanji/blob/main/backend/src/services/kanji.service.ts"
click node_kanji_repo "https://github.com/quang1907/kanji/blob/main/backend/src/repositories/kanji.repository.ts"
click node_content_api "https://github.com/quang1907/kanji/blob/main/backend/src/app.ts"
click node_vocab_routes "https://github.com/quang1907/kanji/blob/main/backend/src/routes/vocabulary.routes.ts"
click node_grammar_routes "https://github.com/quang1907/kanji/blob/main/backend/src/routes/grammar.routes.ts"
click node_lesson_routes "https://github.com/quang1907/kanji/blob/main/backend/src/routes/lesson.routes.ts"
click node_mysql_pool "https://github.com/quang1907/kanji/blob/main/database/config/database.ts"
click node_schema "https://github.com/quang1907/kanji/blob/main/database/schema.ts"

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,node_kanji_pages,node_kanji_service,node_kanji_local,node_sync_service,node_sync_metadata,node_api_client,node_kanji_api_repo,node_browser_db,node_http_client toneBlue
class node_api,node_kanji_routes,node_kanji_controller,node_kanji_service_backend,node_kanji_repo,node_content_api,node_vocab_routes,node_grammar_routes,node_lesson_routes,node_mysql toneAmber
class node_mysql_pool,node_schema toneMint
class node_learner toneIndigo
```

## Components

### Frontend

- [App shell](https://github.com/quang1907/kanji/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Kanji pages](https://github.com/quang1907/kanji/blob/main/frontend/src/pages/user/KanjiPage.tsx): `frontend/src/pages/user/KanjiPage.tsx`
- [Kanji service](https://github.com/quang1907/kanji/blob/main/frontend/src/services/kanji.service.ts): `frontend/src/services/kanji.service.ts`
- [Local kanji store](https://github.com/quang1907/kanji/blob/main/frontend/src/repositories/kanji-local.repository.ts): `frontend/src/repositories/kanji-local.repository.ts`
- [Kanji sync](https://github.com/quang1907/kanji/blob/main/frontend/src/services/kanji-sync.service.ts): `frontend/src/services/kanji-sync.service.ts`
- [Sync metadata](https://github.com/quang1907/kanji/blob/main/frontend/src/repositories/sync-metadata.repository.ts): `frontend/src/repositories/sync-metadata.repository.ts`
- [API client](https://github.com/quang1907/kanji/blob/main/frontend/src/services/api/apiClient.ts): `frontend/src/services/api/apiClient.ts`
- [Kanji API adapter](https://github.com/quang1907/kanji/blob/main/frontend/src/repositories/kanji-api.repository.ts): `frontend/src/repositories/kanji-api.repository.ts`
- [Browser database](https://github.com/quang1907/kanji/blob/main/frontend/src/database/db.ts): `frontend/src/database/db.ts`
- [HTTP transport](https://github.com/quang1907/kanji/blob/main/frontend/src/api/api-client.ts): `frontend/src/api/api-client.ts`

### Learning API

- [Express API](https://github.com/quang1907/kanji/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Kanji routes](https://github.com/quang1907/kanji/blob/main/backend/src/routes/kanji.routes.ts): `backend/src/routes/kanji.routes.ts`
- [Kanji controller](https://github.com/quang1907/kanji/blob/main/backend/src/controllers/kanji.controller.ts): `backend/src/controllers/kanji.controller.ts`
- [Kanji service](https://github.com/quang1907/kanji/blob/main/backend/src/services/kanji.service.ts): `backend/src/services/kanji.service.ts`
- [Kanji repository](https://github.com/quang1907/kanji/blob/main/backend/src/repositories/kanji.repository.ts): `backend/src/repositories/kanji.repository.ts`
- [Other content APIs](https://github.com/quang1907/kanji/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Vocabulary routes](https://github.com/quang1907/kanji/blob/main/backend/src/routes/vocabulary.routes.ts): `backend/src/routes/vocabulary.routes.ts`
- [Grammar routes](https://github.com/quang1907/kanji/blob/main/backend/src/routes/grammar.routes.ts): `backend/src/routes/grammar.routes.ts`
- [Lesson routes](https://github.com/quang1907/kanji/blob/main/backend/src/routes/lesson.routes.ts): `backend/src/routes/lesson.routes.ts`

### Data storage

- [MySQL pool](https://github.com/quang1907/kanji/blob/main/database/config/database.ts): `database/config/database.ts`
- [Learning schema](https://github.com/quang1907/kanji/blob/main/database/schema.ts): `database/schema.ts`

### Other components

- **Learner**
- **MySQL database**

## Connections

- Learner → Kanji pages: browses
- Kanji pages → Kanji service: requests kanji
- Kanji service → Local kanji store: reads local data
- App shell → Kanji sync: starts sync
- Kanji sync → Kanji API adapter: fetches changes
- Kanji sync → Sync metadata: reads/writes cursor
- Kanji sync → Browser database: updates records
- Local kanji store → Browser database: reads/writes
- Kanji API adapter → API client: calls
- API client → HTTP transport: sends requests
- HTTP transport → Express API: HTTP
- Express API → Kanji routes: dispatches
- Kanji routes → Kanji controller: routes requests
- Kanji controller → Kanji service: invokes
- Kanji service → Kanji repository: queries
- Kanji repository → MySQL pool: executes SQL
- MySQL pool → MySQL database: connects
- Express API → Other content APIs: dispatches
- Other content APIs → Vocabulary routes: routes vocabulary
- Other content APIs → Grammar routes: routes grammar
- Other content APIs → Lesson routes: routes lessons
- Learning schema → MySQL database: defines schema