# derek-05/alento architecture

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

- Interactive diagram: https://gitdiagram.com/derek-05/alento
- Repository: https://github.com/derek-05/alento

## Overview

Alento is an academic work-planning application: users manage classes and assignments, attach course materials, and turn those sources into grounded plans and actionable steps. The graph shows the frontend-to-API entry point, source ingestion and retrieval, planning, and related class, integration, focus, and PDF capabilities. Source excerpts confirm several internal behaviors, but route-to-service wiring and some unsampled subsystem details are not shown, so those links are intentionally omitted.

Main entry points: [`backend/app/features/sources/pipeline.py`](https://github.com/derek-05/alento/blob/main/backend/app/features/sources/pipeline.py) (Source processing), [`backend/app/main.py`](https://github.com/derek-05/alento/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/features/sources/retrieval_service.py`](https://github.com/derek-05/alento/blob/main/backend/app/features/sources/retrieval_service.py) (Evidence retrieval), [`backend/app/features/cyber/planner/planner_pipeline.py`](https://github.com/derek-05/alento/blob/main/backend/app/features/cyber/planner/planner_pipeline.py) (Plan generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_web["Next.js app<br/>[layout.tsx]"]
  node_work_ui["Workspaces"]
  node_pdf_ui["PDF suite"]
  node_api_proxy["API proxy<br/>[route.ts]"]
end

subgraph group_api["API and access"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_api_routes["API router<br/>[router.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_work["Work and planning"]
  node_work_service["Work management<br/>[service.py]"]
  node_work_store[("Work persistence<br/>[sql_store.py]")]
  node_planner["Plan generation"]
  node_chat["AI chat<br/>[chat_service.py]"]
  node_focus["Focus tools<br/>[service.py]"]
end

subgraph group_sources["Sources and evidence"]
  node_source_pipeline["Source processing<br/>[pipeline.py]"]
  node_source_review["Source review"]
  node_retrieval["Evidence retrieval"]
  node_object_storage["Object storage<br/>[object_storage.py]"]
  node_database[("PostgreSQL<br/>[db.py]")]
  node_pdf_engine["PDF editing<br/>[pdf-engine.ts]"]
end

subgraph group_integrations["Academic integrations"]
  node_classes["Class materials<br/>[service.py]"]
  node_moodle["Moodle integration<br/>[service.py]"]
  node_onedrive["OneDrive integration<br/>[service.py]"]
end

node_student(("Student"))
node_ai_provider{{"AI provider"}}

node_student -->|"uses"| node_web
node_web -->|"presents"| node_work_ui
node_work_ui -->|"requests"| node_api_proxy
node_pdf_ui -->|"creates splits"| node_pdf_engine
node_api_proxy -->|"forwards requests"| node_api_app
node_api_app -->|"mounts"| node_api_routes
node_api_app -->|"enforces access"| node_auth
node_source_pipeline -->|"stores files"| node_object_storage
node_source_pipeline -->|"records jobs"| node_database
node_source_pipeline -.->|"analyzes sources"| node_ai_provider
node_planner -->|"gets evidence"| node_retrieval
node_planner -->|"generates plans"| node_ai_provider
node_source_review -->|"reviews sources"| node_ai_provider
node_retrieval -->|"searches indexes"| node_database
node_retrieval -->|"signs evidence links"| node_object_storage
node_work_service -->|"persists work"| node_work_store
node_student -->|"manages classes"| node_classes
node_student -->|"imports materials"| node_moodle
node_student -->|"syncs files"| node_onedrive
node_student -->|"uses focus tools"| node_focus
node_student -->|"asks questions"| node_chat

click node_web "https://github.com/derek-05/alento/blob/main/frontend/src/app/layout.tsx"
click node_work_ui "https://github.com/derek-05/alento/blob/main/frontend/src/features/work-items/work-items-workspace.tsx"
click node_pdf_ui "https://github.com/derek-05/alento/blob/main/frontend/src/features/pdf-suite/pdf-suite-workspace.tsx"
click node_api_proxy "https://github.com/derek-05/alento/blob/main/frontend/src/app/api/proxy/%5B...path%5D/route.ts"
click node_api_app "https://github.com/derek-05/alento/blob/main/backend/app/main.py"
click node_api_routes "https://github.com/derek-05/alento/blob/main/backend/app/routes/router.py"
click node_auth "https://github.com/derek-05/alento/blob/main/backend/app/core/security/auth.py"
click node_work_service "https://github.com/derek-05/alento/blob/main/backend/app/features/work/service.py"
click node_work_store "https://github.com/derek-05/alento/blob/main/backend/app/features/work/persistence/sql_store.py"
click node_planner "https://github.com/derek-05/alento/blob/main/backend/app/features/cyber/planner/planner_pipeline.py"
click node_chat "https://github.com/derek-05/alento/blob/main/backend/app/features/cyber/chat/chat_service.py"
click node_focus "https://github.com/derek-05/alento/blob/main/backend/app/features/focus/service.py"
click node_source_pipeline "https://github.com/derek-05/alento/blob/main/backend/app/features/sources/pipeline.py"
click node_source_review "https://github.com/derek-05/alento/blob/main/backend/app/features/cyber/source_review/source_review_service.py"
click node_retrieval "https://github.com/derek-05/alento/blob/main/backend/app/features/sources/retrieval_service.py"
click node_object_storage "https://github.com/derek-05/alento/blob/main/backend/app/connections/storage/object_storage.py"
click node_database "https://github.com/derek-05/alento/blob/main/backend/app/core/db.py"
click node_classes "https://github.com/derek-05/alento/blob/main/backend/app/features/classes/service.py"
click node_moodle "https://github.com/derek-05/alento/blob/main/backend/app/features/moodle/service.py"
click node_onedrive "https://github.com/derek-05/alento/blob/main/backend/app/features/onedrive/service.py"
click node_pdf_engine "https://github.com/derek-05/alento/blob/main/frontend/src/features/pdf-suite/pdf-engine.ts"

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,node_work_ui,node_pdf_ui,node_api_proxy toneBlue
class node_api_app,node_api_routes,node_auth toneAmber
class node_work_service,node_work_store,node_planner,node_chat,node_focus toneMint
class node_source_pipeline,node_source_review,node_retrieval,node_object_storage,node_database,node_pdf_engine toneRose
class node_classes,node_moodle,node_onedrive,node_student,node_ai_provider toneIndigo
```

## Components

### Web application

- [Next.js app](https://github.com/derek-05/alento/blob/main/frontend/src/app/layout.tsx): `frontend/src/app/layout.tsx`
- [Workspaces](https://github.com/derek-05/alento/blob/main/frontend/src/features/work-items/work-items-workspace.tsx): `frontend/src/features/work-items/work-items-workspace.tsx`
- [PDF suite](https://github.com/derek-05/alento/blob/main/frontend/src/features/pdf-suite/pdf-suite-workspace.tsx): `frontend/src/features/pdf-suite/pdf-suite-workspace.tsx`
- [API proxy](https://github.com/derek-05/alento/blob/main/frontend/src/app/api/proxy/%5B...path%5D/route.ts): `frontend/src/app/api/proxy/[...path]/route.ts`

### API and access

- [FastAPI app](https://github.com/derek-05/alento/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/derek-05/alento/blob/main/backend/app/routes/router.py): `backend/app/routes/router.py`
- [Authentication](https://github.com/derek-05/alento/blob/main/backend/app/core/security/auth.py): `backend/app/core/security/auth.py`

### Work and planning

- [Work management](https://github.com/derek-05/alento/blob/main/backend/app/features/work/service.py): `backend/app/features/work/service.py`
- [Work persistence](https://github.com/derek-05/alento/blob/main/backend/app/features/work/persistence/sql_store.py): `backend/app/features/work/persistence/sql_store.py`
- [Plan generation](https://github.com/derek-05/alento/blob/main/backend/app/features/cyber/planner/planner_pipeline.py): `backend/app/features/cyber/planner/planner_pipeline.py`
- [AI chat](https://github.com/derek-05/alento/blob/main/backend/app/features/cyber/chat/chat_service.py): `backend/app/features/cyber/chat/chat_service.py`
- [Focus tools](https://github.com/derek-05/alento/blob/main/backend/app/features/focus/service.py): `backend/app/features/focus/service.py`

### Sources and evidence

- [Source processing](https://github.com/derek-05/alento/blob/main/backend/app/features/sources/pipeline.py): `backend/app/features/sources/pipeline.py`
- [Source review](https://github.com/derek-05/alento/blob/main/backend/app/features/cyber/source_review/source_review_service.py): `backend/app/features/cyber/source_review/source_review_service.py`
- [Evidence retrieval](https://github.com/derek-05/alento/blob/main/backend/app/features/sources/retrieval_service.py): `backend/app/features/sources/retrieval_service.py`
- [Object storage](https://github.com/derek-05/alento/blob/main/backend/app/connections/storage/object_storage.py): `backend/app/connections/storage/object_storage.py`
- [PostgreSQL](https://github.com/derek-05/alento/blob/main/backend/app/core/db.py): `backend/app/core/db.py`
- [PDF editing](https://github.com/derek-05/alento/blob/main/frontend/src/features/pdf-suite/pdf-engine.ts): `frontend/src/features/pdf-suite/pdf-engine.ts`

### Academic integrations

- [Class materials](https://github.com/derek-05/alento/blob/main/backend/app/features/classes/service.py): `backend/app/features/classes/service.py`
- [Moodle integration](https://github.com/derek-05/alento/blob/main/backend/app/features/moodle/service.py): `backend/app/features/moodle/service.py`
- [OneDrive integration](https://github.com/derek-05/alento/blob/main/backend/app/features/onedrive/service.py): `backend/app/features/onedrive/service.py`

### Other components

- **Student**
- **AI provider**

## Connections

- Student → Next.js app: uses
- Next.js app → Workspaces: presents
- Workspaces → API proxy: requests
- PDF suite → PDF editing: creates splits
- API proxy → FastAPI app: forwards requests
- FastAPI app → API router: mounts
- FastAPI app → Authentication: enforces access
- Source processing → Object storage: stores files
- Source processing → PostgreSQL: records jobs
- Source processing → AI provider: analyzes sources
- Plan generation → Evidence retrieval: gets evidence
- Plan generation → AI provider: generates plans
- Source review → AI provider: reviews sources
- Evidence retrieval → PostgreSQL: searches indexes
- Evidence retrieval → Object storage: signs evidence links
- Work management → Work persistence: persists work
- Student → Class materials: manages classes
- Student → Moodle integration: imports materials
- Student → OneDrive integration: syncs files
- Student → Focus tools: uses focus tools
- Student → AI chat: asks questions