# xinyu-li/flora architecture

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

- Interactive diagram: https://gitdiagram.com/xinyu-li/flora
- Repository: https://github.com/xinyu-li/flora

## Overview

FLoRA is a research-oriented learning analytics backend: it captures learning activity, derives self-regulation signals, and supports learners with personalized assistance. Its product capabilities also include writing annotations, course/background-document search, teacher and administrator management, and data export. The graph combines README-described capabilities with sampled controller, processing, storage, and search behavior; unsampled subsystem wiring is intentionally left out.

Main entry points: [`src/main/java/com/monash/flora_backend/controller/HomeController.java`](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/HomeController.java) (Learning API), [`src/main/java/com/monash/flora_backend/controller/TraceDataController.java`](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/TraceDataController.java) (Trace API), [`src/main/java/com/monash/flora_backend/controller/manage/DataManagementController.java`](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/manage/DataManagementController.java) (Management API), [`src/main/java/com/monash/flora_backend/service_func/ExportExcelFileStorageService.java`](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/service_func/ExportExcelFileStorageService.java) (Analytics export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning support"]
  node_home["Learning API"]
  node_chat["Chat API"]
  node_voice["Voice requests"]
  node_annotations["Writing annotations<br/>[Annotation.java]"]
  node_scaffolding["Personalized scaffolds"]
  node_background["Document search"]
  node_backgroundapi["Course documents API"]
end

subgraph group_analytics["Trace analytics"]
  node_traceapi["Trace API"]
  node_traceprocess["SRL processing"]
  node_traceentity["Trace records<br/>[TraceData.java]"]
end

subgraph group_admin["Course operations"]
  node_teacherapi["Teacher tools"]
  node_manageapi["Management API"]
  node_moodle["Moodle data<br/>[MdlCourse.java]"]
  node_export["Analytics export"]
end

subgraph group_platform["Persistence and integrations"]
  node_files["File storage"]
  node_sql[("Application database")]
  node_redis[("Redis cache")]
  node_auth["JWT security"]
end

node_student(("Learner"))
node_teacher(("Teacher"))
node_adminuser(("Administrator"))
node_llm{{"LLM service"}}
node_elastic[("Elasticsearch")]

node_student -->|"requests support"| node_home
node_student -->|"sends messages"| node_chat
node_student -->|"submits speech"| node_voice
node_teacher -->|"uses tools"| node_teacherapi
node_adminuser -->|"manages data"| node_manageapi
node_home -->|"requests scaffold"| node_scaffolding
node_home -.->|"requests generation"| node_llm
node_chat -.->|"sends prompts"| node_llm
node_home -->|"saves documents"| node_background
node_home -->|"saves annotations"| node_annotations
node_background -->|"indexes and searches"| node_elastic
node_traceapi -->|"handles trace data"| node_traceentity
node_traceprocess -->|"updates process labels"| node_traceentity
node_teacherapi -->|"views trace data"| node_traceapi
node_manageapi -->|"starts exports"| node_export
node_export -->|"writes archives"| node_files
node_export -->|"exports records"| node_sql
node_home -->|"reads and writes"| node_sql
node_traceapi -->|"persists traces"| node_sql
node_manageapi -->|"manages course data"| node_moodle
node_home -->|"caches scaffold status"| node_redis
node_student -->|"authenticates"| node_auth
node_teacher -->|"authenticates"| node_auth
node_adminuser -->|"authenticates"| node_auth

click node_home "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/HomeController.java"
click node_chat "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/ChatController.java"
click node_voice "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/VoiceRequestController.java"
click node_annotations "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/dao/entity/Annotation.java"
click node_scaffolding "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/service/IGptScaffoldService.java"
click node_traceapi "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/TraceDataController.java"
click node_traceprocess "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/service_func/ActionAndProcessService.java"
click node_traceentity "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/dao/entity/TraceData.java"
click node_teacherapi "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/TeacherEndController.java"
click node_manageapi "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/manage/DataManagementController.java"
click node_moodle "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/dao/entity/MdlCourse.java"
click node_export "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/service_func/ExportExcelFileStorageService.java"
click node_files "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/service_func/FileStorageService.java"
click node_background "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/service/impl/BackgroundDocService.java"
click node_backgroundapi "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/HomeController.java"
click node_sql "https://github.com/xinyu-li/flora/tree/main/src/main/java/com/monash/flora_backend/dao/mapper"
click node_redis "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/config/cache/MyRedisCacheManager.java"
click node_auth "https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/config/filter/JwtAuthenticationFilter.java"

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_home,node_chat,node_voice,node_annotations,node_scaffolding,node_background,node_backgroundapi toneBlue
class node_traceapi,node_traceprocess,node_traceentity,node_elastic toneAmber
class node_teacherapi,node_manageapi,node_moodle,node_export toneMint
class node_files,node_sql,node_redis,node_auth toneRose
class node_student,node_teacher,node_adminuser,node_llm toneIndigo
```

## Components

### Learning support

- [Learning API](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/HomeController.java): `src/main/java/com/monash/flora_backend/controller/HomeController.java`
- [Chat API](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/ChatController.java): `src/main/java/com/monash/flora_backend/controller/ChatController.java`
- [Voice requests](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/VoiceRequestController.java): `src/main/java/com/monash/flora_backend/controller/VoiceRequestController.java`
- [Writing annotations](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/dao/entity/Annotation.java): `src/main/java/com/monash/flora_backend/dao/entity/Annotation.java`
- [Personalized scaffolds](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/service/IGptScaffoldService.java): `src/main/java/com/monash/flora_backend/service/IGptScaffoldService.java`
- [Document search](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/service/impl/BackgroundDocService.java): `src/main/java/com/monash/flora_backend/service/impl/BackgroundDocService.java`
- [Course documents API](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/HomeController.java): `src/main/java/com/monash/flora_backend/controller/HomeController.java`

### Trace analytics

- [Trace API](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/TraceDataController.java): `src/main/java/com/monash/flora_backend/controller/TraceDataController.java`
- [SRL processing](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/service_func/ActionAndProcessService.java): `src/main/java/com/monash/flora_backend/service_func/ActionAndProcessService.java`
- [Trace records](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/dao/entity/TraceData.java): `src/main/java/com/monash/flora_backend/dao/entity/TraceData.java`

### Course operations

- [Teacher tools](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/TeacherEndController.java): `src/main/java/com/monash/flora_backend/controller/TeacherEndController.java`
- [Management API](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/controller/manage/DataManagementController.java): `src/main/java/com/monash/flora_backend/controller/manage/DataManagementController.java`
- [Moodle data](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/dao/entity/MdlCourse.java): `src/main/java/com/monash/flora_backend/dao/entity/MdlCourse.java`
- [Analytics export](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/service_func/ExportExcelFileStorageService.java): `src/main/java/com/monash/flora_backend/service_func/ExportExcelFileStorageService.java`

### Persistence and integrations

- [File storage](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/service_func/FileStorageService.java): `src/main/java/com/monash/flora_backend/service_func/FileStorageService.java`
- [Application database](https://github.com/xinyu-li/flora/tree/main/src/main/java/com/monash/flora_backend/dao/mapper): `src/main/java/com/monash/flora_backend/dao/mapper`
- [Redis cache](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/config/cache/MyRedisCacheManager.java): `src/main/java/com/monash/flora_backend/config/cache/MyRedisCacheManager.java`
- [JWT security](https://github.com/xinyu-li/flora/blob/main/src/main/java/com/monash/flora_backend/config/filter/JwtAuthenticationFilter.java): `src/main/java/com/monash/flora_backend/config/filter/JwtAuthenticationFilter.java`

### Other components

- **Learner**
- **Teacher**
- **Administrator**
- **LLM service**
- **Elasticsearch**

## Connections

- Learner → Learning API: requests support
- Learner → Chat API: sends messages
- Learner → Voice requests: submits speech
- Teacher → Teacher tools: uses tools
- Administrator → Management API: manages data
- Learning API → Personalized scaffolds: requests scaffold
- Learning API → LLM service: requests generation
- Chat API → LLM service: sends prompts
- Learning API → Document search: saves documents
- Learning API → Writing annotations: saves annotations
- Document search → Elasticsearch: indexes and searches
- Trace API → Trace records: handles trace data
- SRL processing → Trace records: updates process labels
- Teacher tools → Trace API: views trace data
- Management API → Analytics export: starts exports
- Analytics export → File storage: writes archives
- Analytics export → Application database: exports records
- Learning API → Application database: reads and writes
- Trace API → Application database: persists traces
- Management API → Moodle data: manages course data
- Learning API → Redis cache: caches scaffold status
- Learner → JWT security: authenticates
- Teacher → JWT security: authenticates
- Administrator → JWT security: authenticates