# anmoryli/teachagent architecture

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

- Interactive diagram: https://gitdiagram.com/anmoryli/teachagent
- Repository: https://github.com/anmoryli/teachagent

## Overview

#### Purpose and entry point
TeachAgent is a Java teaching-support backend with teacher, student, and user-facing API layers. Its executable application entry point is `src/main/java/com/anmory/teachagent/TeachAgentApplication.java`. Maven build/dependency definition is in `pom.xml`; runtime settings are centralized in `src/main/resources/application.yml`.

#### API and request boundary
HTTP requests enter role-oriented controllers: `src/main/java/com/anmory/teachagent/controller/TeacherController.java`, `src/main/java/com/anmory/teachagent/controller/StudentController.java`, and `src/main/java/com/anmory/teachagent/controller/UserController.java`. Controllers are the boundary between clients and application services, using DTOs such as `src/main/java/com/anmory/teachagent/dto/LessonPlanDto.java` and `src/main/java/com/anmory/teachagent/dto/JudgeStudentAnswerDto.java`.

#### Authentication and cross-cutting web behavior
Login enforcement is separated into `src/main/java/com/anmory/teachagent/interceptor/LoginInterceptor.java`, with interceptor registration likely managed by `src/main/java/com/anmory/teachagent/config/WebConfig.java`. Cross-origin handling, normalized responses, and error translation are handled at the web boundary through `src/main/java/com/anmory/teachagent/config/CorsConfig.java`, `src/main/java/com/anmory/teachagent/config/ResponseAdvice.java`, and `src/main/java/com/anmory/teachagent/config/GlobalExceptionHandler.java`.

#### Teaching workflow services
The core instructional domain is organized as services for courses, materials, questions, answers, practice records, and lesson plans: `src/main/java/com/anmory/teachagent/service/CourseService.java`, `src/main/java/com/anmory/teachagent/service/LessonPlanService.java`, and `src/main/java/com/anmory/teachagent/service/PracticeRecordService.java`. Their persisted domain objects include `src/main/java/com/anmory/teachagent/model/Course.java`, `src/main/java/com/anmory/teachagent/model/LessonPlan.java`, and `src/main/java/com/anmory/teachagent/model/PracticeRecord.java`.

#### AI-assisted generation and evaluation
AI-related capabilities are isolated behind service boundaries: `src/main/java/com/anmory/teachagent/service/AiService.java`, `src/main/java/com/anmory/teachagent/service/RagService.java`, and `src/main/java/com/anmory/teachagent/service/JudgePrommingService.java`. These likely support retrieval-augmented generation, prompt management, student-answer evaluation, and generated teaching artifacts; adjacent services include `src/main/java/com/anmory/teachagent/service/PPTService.java` and `src/main/java/com/anmory/teachagent/service/PromptService.java`. The actual AI provider and integration protocol are not evident from the tree.

#### Persistence, analytics, and reporting
Persistence is mediated through mapper interfaces, including `src/main/java/com/anmory/teachagent/mapper/UserMapper.java`, `src/main/java/com/anmory/teachagent/mapper/LessonPlanMapper.java`, and `src/main/java/com/anmory/teachagent/mapper/QuestionMapper.java`. Database schema and seed/query SQL are present at `src/main/resources/sql/db.sql`, `src/main/resources/sql/insert.sql`, and `src/main/resources/sql/analyse.sql`. Analytics/reporting is a distinct flow via `src/main/java/com/anmory/teachagent/service/AnalyseService.java`, `src/main/java/com/anmory/teachagent/service/StatisticsService.java`, and `src/main/java/com/anmory/teachagent/service/CountService.java`, producing metrics-oriented DTOs.

#### Client delivery and activity observability
The repository includes a bundled static browser client at `src/main/resources/static/index.html` and `src/main/resources/static/app.js`, served alongside the backend rather than as a separate frontend project. User or system activity is modeled and serviced through `src/main/java/com/anmory/teachagent/model/ActivityLog.java` and `src/main/java/com/anmory/teachagent/service/ActivityLogService.java`; request timing is cross-cutting via `src/main/java/com/anmory/teachagent/aspect/TimeAspect.java`.

Main entry points: [`src/main/java/com/anmory/teachagent/controller/TeacherController.java`](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/controller/TeacherController.java) (Teacher API), [`src/main/java/com/anmory/teachagent/service/CourseService.java`](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/CourseService.java) (Teaching Workflow Services), [`src/main/java/com/anmory/teachagent/mapper/LessonPlanMapper.java`](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/mapper/LessonPlanMapper.java) (Persistence Mappers), [`src/main/java/com/anmory/teachagent/controller/StudentController.java`](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/controller/StudentController.java) (Student API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Boundary"]
  node_client["Bundled Browser Client<br/>static client<br/>[index.html]"]
  node_web_config["Web Configuration<br/>[WebConfig.java]"]
  node_login["Login Interceptor<br/>authentication"]
  node_teacher_api["Teacher API<br/>HTTP controller"]
  node_student_api["Student API<br/>HTTP controller"]
  node_user_api["User API<br/>HTTP controller"]
  node_response_boundary["Response &amp; Error Handling<br/>web advice"]
  node_dto["Request/Response DTOs<br/>API contracts<br/>[LessonPlanDto.java]"]
end

subgraph group_teaching["Teaching Domain"]
  node_teaching_services["Teaching Workflow Services<br/>application services<br/>[CourseService.java]"]
  node_lesson_plans["Lesson Plan Service<br/>application service"]
  node_practice["Practice Records<br/>application service"]
end

subgraph group_ai["AI Capabilities"]
  node_ai_service["AI Generation<br/>AI service<br/>[AiService.java]"]
  node_rag["Retrieval-Augmented Generation<br/>AI service<br/>[RagService.java]"]
  node_answer_judge["Answer Evaluation<br/>AI service"]
end

subgraph group_data["Data &amp; Reporting"]
  node_mappers["Persistence Mappers<br/>data access"]
  node_database[("Teaching Data Store<br/>relational database<br/>[db.sql]")]
  node_analytics["Analytics &amp; Statistics<br/>reporting services"]
  node_activity["Activity Logging<br/>audit service"]
end

node_app{{"Spring Boot Application<br/>application entry point"}}
node_timing["Request Timing<br/>aspect<br/>[TimeAspect.java]"]
node_runtime_config["Runtime Settings<br/>application configuration<br/>[application.yml]"]
node_build["Maven Build<br/>build definition<br/>[pom.xml]"]

node_client -->|"teacher requests"| node_teacher_api
node_client -->|"student requests"| node_student_api
node_client -->|"user requests"| node_user_api
node_web_config -->|"registers"| node_login
node_login -.->|"protects"| node_teacher_api
node_login -.->|"protects"| node_student_api
node_teacher_api -->|"uses"| node_dto
node_student_api -->|"uses"| node_dto
node_teacher_api -->|"orchestrates"| node_teaching_services
node_student_api -->|"records practice"| node_practice
node_user_api -->|"accesses"| node_teaching_services
node_teacher_api -->|"manages"| node_lesson_plans
node_response_boundary -.->|"wraps responses"| node_teacher_api
node_teaching_services -->|"persists"| node_mappers
node_lesson_plans -->|"persists"| node_mappers
node_practice -->|"persists"| node_mappers
node_lesson_plans -->|"generates with"| node_ai_service
node_teaching_services -->|"evaluates answers"| node_answer_judge
node_ai_service -->|"uses retrieval"| node_rag
node_mappers -->|"reads and writes"| node_database
node_analytics -->|"queries metrics"| node_mappers
node_analytics -.->|"uses analysis SQL"| node_database
node_teaching_services -.->|"logs activity"| node_activity
node_timing -.->|"times requests"| node_teacher_api
node_app -->|"loads"| node_runtime_config
node_build -->|"builds"| node_app

click node_client "https://github.com/anmoryli/teachagent/blob/main/src/main/resources/static/index.html"
click node_app "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/TeachAgentApplication.java"
click node_web_config "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/config/WebConfig.java"
click node_login "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/interceptor/LoginInterceptor.java"
click node_teacher_api "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/controller/TeacherController.java"
click node_student_api "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/controller/StudentController.java"
click node_user_api "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/controller/UserController.java"
click node_response_boundary "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/config/ResponseAdvice.java"
click node_dto "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/dto/LessonPlanDto.java"
click node_teaching_services "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/CourseService.java"
click node_lesson_plans "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/LessonPlanService.java"
click node_practice "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/PracticeRecordService.java"
click node_ai_service "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/AiService.java"
click node_rag "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/RagService.java"
click node_answer_judge "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/JudgePrommingService.java"
click node_mappers "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/mapper/LessonPlanMapper.java"
click node_database "https://github.com/anmoryli/teachagent/blob/main/src/main/resources/sql/db.sql"
click node_analytics "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/AnalyseService.java"
click node_activity "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/ActivityLogService.java"
click node_timing "https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/aspect/TimeAspect.java"
click node_runtime_config "https://github.com/anmoryli/teachagent/blob/main/src/main/resources/application.yml"
click node_build "https://github.com/anmoryli/teachagent/blob/main/pom.xml"

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_client,node_web_config,node_login,node_teacher_api,node_student_api,node_user_api,node_response_boundary,node_dto toneBlue
class node_teaching_services,node_lesson_plans,node_practice toneAmber
class node_ai_service,node_rag,node_answer_judge toneMint
class node_mappers,node_database,node_analytics,node_activity toneRose
class node_app,node_timing,node_runtime_config,node_build toneNeutral
```

## Components

### Web Boundary

- [Bundled Browser Client](https://github.com/anmoryli/teachagent/blob/main/src/main/resources/static/index.html): static client · `src/main/resources/static/index.html`
- [Web Configuration](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/config/WebConfig.java): web config · Registers interception and cross-origin behavior. · `src/main/java/com/anmory/teachagent/config/WebConfig.java`
- [Login Interceptor](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/interceptor/LoginInterceptor.java): authentication · `src/main/java/com/anmory/teachagent/interceptor/LoginInterceptor.java`
- [Teacher API](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/controller/TeacherController.java): HTTP controller · `src/main/java/com/anmory/teachagent/controller/TeacherController.java`
- [Student API](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/controller/StudentController.java): HTTP controller · `src/main/java/com/anmory/teachagent/controller/StudentController.java`
- [User API](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/controller/UserController.java): HTTP controller · `src/main/java/com/anmory/teachagent/controller/UserController.java`
- [Response & Error Handling](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/config/ResponseAdvice.java): web advice · Normalizes responses and translates errors. · `src/main/java/com/anmory/teachagent/config/ResponseAdvice.java`
- [Request/Response DTOs](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/dto/LessonPlanDto.java): API contracts · `src/main/java/com/anmory/teachagent/dto/LessonPlanDto.java`

### Teaching Domain

- [Teaching Workflow Services](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/CourseService.java): application services · Manages courses, lesson plans, materials, questions, answers, and practice. · `src/main/java/com/anmory/teachagent/service/CourseService.java`
- [Lesson Plan Service](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/LessonPlanService.java): application service · `src/main/java/com/anmory/teachagent/service/LessonPlanService.java`
- [Practice Records](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/PracticeRecordService.java): application service · `src/main/java/com/anmory/teachagent/service/PracticeRecordService.java`

### AI Capabilities

- [AI Generation](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/AiService.java): AI service · Generates AI-assisted teaching artifacts. · `src/main/java/com/anmory/teachagent/service/AiService.java`
- [Retrieval-Augmented Generation](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/RagService.java): AI service · `src/main/java/com/anmory/teachagent/service/RagService.java`
- [Answer Evaluation](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/JudgePrommingService.java): AI service · `src/main/java/com/anmory/teachagent/service/JudgePrommingService.java`

### Data & Reporting

- [Persistence Mappers](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/mapper/LessonPlanMapper.java): data access · Maps users, lesson plans, questions, and related domain data. · `src/main/java/com/anmory/teachagent/mapper/LessonPlanMapper.java`
- [Teaching Data Store](https://github.com/anmoryli/teachagent/blob/main/src/main/resources/sql/db.sql): relational database · Schema, seed data, and analysis queries are maintained as SQL. · `src/main/resources/sql/db.sql`
- [Analytics & Statistics](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/AnalyseService.java): reporting services · Produces metrics from teaching and practice data. · `src/main/java/com/anmory/teachagent/service/AnalyseService.java`
- [Activity Logging](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/service/ActivityLogService.java): audit service · `src/main/java/com/anmory/teachagent/service/ActivityLogService.java`

### Other components

- [Spring Boot Application](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/TeachAgentApplication.java): application entry point · `src/main/java/com/anmory/teachagent/TeachAgentApplication.java`
- [Request Timing](https://github.com/anmoryli/teachagent/blob/main/src/main/java/com/anmory/teachagent/aspect/TimeAspect.java): aspect · `src/main/java/com/anmory/teachagent/aspect/TimeAspect.java`
- [Runtime Settings](https://github.com/anmoryli/teachagent/blob/main/src/main/resources/application.yml): application configuration · `src/main/resources/application.yml`
- [Maven Build](https://github.com/anmoryli/teachagent/blob/main/pom.xml): build definition · `pom.xml`

## Connections

- Bundled Browser Client → Teacher API: teacher requests
- Bundled Browser Client → Student API: student requests
- Bundled Browser Client → User API: user requests
- Web Configuration → Login Interceptor: registers
- Login Interceptor → Teacher API: protects
- Login Interceptor → Student API: protects
- Teacher API → Request/Response DTOs: uses
- Student API → Request/Response DTOs: uses
- Teacher API → Teaching Workflow Services: orchestrates
- Student API → Practice Records: records practice
- User API → Teaching Workflow Services: accesses
- Teacher API → Lesson Plan Service: manages
- Response & Error Handling → Teacher API: wraps responses
- Teaching Workflow Services → Persistence Mappers: persists
- Lesson Plan Service → Persistence Mappers: persists
- Practice Records → Persistence Mappers: persists
- Lesson Plan Service → AI Generation: generates with
- Teaching Workflow Services → Answer Evaluation: evaluates answers
- AI Generation → Retrieval-Augmented Generation: uses retrieval
- Persistence Mappers → Teaching Data Store: reads and writes
- Analytics & Statistics → Persistence Mappers: queries metrics
- Analytics & Statistics → Teaching Data Store: uses analysis SQL
- Teaching Workflow Services → Activity Logging: logs activity
- Request Timing → Teacher API: times requests
- Spring Boot Application → Runtime Settings: loads
- Maven Build → Spring Boot Application: builds
