# desug/jinbi-lesson-management architecture

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

- Interactive diagram: https://gitdiagram.com/desug/jinbi-lesson-management
- Repository: https://github.com/desug/jinbi-lesson-management

## Overview

Jinbi is a split UniApp/Vue student and administrator lesson-management app backed by FastAPI, SQLAlchemy, and MySQL. The main workflow is administrator login, student/grade management, and lesson-hour adjustments that update balances and create records; students can log in to view profiles and lesson records. An optional administrator AI query feature is documented. The graph reflects indexed backend imports and documented capabilities; frontend page-to-API wiring and unsampled student services are not verified in the excerpts.

Main entry points: [`backend/app/main.py`](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/models`](https://github.com/desug/jinbi-lesson-management/tree/main/backend/app/models) (Domain models), [`backend/app/services/auth_service.py`](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/auth_service.py) (Authentication), [`backend/app/services/admin_service.py`](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/admin_service.py) (Admin operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["UniApp frontend"]
  node_app_shell["App shell<br/>[App.vue]"]
  node_admin_pages["Admin pages"]
  node_student_pages["Student pages"]
  node_login_page["Login pages<br/>[index.vue]"]
  node_frontend_api["API clients"]
end

subgraph group_api["API and identity"]
  node_backend_app["FastAPI app<br/>[main.py]"]
  node_auth_router["Auth routes<br/>[auth.py]"]
  node_admin_router["Admin routes<br/>[admin.py]"]
  node_student_router["Student routes<br/>[student.py]"]
  node_ai_router["AI route<br/>[admin_ai.py]"]
  node_auth_service["Authentication<br/>[auth_service.py]"]
end

subgraph group_domain["Lesson management"]
  node_admin_service["Admin operations<br/>[admin_service.py]"]
  node_student_service["Student queries<br/>[student_service.py]"]
  node_ai_service["Natural-language queries"]
  node_shared_logic["Shared domain helpers<br/>[common.py]"]
  node_class_types["Class types<br/>[class_types.py]"]
end

subgraph group_infra["Data and integrations"]
  node_db_session["Database sessions<br/>[database.py]"]
  node_sql_models["Domain models"]
  node_jwt_security["JWT security<br/>[security.py]"]
  node_settings["Configuration<br/>[config.py]"]
end

node_admin_user(("Administrator"))
node_student_user(("Student"))
node_mysql[("MySQL database")]
node_deepseek["DeepSeek-compatible service"]

node_backend_app -->|"registers routes"| node_auth_router
node_backend_app -->|"registers routes"| node_admin_router
node_backend_app -->|"registers routes"| node_student_router
node_backend_app -->|"registers routes"| node_ai_router
node_auth_router -->|"delegates to"| node_auth_service
node_admin_router -->|"delegates to"| node_admin_service
node_student_router -->|"delegates to"| node_student_service
node_ai_router -->|"delegates to"| node_ai_service
node_auth_service -->|"creates tokens"| node_jwt_security
node_auth_service -->|"builds profile"| node_shared_logic
node_auth_service -->|"queries accounts"| node_sql_models
node_admin_service -->|"updates records"| node_sql_models
node_admin_service -->|"uses helpers"| node_shared_logic
node_admin_service -->|"uses class rules"| node_class_types
node_student_service -->|"queries records"| node_sql_models
node_ai_service -->|"queries lesson data"| node_sql_models
node_ai_service -->|"reads configuration"| node_settings
node_db_session -->|"reads database config"| node_settings
node_sql_models -->|"uses model base"| node_db_session
node_db_session -->|"connects to"| node_mysql
node_ai_service -.->|"queries model"| node_deepseek
node_admin_user -.->|"signs in"| node_login_page
node_student_user -.->|"signs in"| node_login_page
node_admin_pages -.->|"requests data"| node_frontend_api
node_student_pages -.->|"requests data"| node_frontend_api
node_frontend_api -.->|"calls API"| node_backend_app
node_admin_user -.->|"manages lessons"| node_admin_pages
node_student_user -.->|"views lesson data"| node_student_pages

click node_app_shell "https://github.com/desug/jinbi-lesson-management/blob/main/frontend/App.vue"
click node_admin_pages "https://github.com/desug/jinbi-lesson-management/tree/main/frontend/pages/admin"
click node_student_pages "https://github.com/desug/jinbi-lesson-management/tree/main/frontend/pages/student"
click node_login_page "https://github.com/desug/jinbi-lesson-management/blob/main/frontend/pages/login/index.vue"
click node_frontend_api "https://github.com/desug/jinbi-lesson-management/tree/main/frontend/api"
click node_backend_app "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/main.py"
click node_auth_router "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/routers/auth.py"
click node_admin_router "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/routers/admin.py"
click node_student_router "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/routers/student.py"
click node_ai_router "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/routers/admin_ai.py"
click node_auth_service "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/auth_service.py"
click node_admin_service "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/admin_service.py"
click node_student_service "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/student_service.py"
click node_ai_service "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/ai_query_service.py"
click node_shared_logic "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/common.py"
click node_class_types "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/class_types.py"
click node_db_session "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/core/database.py"
click node_sql_models "https://github.com/desug/jinbi-lesson-management/tree/main/backend/app/models"
click node_jwt_security "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/core/security.py"
click node_settings "https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/core/config.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_app_shell,node_admin_pages,node_student_pages,node_login_page,node_frontend_api toneBlue
class node_backend_app,node_auth_router,node_admin_router,node_student_router,node_ai_router,node_auth_service,node_mysql toneAmber
class node_admin_service,node_student_service,node_ai_service,node_shared_logic,node_class_types toneMint
class node_db_session,node_sql_models,node_jwt_security,node_settings toneRose
class node_admin_user,node_student_user,node_deepseek toneIndigo
```

## Components

### UniApp frontend

- [App shell](https://github.com/desug/jinbi-lesson-management/blob/main/frontend/App.vue): `frontend/App.vue`
- [Admin pages](https://github.com/desug/jinbi-lesson-management/tree/main/frontend/pages/admin): `frontend/pages/admin`
- [Student pages](https://github.com/desug/jinbi-lesson-management/tree/main/frontend/pages/student): `frontend/pages/student`
- [Login pages](https://github.com/desug/jinbi-lesson-management/blob/main/frontend/pages/login/index.vue): `frontend/pages/login/index.vue`
- [API clients](https://github.com/desug/jinbi-lesson-management/tree/main/frontend/api): `frontend/api`

### API and identity

- [FastAPI app](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Admin routes](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/routers/admin.py): `backend/app/routers/admin.py`
- [Student routes](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/routers/student.py): `backend/app/routers/student.py`
- [AI route](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/routers/admin_ai.py): `backend/app/routers/admin_ai.py`
- [Authentication](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`

### Lesson management

- [Admin operations](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/admin_service.py): `backend/app/services/admin_service.py`
- [Student queries](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/student_service.py): `backend/app/services/student_service.py`
- [Natural-language queries](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/ai_query_service.py): `backend/app/services/ai_query_service.py`
- [Shared domain helpers](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/common.py): `backend/app/services/common.py`
- [Class types](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/services/class_types.py): `backend/app/services/class_types.py`

### Data and integrations

- [Database sessions](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Domain models](https://github.com/desug/jinbi-lesson-management/tree/main/backend/app/models): `backend/app/models`
- [JWT security](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Configuration](https://github.com/desug/jinbi-lesson-management/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Other components

- **Administrator**
- **Student**
- **MySQL database**
- **DeepSeek-compatible service**

## Connections

- FastAPI app → Auth routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Admin routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Student routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → AI route: registers routes (evidence: `backend/app/main.py`)
- Auth routes → Authentication: delegates to (evidence: `backend/app/routers/auth.py`)
- Admin routes → Admin operations: delegates to (evidence: `backend/app/routers/admin.py`)
- Student routes → Student queries: delegates to (evidence: `backend/app/routers/student.py`)
- AI route → Natural-language queries: delegates to (evidence: `backend/app/routers/admin_ai.py`)
- Authentication → JWT security: creates tokens (evidence: `backend/app/services/auth_service.py`)
- Authentication → Shared domain helpers: builds profile (evidence: `backend/app/services/auth_service.py`)
- Authentication → Domain models: queries accounts (evidence: `backend/app/services/auth_service.py`)
- Admin operations → Domain models: updates records (evidence: `backend/app/services/admin_service.py`)
- Admin operations → Shared domain helpers: uses helpers (evidence: `backend/app/services/admin_service.py`)
- Admin operations → Class types: uses class rules (evidence: `backend/app/services/admin_service.py`)
- Student queries → Domain models: queries records
- Natural-language queries → Domain models: queries lesson data (evidence: `backend/app/services/ai_query_service.py`)
- Natural-language queries → Configuration: reads configuration (evidence: `backend/app/services/ai_query_service.py`)
- Database sessions → Configuration: reads database config (evidence: `backend/app/core/database.py`)
- Domain models → Database sessions: uses model base (evidence: `backend/app/models/student.py`)
- Database sessions → MySQL database: connects to (evidence: `backend/app/core/database.py`)
- Natural-language queries → DeepSeek-compatible service: queries model (evidence: `README.md`)
- Administrator → Login pages: signs in
- Student → Login pages: signs in
- Admin pages → API clients: requests data
- Student pages → API clients: requests data
- API clients → FastAPI app: calls API
- Administrator → Admin pages: manages lessons (evidence: `README.md`)
- Student → Student pages: views lesson data (evidence: `README.md`)
