# dangothecat/vieva architecture

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

- Interactive diagram: https://gitdiagram.com/dangothecat/vieva
- Repository: https://github.com/dangothecat/vieva

## Overview

AIVES is an oral-exam platform with lecturer workflows for course-material ingestion and AI-assisted question-bank management, student voice exams, and administrator account and speech configuration. The repository includes a React client and a Spring modular-monolith backend. The graph emphasizes the documented RAG workflow and sampled account-management flow; exam-session, streaming, grading, and speech-configuration capabilities are documented in the README but lack corresponding sampled implementation files, so their links are documentation-based rather than source-verified.

Main entry points: [`FE/src/api/client.js`](https://github.com/dangothecat/vieva/blob/main/FE/src/api/client.js) (API client), [`FE/src/pages/AdminUserPage.jsx`](https://github.com/dangothecat/vieva/blob/main/FE/src/pages/AdminUserPage.jsx) (Admin user management), [`BE/src/main/java/com/example/vieva/infrastructure/database`](https://github.com/dangothecat/vieva/tree/main/BE/src/main/java/com/example/vieva/infrastructure/database) (Question and document store), [`FE/src/App.jsx`](https://github.com/dangothecat/vieva/blob/main/FE/src/App.jsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["Web application<br/>[App.jsx]"]
  node_authui["Login and registration<br/>[LoginPage.jsx]"]
end

subgraph group_identity["Identity and admin"]
  node_authstate["Authentication state<br/>[AuthContext.jsx]"]
  node_httpclient["API client<br/>[client.js]"]
  node_authapi["Authentication API<br/>[authApi.js]"]
  node_userapi["User API<br/>[userApi.js]"]
  node_adminpage["Admin user management<br/>[AdminUserPage.jsx]"]
  node_usermodal["User management dialogs"]
  node_usertable["User table<br/>[UserTable.jsx]"]
  node_adminapi["Admin user API<br/>[adminUserApi.js]"]
  node_admincontroller["Admin user endpoints"]
  node_adminservice["Admin user use case"]
  node_authcontroller["Authentication endpoints"]
  node_authservice["Authentication use case"]
end

subgraph group_questionbank["Question bank and RAG"]
  node_documents["Course documents"]
  node_indexworker["Async indexing worker"]
  node_docparser["Document parsing"]
  node_embedding["Embedding service"]
  node_questiongen["RAG question generation"]
  node_questionbankservice["Question bank use case"]
  node_questioncontroller["Lecturer question endpoints"]
  node_llm{{"LLM service"}}
end

subgraph group_oralexam["Oral examination"]
  node_oralworkflow["Exam attempts and snapshots"]
  node_audio["Real-time speech interaction"]
  node_adaptive["Adaptive follow-up and grading"]
  node_speechservices{{"STT and TTS services"}}
end

subgraph group_backend["Backend foundations"]
  node_storage[("Question and document store")]
  node_database[("PostgreSQL")]
end

node_user(("User"))

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_authui
node_authui -->|"authenticates via"| node_authstate
node_authstate -->|"calls"| node_authapi
node_authstate -->|"loads profile"| node_userapi
node_authapi -->|"sends requests"| node_httpclient
node_userapi -->|"sends requests"| node_httpclient
node_httpclient -.->|"REST API"| node_authcontroller
node_webapp -->|"routes to"| node_adminpage
node_adminpage -->|"loads and updates"| node_adminapi
node_adminpage -->|"renders"| node_usertable
node_adminpage -->|"opens"| node_usermodal
node_usermodal -->|"submits changes"| node_adminapi
node_adminapi -->|"sends requests"| node_httpclient
node_httpclient -.->|"REST API"| node_admincontroller
node_admincontroller -.->|"delegates"| node_adminservice
node_authcontroller -.->|"delegates"| node_authservice
node_user -->|"uploads course material"| node_documents
node_documents -->|"indexes asynchronously"| node_indexworker
node_indexworker -->|"extracts text"| node_docparser
node_indexworker -->|"creates vectors"| node_embedding
node_documents -.->|"stores indexed material"| node_storage
node_user -->|"reviews questions"| node_questioncontroller
node_questioncontroller -.->|"manages drafts and approval"| node_questionbankservice
node_questionbankservice -->|"requests generation"| node_questiongen
node_questiongen -->|"retrieves context"| node_embedding
node_questiongen -->|"generates questions"| node_llm
node_questionbankservice -.->|"persists questions"| node_storage
node_user -->|"starts exam"| node_oralworkflow
node_oralworkflow -->|"starts voice session"| node_audio
node_audio -->|"streams audio"| node_speechservices
node_audio -->|"submits transcript"| node_adaptive
node_adaptive -->|"evaluates and follows up"| node_llm
node_oralworkflow -->|"stores exam evidence"| node_storage
node_storage -.->|"persists records"| node_database

click node_webapp "https://github.com/dangothecat/vieva/blob/main/FE/src/App.jsx"
click node_authui "https://github.com/dangothecat/vieva/blob/main/FE/src/pages/LoginPage.jsx"
click node_authstate "https://github.com/dangothecat/vieva/blob/main/FE/src/context/AuthContext.jsx"
click node_httpclient "https://github.com/dangothecat/vieva/blob/main/FE/src/api/client.js"
click node_authapi "https://github.com/dangothecat/vieva/blob/main/FE/src/api/authApi.js"
click node_userapi "https://github.com/dangothecat/vieva/blob/main/FE/src/api/userApi.js"
click node_adminpage "https://github.com/dangothecat/vieva/blob/main/FE/src/pages/AdminUserPage.jsx"
click node_usermodal "https://github.com/dangothecat/vieva/blob/main/FE/src/components/users/CreateUserModal.jsx"
click node_usertable "https://github.com/dangothecat/vieva/blob/main/FE/src/components/users/UserTable.jsx"
click node_adminapi "https://github.com/dangothecat/vieva/blob/main/FE/src/api/adminUserApi.js"
click node_admincontroller "https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/adapters/controllers/AdminUserController.java"
click node_adminservice "https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/application/usecases/user/AdminUserServiceImpl.java"
click node_authcontroller "https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/adapters/controllers/AuthController.java"
click node_authservice "https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/application/usecases/auth/AuthServiceImpl.java"
click node_documents "https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/application/usecases/document/DocumentIndexingServiceImpl.java"
click node_indexworker "https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/infrastructure/service/AsyncDocumentIndexingWorker.java"
click node_docparser "https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/infrastructure/service/TikaDocumentParserGateway.java"
click node_embedding "https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/infrastructure/service/SpringAiEmbeddingGateway.java"
click node_questiongen "https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/infrastructure/service/OpenAiQuestionGeneratorGateway.java"
click node_questionbankservice "https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/application/usecases/question/QuestionBankServiceImpl.java"
click node_questioncontroller "https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/adapters/controllers/LecturerQuestionController.java"
click node_storage "https://github.com/dangothecat/vieva/tree/main/BE/src/main/java/com/example/vieva/infrastructure/database"
click node_oralworkflow "https://github.com/dangothecat/vieva/tree/main/BE/src/main/java/com/example/vieva"
click node_audio "https://github.com/dangothecat/vieva/tree/main/BE/src/main/java/com/example/vieva"
click node_adaptive "https://github.com/dangothecat/vieva/tree/main/BE/src/main/java/com/example/vieva"

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_webapp,node_authui,node_user toneBlue
class node_authstate,node_httpclient,node_authapi,node_userapi,node_adminpage,node_usermodal,node_usertable,node_adminapi,node_admincontroller,node_adminservice,node_authcontroller,node_authservice toneAmber
class node_documents,node_indexworker,node_docparser,node_embedding,node_questiongen,node_questionbankservice,node_questioncontroller,node_llm toneMint
class node_oralworkflow,node_audio,node_adaptive,node_speechservices toneRose
class node_storage,node_database toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/dangothecat/vieva/blob/main/FE/src/App.jsx): `FE/src/App.jsx`
- [Login and registration](https://github.com/dangothecat/vieva/blob/main/FE/src/pages/LoginPage.jsx): `FE/src/pages/LoginPage.jsx`

### Identity and admin

- [Authentication state](https://github.com/dangothecat/vieva/blob/main/FE/src/context/AuthContext.jsx): `FE/src/context/AuthContext.jsx`
- [API client](https://github.com/dangothecat/vieva/blob/main/FE/src/api/client.js): `FE/src/api/client.js`
- [Authentication API](https://github.com/dangothecat/vieva/blob/main/FE/src/api/authApi.js): `FE/src/api/authApi.js`
- [User API](https://github.com/dangothecat/vieva/blob/main/FE/src/api/userApi.js): `FE/src/api/userApi.js`
- [Admin user management](https://github.com/dangothecat/vieva/blob/main/FE/src/pages/AdminUserPage.jsx): `FE/src/pages/AdminUserPage.jsx`
- [User management dialogs](https://github.com/dangothecat/vieva/blob/main/FE/src/components/users/CreateUserModal.jsx): `FE/src/components/users/CreateUserModal.jsx`
- [User table](https://github.com/dangothecat/vieva/blob/main/FE/src/components/users/UserTable.jsx): `FE/src/components/users/UserTable.jsx`
- [Admin user API](https://github.com/dangothecat/vieva/blob/main/FE/src/api/adminUserApi.js): `FE/src/api/adminUserApi.js`
- [Admin user endpoints](https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/adapters/controllers/AdminUserController.java): `BE/src/main/java/com/example/vieva/adapters/controllers/AdminUserController.java`
- [Admin user use case](https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/application/usecases/user/AdminUserServiceImpl.java): `BE/src/main/java/com/example/vieva/application/usecases/user/AdminUserServiceImpl.java`
- [Authentication endpoints](https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/adapters/controllers/AuthController.java): `BE/src/main/java/com/example/vieva/adapters/controllers/AuthController.java`
- [Authentication use case](https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/application/usecases/auth/AuthServiceImpl.java): `BE/src/main/java/com/example/vieva/application/usecases/auth/AuthServiceImpl.java`

### Question bank and RAG

- [Course documents](https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/application/usecases/document/DocumentIndexingServiceImpl.java): `BE/src/main/java/com/example/vieva/application/usecases/document/DocumentIndexingServiceImpl.java`
- [Async indexing worker](https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/infrastructure/service/AsyncDocumentIndexingWorker.java): `BE/src/main/java/com/example/vieva/infrastructure/service/AsyncDocumentIndexingWorker.java`
- [Document parsing](https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/infrastructure/service/TikaDocumentParserGateway.java): `BE/src/main/java/com/example/vieva/infrastructure/service/TikaDocumentParserGateway.java`
- [Embedding service](https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/infrastructure/service/SpringAiEmbeddingGateway.java): `BE/src/main/java/com/example/vieva/infrastructure/service/SpringAiEmbeddingGateway.java`
- [RAG question generation](https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/infrastructure/service/OpenAiQuestionGeneratorGateway.java): `BE/src/main/java/com/example/vieva/infrastructure/service/OpenAiQuestionGeneratorGateway.java`
- [Question bank use case](https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/application/usecases/question/QuestionBankServiceImpl.java): `BE/src/main/java/com/example/vieva/application/usecases/question/QuestionBankServiceImpl.java`
- [Lecturer question endpoints](https://github.com/dangothecat/vieva/blob/main/BE/src/main/java/com/example/vieva/adapters/controllers/LecturerQuestionController.java): `BE/src/main/java/com/example/vieva/adapters/controllers/LecturerQuestionController.java`
- **LLM service**

### Oral examination

- [Exam attempts and snapshots](https://github.com/dangothecat/vieva/tree/main/BE/src/main/java/com/example/vieva): `BE/src/main/java/com/example/vieva`
- [Real-time speech interaction](https://github.com/dangothecat/vieva/tree/main/BE/src/main/java/com/example/vieva): `BE/src/main/java/com/example/vieva`
- [Adaptive follow-up and grading](https://github.com/dangothecat/vieva/tree/main/BE/src/main/java/com/example/vieva): `BE/src/main/java/com/example/vieva`
- **STT and TTS services**

### Backend foundations

- [Question and document store](https://github.com/dangothecat/vieva/tree/main/BE/src/main/java/com/example/vieva/infrastructure/database): `BE/src/main/java/com/example/vieva/infrastructure/database`
- **PostgreSQL**

### Other components

- **User**

## Connections

- User → Web application: uses (evidence: `README.md`)
- Web application → Login and registration: routes to (evidence: `FE/src/App.jsx`)
- Login and registration → Authentication state: authenticates via (evidence: `FE/src/pages/LoginPage.jsx`)
- Authentication state → Authentication API: calls (evidence: `FE/src/context/AuthContext.jsx`)
- Authentication state → User API: loads profile (evidence: `FE/src/context/AuthContext.jsx`)
- Authentication API → API client: sends requests (evidence: `FE/src/api/authApi.js`)
- User API → API client: sends requests (evidence: `FE/src/api/userApi.js`)
- API client → Authentication endpoints: REST API
- Web application → Admin user management: routes to (evidence: `FE/src/App.jsx`)
- Admin user management → Admin user API: loads and updates (evidence: `FE/src/pages/AdminUserPage.jsx`)
- Admin user management → User table: renders (evidence: `FE/src/pages/AdminUserPage.jsx`)
- Admin user management → User management dialogs: opens (evidence: `FE/src/pages/AdminUserPage.jsx`)
- User management dialogs → Admin user API: submits changes (evidence: `FE/src/components/users/CreateUserModal.jsx`)
- Admin user API → API client: sends requests (evidence: `FE/src/api/adminUserApi.js`)
- API client → Admin user endpoints: REST API
- Admin user endpoints → Admin user use case: delegates
- Authentication endpoints → Authentication use case: delegates
- User → Course documents: uploads course material (evidence: `README.md`)
- Course documents → Async indexing worker: indexes asynchronously (evidence: `README.md`)
- Async indexing worker → Document parsing: extracts text (evidence: `README.md`)
- Async indexing worker → Embedding service: creates vectors (evidence: `README.md`)
- Course documents → Question and document store: stores indexed material
- User → Lecturer question endpoints: reviews questions (evidence: `README.md`)
- Lecturer question endpoints → Question bank use case: manages drafts and approval
- Question bank use case → RAG question generation: requests generation (evidence: `README.md`)
- RAG question generation → Embedding service: retrieves context (evidence: `README.md`)
- RAG question generation → LLM service: generates questions (evidence: `README.md`)
- Question bank use case → Question and document store: persists questions
- User → Exam attempts and snapshots: starts exam (evidence: `README.md`)
- Exam attempts and snapshots → Real-time speech interaction: starts voice session (evidence: `README.md`)
- Real-time speech interaction → STT and TTS services: streams audio (evidence: `README.md`)
- Real-time speech interaction → Adaptive follow-up and grading: submits transcript (evidence: `README.md`)
- Adaptive follow-up and grading → LLM service: evaluates and follows up (evidence: `README.md`)
- Exam attempts and snapshots → Question and document store: stores exam evidence (evidence: `README.md`)
- Question and document store → PostgreSQL: persists records