# calmxz/project_apt architecture

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

- Interactive diagram: https://gitdiagram.com/calmxz/project_apt
- Repository: https://github.com/calmxz/project_apt

## Overview

Crux is an adaptive AI study companion: a learner starts or resumes a topic session, chats with a tutor grounded in uploaded course material, and gets learner-profile updates and checks that inform later turns. Separate flows handle document ingestion, profile and session views, and spaced review. The README documents the chat/tool workflow and major capabilities; sampled source confirms retrieval, ingestion, review scheduling, and app startup details, but not every route-to-service call, so uncertain wiring is omitted.

Main entry points: [`frontend/src/App.vue`](https://github.com/calmxz/project_apt/blob/main/frontend/src/App.vue) (Vue application), [`backend/db/database.py`](https://github.com/calmxz/project_apt/blob/main/backend/db/database.py) (Application database), [`backend/main.py`](https://github.com/calmxz/project_apt/blob/main/backend/main.py) (FastAPI app), [`backend/services/ingestion_service.py`](https://github.com/calmxz/project_apt/blob/main/backend/services/ingestion_service.py) (Ingestion pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Study interface"]
  node_web_app["Vue application<br/>[App.vue]"]
  node_session_view["Study session<br/>[SessionView.vue]"]
  node_chat_stream["Chat stream"]
  node_library_view["Session library"]
  node_profile_view["Profile views<br/>[ProfileView.vue]"]
  node_review_view["Review view<br/>[ReviewView.vue]"]
  node_upload_api["Upload client<br/>[uploadApi.js]"]
end

subgraph group_api_agent["API and tutor"]
  node_backend_app["FastAPI app<br/>[main.py]"]
  node_chat_route["Chat endpoint<br/>[chat.py]"]
  node_tutor["Tutor agent<br/>[tutor.py]"]
  node_agent_tools["Agent tools<br/>[tools.py]"]
end

subgraph group_learning_data["Learning and state"]
  node_profile_service["Learner profile<br/>[profile_service.py]"]
  node_check_service["Knowledge checks"]
  node_review_service["Review scheduler"]
  node_session_routes["Session routes<br/>[sessions.py]"]
  node_profile_routes["Profile routes<br/>[profile.py]"]
  node_review_routes["Review routes<br/>[review.py]"]
  node_database[("Application database<br/>[database.py]")]
end

subgraph group_materials["Course materials"]
  node_upload_routes["Upload routes<br/>[upload.py]"]
  node_documents_routes["Document routes<br/>[documents.py]"]
  node_ingestion["Ingestion pipeline"]
  node_retrieval["RAG retrieval"]
  node_vector_store[("Vector store<br/>[pgvector_store.py]")]
  node_object_store[("File storage<br/>[object_store.py]")]
end

node_learner(("Learner"))
node_llm{{"LLM provider"}}
node_supabase{{"Supabase services"}}

node_learner -->|"uses"| node_web_app
node_web_app -->|"renders"| node_session_view
node_session_view -->|"streams turns"| node_chat_stream
node_chat_stream -->|"posts turns"| node_chat_route
node_web_app -->|"calls API"| node_backend_app
node_backend_app -->|"mounts routes"| node_chat_route
node_chat_route -->|"runs turn"| node_tutor
node_tutor -->|"requests completion"| node_llm
node_tutor -->|"dispatches tools"| node_agent_tools
node_agent_tools -->|"retrieves chunks"| node_retrieval
node_retrieval -->|"embeds query"| node_llm
node_retrieval -->|"searches chunks"| node_vector_store
node_agent_tools -->|"updates profile"| node_profile_service
node_agent_tools -->|"registers checks"| node_check_service
node_chat_route -->|"loads and saves turn"| node_database
node_profile_service -->|"reads and writes"| node_database
node_check_service -->|"records outcomes"| node_database
node_web_app -->|"renders"| node_library_view
node_library_view -->|"loads sessions"| node_session_routes
node_web_app -->|"renders"| node_profile_view
node_profile_view -->|"loads profiles"| node_profile_routes
node_web_app -->|"renders"| node_review_view
node_review_view -->|"loads due concepts"| node_review_routes
node_review_routes -->|"computes schedule"| node_review_service
node_review_routes -->|"loads learning events"| node_database
node_learner -->|"uploads materials"| node_upload_api
node_upload_api -->|"submits files"| node_upload_routes
node_backend_app -->|"mounts routes"| node_upload_routes
node_backend_app -->|"mounts routes"| node_documents_routes
node_upload_routes -->|"stores file"| node_object_store
node_ingestion -->|"loads file"| node_object_store
node_ingestion -->|"embeds chunks"| node_llm
node_ingestion -->|"stores embeddings"| node_vector_store
node_ingestion -->|"updates document state"| node_database
node_retrieval -->|"checks readiness"| node_database
node_backend_app -.->|"validates auth"| node_supabase

click node_web_app "https://github.com/calmxz/project_apt/blob/main/frontend/src/App.vue"
click node_session_view "https://github.com/calmxz/project_apt/blob/main/frontend/src/views/SessionView.vue"
click node_chat_stream "https://github.com/calmxz/project_apt/blob/main/frontend/src/services/chatStreamService.js"
click node_library_view "https://github.com/calmxz/project_apt/blob/main/frontend/src/views/SessionsLibraryView.vue"
click node_profile_view "https://github.com/calmxz/project_apt/blob/main/frontend/src/views/ProfileView.vue"
click node_review_view "https://github.com/calmxz/project_apt/blob/main/frontend/src/views/ReviewView.vue"
click node_upload_api "https://github.com/calmxz/project_apt/blob/main/frontend/src/services/uploadApi.js"
click node_backend_app "https://github.com/calmxz/project_apt/blob/main/backend/main.py"
click node_chat_route "https://github.com/calmxz/project_apt/blob/main/backend/routes/chat.py"
click node_tutor "https://github.com/calmxz/project_apt/blob/main/backend/agent/tutor.py"
click node_agent_tools "https://github.com/calmxz/project_apt/blob/main/backend/agent/tools.py"
click node_profile_service "https://github.com/calmxz/project_apt/blob/main/backend/services/profile_service.py"
click node_check_service "https://github.com/calmxz/project_apt/blob/main/backend/services/check_question_service.py"
click node_review_service "https://github.com/calmxz/project_apt/blob/main/backend/services/review_queue_service.py"
click node_session_routes "https://github.com/calmxz/project_apt/blob/main/backend/routes/sessions.py"
click node_profile_routes "https://github.com/calmxz/project_apt/blob/main/backend/routes/profile.py"
click node_review_routes "https://github.com/calmxz/project_apt/blob/main/backend/routes/review.py"
click node_database "https://github.com/calmxz/project_apt/blob/main/backend/db/database.py"
click node_upload_routes "https://github.com/calmxz/project_apt/blob/main/backend/routes/upload.py"
click node_documents_routes "https://github.com/calmxz/project_apt/blob/main/backend/routes/documents.py"
click node_ingestion "https://github.com/calmxz/project_apt/blob/main/backend/services/ingestion_service.py"
click node_retrieval "https://github.com/calmxz/project_apt/blob/main/backend/services/retrieval_service.py"
click node_vector_store "https://github.com/calmxz/project_apt/blob/main/backend/services/pgvector_store.py"
click node_object_store "https://github.com/calmxz/project_apt/blob/main/backend/services/object_store.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_web_app,node_session_view,node_chat_stream,node_library_view,node_profile_view,node_review_view,node_upload_api toneBlue
class node_backend_app,node_chat_route,node_tutor,node_agent_tools toneAmber
class node_profile_service,node_check_service,node_review_service,node_session_routes,node_profile_routes,node_review_routes,node_database toneMint
class node_upload_routes,node_documents_routes,node_ingestion,node_retrieval,node_vector_store,node_object_store toneRose
class node_learner,node_llm,node_supabase toneIndigo
```

## Components

### Study interface

- [Vue application](https://github.com/calmxz/project_apt/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [Study session](https://github.com/calmxz/project_apt/blob/main/frontend/src/views/SessionView.vue): `frontend/src/views/SessionView.vue`
- [Chat stream](https://github.com/calmxz/project_apt/blob/main/frontend/src/services/chatStreamService.js): `frontend/src/services/chatStreamService.js`
- [Session library](https://github.com/calmxz/project_apt/blob/main/frontend/src/views/SessionsLibraryView.vue): `frontend/src/views/SessionsLibraryView.vue`
- [Profile views](https://github.com/calmxz/project_apt/blob/main/frontend/src/views/ProfileView.vue): `frontend/src/views/ProfileView.vue`
- [Review view](https://github.com/calmxz/project_apt/blob/main/frontend/src/views/ReviewView.vue): `frontend/src/views/ReviewView.vue`
- [Upload client](https://github.com/calmxz/project_apt/blob/main/frontend/src/services/uploadApi.js): `frontend/src/services/uploadApi.js`

### API and tutor

- [FastAPI app](https://github.com/calmxz/project_apt/blob/main/backend/main.py): `backend/main.py`
- [Chat endpoint](https://github.com/calmxz/project_apt/blob/main/backend/routes/chat.py): `backend/routes/chat.py`
- [Tutor agent](https://github.com/calmxz/project_apt/blob/main/backend/agent/tutor.py): `backend/agent/tutor.py`
- [Agent tools](https://github.com/calmxz/project_apt/blob/main/backend/agent/tools.py): `backend/agent/tools.py`

### Learning and state

- [Learner profile](https://github.com/calmxz/project_apt/blob/main/backend/services/profile_service.py): `backend/services/profile_service.py`
- [Knowledge checks](https://github.com/calmxz/project_apt/blob/main/backend/services/check_question_service.py): `backend/services/check_question_service.py`
- [Review scheduler](https://github.com/calmxz/project_apt/blob/main/backend/services/review_queue_service.py): `backend/services/review_queue_service.py`
- [Session routes](https://github.com/calmxz/project_apt/blob/main/backend/routes/sessions.py): `backend/routes/sessions.py`
- [Profile routes](https://github.com/calmxz/project_apt/blob/main/backend/routes/profile.py): `backend/routes/profile.py`
- [Review routes](https://github.com/calmxz/project_apt/blob/main/backend/routes/review.py): `backend/routes/review.py`
- [Application database](https://github.com/calmxz/project_apt/blob/main/backend/db/database.py): `backend/db/database.py`

### Course materials

- [Upload routes](https://github.com/calmxz/project_apt/blob/main/backend/routes/upload.py): `backend/routes/upload.py`
- [Document routes](https://github.com/calmxz/project_apt/blob/main/backend/routes/documents.py): `backend/routes/documents.py`
- [Ingestion pipeline](https://github.com/calmxz/project_apt/blob/main/backend/services/ingestion_service.py): `backend/services/ingestion_service.py`
- [RAG retrieval](https://github.com/calmxz/project_apt/blob/main/backend/services/retrieval_service.py): `backend/services/retrieval_service.py`
- [Vector store](https://github.com/calmxz/project_apt/blob/main/backend/services/pgvector_store.py): `backend/services/pgvector_store.py`
- [File storage](https://github.com/calmxz/project_apt/blob/main/backend/services/object_store.py): `backend/services/object_store.py`

### Other components

- **Learner**
- **LLM provider**
- **Supabase services**

## Connections

- Learner → Vue application: uses
- Vue application → Study session: renders
- Study session → Chat stream: streams turns
- Chat stream → Chat endpoint: posts turns
- Vue application → FastAPI app: calls API
- FastAPI app → Chat endpoint: mounts routes
- Chat endpoint → Tutor agent: runs turn
- Tutor agent → LLM provider: requests completion
- Tutor agent → Agent tools: dispatches tools
- Agent tools → RAG retrieval: retrieves chunks
- RAG retrieval → LLM provider: embeds query
- RAG retrieval → Vector store: searches chunks
- Agent tools → Learner profile: updates profile
- Agent tools → Knowledge checks: registers checks
- Chat endpoint → Application database: loads and saves turn
- Learner profile → Application database: reads and writes
- Knowledge checks → Application database: records outcomes
- Vue application → Session library: renders
- Session library → Session routes: loads sessions
- Vue application → Profile views: renders
- Profile views → Profile routes: loads profiles
- Vue application → Review view: renders
- Review view → Review routes: loads due concepts
- Review routes → Review scheduler: computes schedule
- Review routes → Application database: loads learning events
- Learner → Upload client: uploads materials
- Upload client → Upload routes: submits files
- FastAPI app → Upload routes: mounts routes
- FastAPI app → Document routes: mounts routes
- Upload routes → File storage: stores file
- Ingestion pipeline → File storage: loads file
- Ingestion pipeline → LLM provider: embeds chunks
- Ingestion pipeline → Vector store: stores embeddings
- Ingestion pipeline → Application database: updates document state
- RAG retrieval → Application database: checks readiness
- FastAPI app → Supabase services: validates auth