# zichen0116/aisystem architecture

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

- Interactive diagram: https://gitdiagram.com/zichen0116/aisystem
- Repository: https://github.com/zichen0116/aisystem

## Overview

1. **System shape**
   - This repository contains two runtime applications: a **Python backend** in `backend/` and a **Vue 3 + Vite frontend** in `teacher-platform/`.
   - The frontend is the user-facing workbench for lesson prep, courseware, knowledge base, PPT generation, and admin screens.
   - The backend is the API/orchestration layer that owns authentication, persistence, file processing, AI workflows, and async jobs.

2. **Frontend boundary**
   - `teacher-platform/src/main.js` bootstraps a Vue SPA with **Vue Router** and **Pinia**.
   - `src/views/` holds feature pages such as `LessonPrep`, `CoursewareManage`, `KnowledgeBase`, `PersonalCenter`, and the `ppt/` flow.
   - `src/components/` is organized by domain: lesson-plan chat/editor UI, knowledge-graph widgets, big-screen/admin widgets, digital human assistant, and shared layout/navigation.
   - `src/api/` is the only direct network boundary; UI state is mostly kept in stores like `user`, `courseware`, `knowledge`, and `ppt`.

3. **Backend API boundary**
   - `backend/app/main.py` is the service entrypoint, and `backend/app/api/` is split by business area: `auth`, `lesson_plan`, `knowledge`, `courseware`, `ppt`-related endpoints, `data_analysis`, `chat`, `resource_search`, `question_generate`, `question_paper`, `digital_human`, and HTML import/export/upload flows.
   - Request/response contracts are separated into `backend/app/schemas/`, while persistence models live in `backend/app/models/`.
   - `backend/app/core/` contains shared platform concerns: config, database wiring, JWT/security, and auth helpers.

4. **Primary persisted domain data**
   - The backend stores structured application state for **users**, **chat history**, **lesson plans**, **lesson plan references**, **courseware**, **knowledge libraries/assets**, **question papers**, and **token blacklists**.
   - Alembic migrations show the domain evolving around these core entities, including lesson plans, knowledge library, question papers, user profile fields, and PPT schema/intents.
   - This is the main transactional boundary: the UI drives workflows, but durable state is owned by the backend database.

5. **Knowledge ingestion and RAG layer**
   - `backend/app/services/parsers/` handles uploaded source material from multiple formats: DOCX, PDF, image, and video.
   - Parsed content is fed into the RAG stack under `backend/app/services/rag/`, which includes text splitting, vector storage, reranking, hybrid retrieval, and a graph store.
   - The repository includes `backend/chroma_data/`, indicating a local **Chroma** vector database used for semantic retrieval.
   - This layer backs the knowledge base, reference search, and content-grounded generation features.

6. **Lesson plan generation workflow**
   - Lesson planning is a dedicated AI workflow spanning `backend/app/api/lesson_plan.py`, `backend/app/services/lesson_plan_service.py`, and `backend/app/services/ai/lesson_generator.py`.
   - Conversation state is persisted so the frontend can show history, resume prior sessions, and continue editing.
   - The endpoint set in the README (`generate`, `modify`, `list`, `detail`, `messages`, `upload`, `export`) reflects a workflow that combines chat, document references, and document output.

7. **AI orchestration layer**
   - `backend/app/services/ai/` contains the main model-facing integration points: `dashscope_service`, `vision_service`, `asr_service`, and supporting tools.
   - The `graph/` subfolder suggests a stateful orchestration pipeline for multi-step AI reasoning or agent flows.
   - This layer is where user prompts, uploaded content, and retrieval results are combined before generating lesson text, analysis, or multimodal outputs.

8. **PPT generation as a separate subplatform**
   - PPT work is unusually deep and deserves its own subsystem: `backend/app/generators/ppt/` contains schemas, routes, intent parsing, template settings, file handling, export, parsing, and Celery tasks.
   - The frontend mirrors this with a dedicated `src/views/ppt/` flow and `src/components/lesson-plan-v2/`-style rich editors/dialogs for generation, outline, preview, and history.
   - There is also a `banana_*` integration path, indicating a specialized provider or model pipeline for PPT generation.
   - This is likely one of the most important architecture boundaries in the repo: it is a multi-step document-generation pipeline rather than a simple CRUD feature.

9. **Courseware, resource search, and knowledge management**
   - `backend/app/api/courseware.py`, `knowledge.py`, `libraries.py`, and `resource_search.py` support repository and discovery features around teaching assets.
   - The frontend’s `CoursewareManage`, `KnowledgeBase`, and `KnowledgeDetail` pages are the corresponding user surfaces.
   - These features bridge structured metadata in the database with unstructured content in RAG/vector storage.

10. **Data analysis and auxiliary generation tools**
   - `backend/app/services/data_analysis/` is a self-contained pipeline for analyzer logic, chart suggestion/rendering, and LLM-assisted planning/chat.
   - On the frontend, `LessonPrepData` and related views likely consume this subsystem for analytics-oriented teaching prep.
   - `question_generate` and `question_paper` extend the platform into assessment creation rather than only lesson planning.

11. **Async jobs and infrastructure**
   - `backend/app/celery.py` and `backend/app/tasks.py` indicate background processing for long-running jobs such as export, parsing, or AI generation.
   - `backend/app/services/redis_service.py` suggests Redis is part of the async/cache/message infrastructure.
   - File and media handling is externalized through `oss_service`, while email and SMS helpers indicate notification-capable workflows.
   - `backend/media/` and `backend/chroma_data/` are runtime storage areas for assets and embeddings.

12. **External integrations and operational boundaries**
   - The backend integrates with multiple external AI/communications services: **DashScope**, **iflytek VMS**, OSS, email, SMS, and a Dify-based resource recommendation service.
   - The frontend also bundles an avatar SDK demo/library under `public/libs/` and `src/libs/`, supporting digital human or voice/avatar features.
   - These integrations are not core UI concerns; they are backend-mediated services or embedded client-side SDKs that sit at the edge of the platform.

13. **Supporting assets, docs, and tests**
   - `docs/` contains design/spec artifacts for the major subsystems, especially knowledge library, RAG reranking, lesson plan generation, 3D knowledge graph, and PPT redesign.
   - `backend/tests/` is extensive and maps closely to the main architecture: parsers, vector DB, hybrid retrieval, lesson-plan APIs, and PPT helpers.
   - These directories are important for understanding system intent, but they are not part of the runtime path.

Main entry points: [`backend/app/api`](https://github.com/zichen0116/aisystem/tree/main/backend/app/api) (API routes), [`teacher-platform/src/views`](https://github.com/zichen0116/aisystem/tree/main/teacher-platform/src/views) (Workbenches), [`backend/app/services/rag`](https://github.com/zichen0116/aisystem/tree/main/backend/app/services/rag) (RAG stack), [`teacher-platform/src/main.js`](https://github.com/zichen0116/aisystem/blob/main/teacher-platform/src/main.js) (App bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_fe_main(("App bootstrap<br/>Vue SPA entry<br/>[main.js]"))
  node_fe_router["Router<br/>route map<br/>[index.js]"]
  node_fe_stores["State stores<br/>Pinia state"]
  node_fe_api["API client<br/>network boundary"]
  node_fe_views["Workbenches<br/>feature views"]
  node_fe_components["UI components<br/>domain widgets"]
  node_fe_ppt_views["PPT flow<br/>ppt UI"]
  node_fe_ppt_util["PPT intent util<br/>client helper<br/>[pptIntent.js]"]
  node_fe_avatar_sdk["Avatar SDK<br/>client integration"]
end

subgraph group_backend["Backend API"]
  node_be_main(("Service entry<br/>Python service<br/>[main.py]"))
  node_be_api["API routes<br/>HTTP endpoints"]
  node_be_core["Core platform<br/>config/security/db"]
  node_be_models[("Domain models<br/>persistence models")]
  node_be_schemas["Contracts<br/>request/response schemas"]
  node_be_lesson["Lesson planning<br/>ai workflow"]
  node_be_ai["AI orchestration<br/>model integration"]
  node_be_rag["RAG stack<br/>retrieval pipeline"]
  node_be_parsers["Ingestion parsers<br/>document ingest"]
  node_be_ppt["PPT platform<br/>generation pipeline"]
  node_be_async["Async jobs<br/>celery/redis<br/>[celery.py]"]
  node_be_integrations["External services<br/>providers"]
end

subgraph group_storage["Runtime Storage"]
  node_store_chroma[("Chroma store<br/>vector database")]
  node_store_media["Media assets<br/>file storage"]
end

node_fe_main -->|"registers routes"| node_fe_router
node_fe_main -->|"installs state"| node_fe_stores
node_fe_main -->|"renders pages"| node_fe_views
node_fe_router -->|"maps to"| node_fe_views
node_fe_views -->|"composes"| node_fe_components
node_fe_views -->|"calls"| node_fe_api
node_fe_stores -->|"syncs via"| node_fe_api
node_fe_views -->|"specializes"| node_fe_ppt_views
node_fe_ppt_views -->|"uses"| node_fe_ppt_util
node_fe_components -->|"integrates"| node_fe_avatar_sdk
node_be_main -->|"mounts"| node_be_api
node_be_api -->|"uses"| node_be_core
node_be_api -->|"validates"| node_be_schemas
node_be_api -->|"persists"| node_be_models
node_be_api -->|"orchestrates"| node_be_lesson
node_be_api -->|"invokes"| node_be_ai
node_be_api -->|"retrieves from"| node_be_rag
node_be_api -->|"ingests"| node_be_parsers
node_be_api -->|"drives"| node_be_ppt
node_be_lesson -->|"grounds on"| node_be_rag
node_be_lesson -->|"generates with"| node_be_ai
node_be_rag -->|"stores embeddings"| node_store_chroma
node_be_ppt -->|"queues jobs"| node_be_async
node_be_ai -->|"offloads"| node_be_async
node_be_integrations -->|"reads/writes"| node_store_media
node_be_ppt -->|"uses providers"| node_be_integrations
node_be_rag -->|"recommends via"| node_be_integrations

click node_fe_main "https://github.com/zichen0116/aisystem/blob/main/teacher-platform/src/main.js"
click node_fe_router "https://github.com/zichen0116/aisystem/blob/main/teacher-platform/src/router/index.js"
click node_fe_stores "https://github.com/zichen0116/aisystem/tree/main/teacher-platform/src/stores"
click node_fe_api "https://github.com/zichen0116/aisystem/tree/main/teacher-platform/src/api"
click node_fe_views "https://github.com/zichen0116/aisystem/tree/main/teacher-platform/src/views"
click node_fe_components "https://github.com/zichen0116/aisystem/tree/main/teacher-platform/src/components"
click node_fe_ppt_views "https://github.com/zichen0116/aisystem/tree/main/teacher-platform/src/views/ppt"
click node_fe_ppt_util "https://github.com/zichen0116/aisystem/blob/main/teacher-platform/src/utils/pptIntent.js"
click node_fe_avatar_sdk "https://github.com/zichen0116/aisystem/blob/main/teacher-platform/src/libs/avatar-sdk-web_3.1.2.1002"
click node_be_main "https://github.com/zichen0116/aisystem/blob/main/backend/app/main.py"
click node_be_api "https://github.com/zichen0116/aisystem/tree/main/backend/app/api"
click node_be_core "https://github.com/zichen0116/aisystem/tree/main/backend/app/core"
click node_be_models "https://github.com/zichen0116/aisystem/tree/main/backend/app/models"
click node_be_schemas "https://github.com/zichen0116/aisystem/tree/main/backend/app/schemas"
click node_be_lesson "https://github.com/zichen0116/aisystem/blob/main/backend/app/services/lesson_plan_service.py"
click node_be_ai "https://github.com/zichen0116/aisystem/tree/main/backend/app/services/ai"
click node_be_rag "https://github.com/zichen0116/aisystem/tree/main/backend/app/services/rag"
click node_be_parsers "https://github.com/zichen0116/aisystem/tree/main/backend/app/services/parsers"
click node_be_ppt "https://github.com/zichen0116/aisystem/tree/main/backend/app/generators/ppt"
click node_be_async "https://github.com/zichen0116/aisystem/blob/main/backend/app/celery.py"
click node_be_integrations "https://github.com/zichen0116/aisystem/tree/main/backend/app/services"
click node_store_chroma "https://github.com/zichen0116/aisystem/tree/main/backend/chroma_data"
click node_store_media "https://github.com/zichen0116/aisystem/tree/main/backend/media"

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_fe_main,node_fe_router,node_fe_stores,node_fe_api,node_fe_views,node_fe_components,node_fe_ppt_views,node_fe_ppt_util,node_fe_avatar_sdk toneBlue
class node_be_main,node_be_api,node_be_core,node_be_models,node_be_schemas,node_be_lesson,node_be_ai,node_be_rag,node_be_parsers,node_be_ppt,node_be_async,node_be_integrations toneAmber
class node_store_chroma,node_store_media toneMint
```

## Components

### Frontend SPA

Vue 3 + Vite teaching workbench and user/admin surfaces.

- [App bootstrap](https://github.com/zichen0116/aisystem/blob/main/teacher-platform/src/main.js): Vue SPA entry · Bootstraps the frontend with router, Pinia, and global app shell. · `teacher-platform/src/main.js`
- [Router](https://github.com/zichen0116/aisystem/blob/main/teacher-platform/src/router/index.js): route map · Defines SPA navigation across workbench, admin, PPT, and support screens. · `teacher-platform/src/router/index.js`
- [State stores](https://github.com/zichen0116/aisystem/tree/main/teacher-platform/src/stores): Pinia state · Central client state for user, courseware, knowledge, PPT, and admin digital human flows. · `teacher-platform/src/stores`
- [API client](https://github.com/zichen0116/aisystem/tree/main/teacher-platform/src/api): network boundary · Typed frontend HTTP boundary for backend-driven workflows. · `teacher-platform/src/api`
- [Workbenches](https://github.com/zichen0116/aisystem/tree/main/teacher-platform/src/views): feature views · Primary user-facing pages for lesson prep, courseware, knowledge, resource search, personal center, and PPT. · `teacher-platform/src/views`
- [UI components](https://github.com/zichen0116/aisystem/tree/main/teacher-platform/src/components): domain widgets · Reusable lesson-plan, knowledge-graph, layout, admin dashboard, and digital human components. · `teacher-platform/src/components`
- [PPT flow](https://github.com/zichen0116/aisystem/tree/main/teacher-platform/src/views/ppt): ppt UI · Dedicated PPT generation screens for description, outline, preview, history, and orchestration. · `teacher-platform/src/views/ppt`
- [PPT intent util](https://github.com/zichen0116/aisystem/blob/main/teacher-platform/src/utils/pptIntent.js): client helper · Frontend helper for PPT intent parsing and UI coordination. · `teacher-platform/src/utils/pptIntent.js`
- [Avatar SDK](https://github.com/zichen0116/aisystem/blob/main/teacher-platform/src/libs/avatar-sdk-web_3.1.2.1002): client integration · Embedded avatar/voice SDK bundle supporting digital human experiences. · `teacher-platform/src/libs/avatar-sdk-web_3.1.2.1002`

### Backend API

FastAPI-style Python service with orchestration, persistence, AI, and async jobs.

- [Service entry](https://github.com/zichen0116/aisystem/blob/main/backend/app/main.py): Python service · Backend application entrypoint and service bootstrap. · `backend/app/main.py`
- [API routes](https://github.com/zichen0116/aisystem/tree/main/backend/app/api): HTTP endpoints · Business APIs for auth, lesson plans, knowledge, courseware, chat, data analysis, PPT, search, and digital human. · `backend/app/api`
- [Core platform](https://github.com/zichen0116/aisystem/tree/main/backend/app/core): config/security/db · Shared platform wiring for configuration, database, JWT, and security helpers. · `backend/app/core`
- [Domain models](https://github.com/zichen0116/aisystem/tree/main/backend/app/models): persistence models · Transactional entities for users, chat history, lesson plans, courseware, knowledge assets, question papers, and token blacklist. · `backend/app/models`
- [Contracts](https://github.com/zichen0116/aisystem/tree/main/backend/app/schemas): request/response schemas · API payload contracts and validation models. · `backend/app/schemas`
- [Lesson planning](https://github.com/zichen0116/aisystem/blob/main/backend/app/services/lesson_plan_service.py): ai workflow · Lesson plan generation, edit, persistence, and export workflow. · `backend/app/services/lesson_plan_service.py`
- [AI orchestration](https://github.com/zichen0116/aisystem/tree/main/backend/app/services/ai): model integration · Model-facing services, multimodal tooling, and graph-based orchestration. · `backend/app/services/ai`
- [RAG stack](https://github.com/zichen0116/aisystem/tree/main/backend/app/services/rag): retrieval pipeline · Text splitting, vector storage, reranking, hybrid retrieval, and graph store for grounded generation. · `backend/app/services/rag`
- [Ingestion parsers](https://github.com/zichen0116/aisystem/tree/main/backend/app/services/parsers): document ingest · Format parsers for DOCX, PDF, image, and video sources. · `backend/app/services/parsers`
- [PPT platform](https://github.com/zichen0116/aisystem/tree/main/backend/app/generators/ppt): generation pipeline · Deep PPT generation subsystem with schema, intent parsing, templates, export, parse, and Celery tasks. · `backend/app/generators/ppt`
- [Async jobs](https://github.com/zichen0116/aisystem/blob/main/backend/app/celery.py): celery/redis · Background task execution and Redis-backed infrastructure for long-running jobs. · `backend/app/celery.py`
- [External services](https://github.com/zichen0116/aisystem/tree/main/backend/app/services): providers · DashScope, vision, ASR, OSS, email, SMS, Dify resource recommendation, and other edge integrations. · `backend/app/services`

### Runtime Storage

Local persisted vectors and media used by the backend.

- [Chroma store](https://github.com/zichen0116/aisystem/tree/main/backend/chroma_data): vector database · Local Chroma persistence for semantic retrieval. · `backend/chroma_data`
- [Media assets](https://github.com/zichen0116/aisystem/tree/main/backend/media): file storage · Runtime media and font assets used by backend exports and processing. · `backend/media`

## Connections

- App bootstrap → Router: registers routes · The SPA bootstraps navigation.
- App bootstrap → State stores: installs state · Pinia stores are attached at startup.
- App bootstrap → Workbenches: renders pages · App shell hosts routed workbench views.
- Router → Workbenches: maps to · Routes resolve to lesson prep, courseware, knowledge, PPT, and admin pages.
- Workbenches → UI components: composes · Feature pages are built from shared and domain widgets.
- Workbenches → API client: calls · Pages fetch and mutate backend state through API clients.
- State stores → API client: syncs via · Client state is hydrated and persisted through network calls.
- Workbenches → PPT flow: specializes · PPT generation has its own dedicated UI flow.
- PPT flow → PPT intent util: uses · PPT screens share intent parsing helpers.
- UI components → Avatar SDK: integrates · Digital human components depend on the embedded avatar SDK.
- Service entry → API routes: mounts · Service entrypoint wires all HTTP routes.
- API routes → Core platform: uses · Routes rely on common auth, config, and database services.
- API routes → Contracts: validates · Endpoints exchange structured contracts.
- API routes → Domain models: persists · Business APIs read and write domain entities.
- API routes → Lesson planning: orchestrates · Lesson plan endpoints delegate to the lesson workflow.
- API routes → AI orchestration: invokes · Chat, generation, vision, and analysis endpoints call AI services.
- API routes → RAG stack: retrieves from · Knowledge and search endpoints use the retrieval stack.
- API routes → Ingestion parsers: ingests · Upload and import endpoints route content into parsers.
- API routes → PPT platform: drives · PPT endpoints enter the document-generation pipeline.
- Lesson planning → RAG stack: grounds on · Lesson generation uses retrieved references and knowledge context.
- Lesson planning → AI orchestration: generates with · Lesson workflow calls model-facing services and graph orchestration.
- RAG stack → Chroma store: stores embeddings · Semantic retrieval persists vectors locally.
- PPT platform → Async jobs: queues jobs · PPT generation and export use background processing.
- AI orchestration → Async jobs: offloads · Long-running AI tasks can be executed asynchronously.
- External services → Media assets: reads/writes · Externalized file and media handling uses runtime asset storage.
- PPT platform → External services: uses providers · PPT generation depends on specialized model/provider integrations.
- RAG stack → External services: recommends via · Retrieval and recommendation flows can call external services.
