# daetoya608/examassistent architecture

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

- Interactive diagram: https://gitdiagram.com/daetoya608/examassistent
- Repository: https://github.com/daetoya608/examassistent

## Overview

ExamAssistant is an exam-preparation assistant: users upload lecture PDFs, then ask questions that can draw on those documents. The documented upload path parses and chunks PDF pages, stores the file, and indexes chunks; the documented question path may retrieve relevant chunks before generating an answer. The graph includes the API, use cases, domain services, and principal adapters. Some internal chat/agent behavior is represented from README descriptions and source-index references; unsampled implementation details are not asserted as verified calls.

Main entry points: [`app/application/use_cases/upload_document.py`](https://github.com/daetoya608/examassistent/blob/main/app/application/use_cases/upload_document.py) (Upload use case), [`app/application/use_cases/chat.py`](https://github.com/daetoya608/examassistent/blob/main/app/application/use_cases/chat.py) (Chat use case), [`app/domains/vector_db/service.py`](https://github.com/daetoya608/examassistent/blob/main/app/domains/vector_db/service.py) (Vector service), [`app/infrastructure/persistence/postgres/connection/session.py`](https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/persistence/postgres/connection/session.py) (Postgres session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api_app["API and workflows"]
  node_chat_api["Chat endpoint<br/>[chat.py]"]
  node_upload_api["Document endpoint<br/>[documents.py]"]
  node_chat_flow["Chat use case<br/>[chat.py]"]
  node_upload_flow["Upload use case<br/>[upload_document.py]"]
end

subgraph group_domain["Domain services"]
  node_chat_service["Chat service<br/>[service.py]"]
  node_document_service["Document service<br/>[service.py]"]
  node_vector_service["Vector service<br/>[service.py]"]
  node_user_service["User service<br/>[service.py]"]
end

subgraph group_integrations["AI and file integrations"]
  node_pdf_parser["PDF parser<br/>[pdf_parser.py]"]
  node_file_storage["Backblaze storage"]
  node_agent["LangGraph agent<br/>[agent.py]"]
  node_openai["OpenAI adapter"]
  node_qdrant[("Qdrant chunk index<br/>[docs_repository.py]")]
end

subgraph group_persistence["Persistence"]
  node_postgres_chat[("Chat repository<br/>[repository.py]")]
  node_postgres_docs[("Document repository<br/>[repository.py]")]
  node_postgres_users[("User repository<br/>[repository.py]")]
  node_postgres_session[("Postgres session<br/>[session.py]")]
end

node_student(("Student"))

node_student -->|"uploads PDF"| node_upload_api
node_student -->|"asks question"| node_chat_api
node_upload_api -->|"invokes"| node_upload_flow
node_chat_api -->|"invokes"| node_chat_flow
node_upload_flow -->|"parses PDF"| node_pdf_parser
node_upload_flow -->|"chunks pages"| node_document_service
node_upload_flow -->|"saves file"| node_file_storage
node_upload_flow -->|"indexes chunks"| node_vector_service
node_upload_flow -->|"saves metadata"| node_postgres_docs
node_vector_service -.->|"delegates storage"| node_qdrant
node_chat_flow -.->|"uses history"| node_chat_service
node_chat_flow -->|"retrieves context"| node_vector_service
node_chat_flow -.->|"coordinates response"| node_agent
node_chat_flow -.->|"generates answer"| node_openai
node_chat_service -.->|"persists messages"| node_postgres_chat
node_upload_flow -.->|"uses user service"| node_user_service
node_postgres_chat -.->|"uses session"| node_postgres_session
node_postgres_docs -.->|"uses session"| node_postgres_session
node_postgres_users -.->|"uses session"| node_postgres_session

click node_chat_api "https://github.com/daetoya608/examassistent/blob/main/app/api/v1/chat.py"
click node_upload_api "https://github.com/daetoya608/examassistent/blob/main/app/api/v1/documents.py"
click node_chat_flow "https://github.com/daetoya608/examassistent/blob/main/app/application/use_cases/chat.py"
click node_upload_flow "https://github.com/daetoya608/examassistent/blob/main/app/application/use_cases/upload_document.py"
click node_chat_service "https://github.com/daetoya608/examassistent/blob/main/app/domains/chats/service.py"
click node_document_service "https://github.com/daetoya608/examassistent/blob/main/app/domains/documents/service.py"
click node_vector_service "https://github.com/daetoya608/examassistent/blob/main/app/domains/vector_db/service.py"
click node_user_service "https://github.com/daetoya608/examassistent/blob/main/app/domains/users/service.py"
click node_pdf_parser "https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/parsers/pdf_parser/pdf_parser.py"
click node_file_storage "https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/file_storage/s3/backblaze_storage.py"
click node_agent "https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/langgraph_agent/agent.py"
click node_openai "https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/openai_llm/langchain_openai_repo.py"
click node_qdrant "https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/vector_db/qdrant/docs_repository.py"
click node_postgres_chat "https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/persistence/postgres/modules/chats/repository.py"
click node_postgres_docs "https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/persistence/postgres/modules/documents/repository.py"
click node_postgres_users "https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/persistence/postgres/modules/users/repository.py"
click node_postgres_session "https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/persistence/postgres/connection/session.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_chat_api,node_upload_api,node_chat_flow,node_upload_flow toneBlue
class node_chat_service,node_document_service,node_vector_service,node_user_service toneAmber
class node_pdf_parser,node_file_storage,node_agent,node_openai,node_qdrant toneMint
class node_postgres_chat,node_postgres_docs,node_postgres_users,node_postgres_session toneRose
class node_student toneIndigo
```

## Components

### API and workflows

- [Chat endpoint](https://github.com/daetoya608/examassistent/blob/main/app/api/v1/chat.py): `app/api/v1/chat.py`
- [Document endpoint](https://github.com/daetoya608/examassistent/blob/main/app/api/v1/documents.py): `app/api/v1/documents.py`
- [Chat use case](https://github.com/daetoya608/examassistent/blob/main/app/application/use_cases/chat.py): `app/application/use_cases/chat.py`
- [Upload use case](https://github.com/daetoya608/examassistent/blob/main/app/application/use_cases/upload_document.py): `app/application/use_cases/upload_document.py`

### Domain services

- [Chat service](https://github.com/daetoya608/examassistent/blob/main/app/domains/chats/service.py): `app/domains/chats/service.py`
- [Document service](https://github.com/daetoya608/examassistent/blob/main/app/domains/documents/service.py): `app/domains/documents/service.py`
- [Vector service](https://github.com/daetoya608/examassistent/blob/main/app/domains/vector_db/service.py): `app/domains/vector_db/service.py`
- [User service](https://github.com/daetoya608/examassistent/blob/main/app/domains/users/service.py): `app/domains/users/service.py`

### AI and file integrations

- [PDF parser](https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/parsers/pdf_parser/pdf_parser.py): `app/infrastructure/parsers/pdf_parser/pdf_parser.py`
- [Backblaze storage](https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/file_storage/s3/backblaze_storage.py): `app/infrastructure/file_storage/s3/backblaze_storage.py`
- [LangGraph agent](https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/langgraph_agent/agent.py): `app/infrastructure/langgraph_agent/agent.py`
- [OpenAI adapter](https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/openai_llm/langchain_openai_repo.py): `app/infrastructure/openai_llm/langchain_openai_repo.py`
- [Qdrant chunk index](https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/vector_db/qdrant/docs_repository.py): `app/infrastructure/vector_db/qdrant/docs_repository.py`

### Persistence

- [Chat repository](https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/persistence/postgres/modules/chats/repository.py): `app/infrastructure/persistence/postgres/modules/chats/repository.py`
- [Document repository](https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/persistence/postgres/modules/documents/repository.py): `app/infrastructure/persistence/postgres/modules/documents/repository.py`
- [User repository](https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/persistence/postgres/modules/users/repository.py): `app/infrastructure/persistence/postgres/modules/users/repository.py`
- [Postgres session](https://github.com/daetoya608/examassistent/blob/main/app/infrastructure/persistence/postgres/connection/session.py): `app/infrastructure/persistence/postgres/connection/session.py`

### Other components

- **Student**

## Connections

- Student → Document endpoint: uploads PDF
- Student → Chat endpoint: asks question
- Document endpoint → Upload use case: invokes (evidence: `app/api/v1/documents.py`)
- Chat endpoint → Chat use case: invokes (evidence: `app/api/v1/chat.py`)
- Upload use case → PDF parser: parses PDF (evidence: `app/application/use_cases/upload_document.py`)
- Upload use case → Document service: chunks pages (evidence: `app/application/use_cases/upload_document.py`)
- Upload use case → Backblaze storage: saves file (evidence: `app/application/use_cases/upload_document.py`)
- Upload use case → Vector service: indexes chunks (evidence: `app/application/use_cases/upload_document.py`)
- Upload use case → Document repository: saves metadata (evidence: `app/application/use_cases/upload_document.py`)
- Vector service → Qdrant chunk index: delegates storage
- Chat use case → Chat service: uses history (evidence: `app/application/use_cases/chat.py`)
- Chat use case → Vector service: retrieves context (evidence: `app/application/use_cases/chat.py`)
- Chat use case → LangGraph agent: coordinates response
- Chat use case → OpenAI adapter: generates answer
- Chat service → Chat repository: persists messages
- Upload use case → User service: uses user service (evidence: `app/application/use_cases/upload_document.py`)
- Chat repository → Postgres session: uses session
- Document repository → Postgres session: uses session
- User repository → Postgres session: uses session
