# ndeshpan30/laif architecture

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

- Interactive diagram: https://gitdiagram.com/ndeshpan30/laif
- Repository: https://github.com/ndeshpan30/laif

## Overview

Autonomous Cognitive Offloader pairs a conversational BuJo logger with a deterministic life scheduler: users state goals, log activities, or announce deadlines; the backend extracts typed intent, applies memory guardrails, and delegates calendar placement to a CP-SAT solver. Separate flows ingest syllabus PDFs and episodic constraints for retrieval and knowledge-graph exploration, while telemetry updates dynamic trackers and logs. The Ledger presents recorded activity. Paths and links reflect the supplied tree, README capabilities, and sampled code; unsampled endpoint wiring is shown only where documented, and uncertain call relations are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/ndeshpan30/laif/blob/main/backend/app/main.py) (FastAPI App), [`backend/app/database.py`](https://github.com/ndeshpan30/laif/blob/main/backend/app/database.py) (Database Session & Schema), [`frontend/app/page.tsx`](https://github.com/ndeshpan30/laif/blob/main/frontend/app/page.tsx) (Conversation UI), [`backend/app/services/conversation.py`](https://github.com/ndeshpan30/laif/blob/main/backend/app/services/conversation.py) (Conversation Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_conversation_ui["Conversation UI<br/>[page.tsx]"]
  node_speech["Speech Manager<br/>[SpeechManager.ts]"]
  node_sound["Sound Manager<br/>[SoundManager.ts]"]
  node_ledger_ui["Ledger Dashboard<br/>[page.tsx]"]
  node_graph_ui["Knowledge Graph UI<br/>[page.tsx]"]
  node_graph_view["Graph View &amp; Details"]
end

subgraph group_conversation["Conversation &amp; Scheduling"]
  node_api["FastAPI App<br/>[main.py]"]
  node_conversation_api["Conversation API<br/>[conversation.py]"]
  node_conversation_service["Conversation Service<br/>[conversation.py]"]
  node_llm["Goal &amp; Telemetry Extraction<br/>[gemini_client.py]"]
  node_scheduler["CP-SAT Scheduler<br/>[scheduler.py]"]
  node_schedule_api["Schedule API<br/>[schedule.py]"]
end

subgraph group_memory["Memory &amp; Knowledge Graph"]
  node_semantic_api["Semantic API<br/>[semantic.py]"]
  node_rag["Syllabus &amp; Constraint RAG<br/>[rag.py]"]
  node_kg_api["Knowledge Graph API<br/>[knowledge_graph.py]"]
  node_knowledge_graph["Knowledge Graph Service<br/>[knowledge_graph.py]"]
end

subgraph group_telemetry["BuJo Telemetry &amp; Ledger"]
  node_telemetry_api["Telemetry API<br/>[telemetry.py]"]
  node_telemetry_engine["Telemetry Engine"]
  node_tracker_api["Tracker API<br/>[trackers.py]"]
end

subgraph group_persistence["Persistence"]
  node_user_api["User API<br/>[user.py]"]
  node_database[("Database Session &amp; Schema<br/>[database.py]")]
  node_models["Domain Models"]
end

node_user(("User"))
node_external_llm(("LLM Provider"))
node_browser_audio(("Browser Audio &amp; Speech"))
node_client(("Frontend Client"))

node_user -->|"states goals"| node_conversation_ui
node_conversation_ui -->|"captures speech"| node_speech
node_conversation_ui -->|"sends requests"| node_api
node_api -->|"dispatches"| node_conversation_api
node_conversation_api -->|"handles conversation"| node_conversation_service
node_conversation_service -->|"extracts intent"| node_llm
node_llm -.->|"requests generation"| node_external_llm
node_conversation_service -->|"solves schedule"| node_scheduler
node_conversation_service -->|"retrieves context"| node_rag
node_conversation_ui -->|"plays feedback"| node_sound
node_sound -->|"generates tones"| node_browser_audio
node_speech -->|"uses speech APIs"| node_browser_audio
node_user -->|"uploads syllabus"| node_semantic_api
node_api -->|"dispatches"| node_semantic_api
node_semantic_api -->|"ingests and retrieves"| node_rag
node_rag -->|"reads and writes context"| node_database
node_user -->|"manages schedule"| node_schedule_api
node_api -->|"dispatches"| node_schedule_api
node_schedule_api -->|"solves schedule"| node_scheduler
node_schedule_api -->|"reads and writes schedule"| node_database
node_user -->|"logs activities"| node_telemetry_api
node_api -->|"dispatches"| node_telemetry_api
node_telemetry_api -->|"extracts data points"| node_llm
node_telemetry_api -->|"processes logs"| node_telemetry_engine
node_telemetry_engine -->|"reads and writes trackers and logs"| node_database
node_telemetry_engine -->|"syncs logged nodes"| node_knowledge_graph
node_user -->|"manages trackers"| node_tracker_api
node_api -->|"dispatches"| node_tracker_api
node_tracker_api -->|"reads and writes trackers"| node_database
node_user -->|"manages profile"| node_user_api
node_api -->|"dispatches"| node_user_api
node_user_api -->|"reads and writes user"| node_database
node_database -->|"maps records"| node_models
node_client -->|"views ledger"| node_ledger_ui
node_client -->|"explores graph"| node_graph_ui
node_graph_ui -->|"fetches graph"| node_api
node_api -->|"dispatches"| node_kg_api
node_kg_api -->|"builds graph"| node_knowledge_graph
node_knowledge_graph -->|"reads graph data"| node_database
node_graph_ui -->|"renders filtered graph"| node_graph_view
node_ledger_ui -->|"loads ledger data"| node_api

click node_conversation_ui "https://github.com/ndeshpan30/laif/blob/main/frontend/app/page.tsx"
click node_speech "https://github.com/ndeshpan30/laif/blob/main/frontend/components/SpeechManager.ts"
click node_sound "https://github.com/ndeshpan30/laif/blob/main/frontend/components/SoundManager.ts"
click node_ledger_ui "https://github.com/ndeshpan30/laif/blob/main/frontend/app/ledger/page.tsx"
click node_graph_ui "https://github.com/ndeshpan30/laif/blob/main/frontend/app/web/page.tsx"
click node_graph_view "https://github.com/ndeshpan30/laif/blob/main/frontend/components/KnowledgeGraphView.tsx"
click node_api "https://github.com/ndeshpan30/laif/blob/main/backend/app/main.py"
click node_conversation_api "https://github.com/ndeshpan30/laif/blob/main/backend/app/api/conversation.py"
click node_conversation_service "https://github.com/ndeshpan30/laif/blob/main/backend/app/services/conversation.py"
click node_llm "https://github.com/ndeshpan30/laif/blob/main/backend/app/services/gemini_client.py"
click node_scheduler "https://github.com/ndeshpan30/laif/blob/main/backend/app/solver/scheduler.py"
click node_schedule_api "https://github.com/ndeshpan30/laif/blob/main/backend/app/api/schedule.py"
click node_semantic_api "https://github.com/ndeshpan30/laif/blob/main/backend/app/api/semantic.py"
click node_rag "https://github.com/ndeshpan30/laif/blob/main/backend/app/services/rag.py"
click node_kg_api "https://github.com/ndeshpan30/laif/blob/main/backend/app/api/knowledge_graph.py"
click node_knowledge_graph "https://github.com/ndeshpan30/laif/blob/main/backend/app/services/knowledge_graph.py"
click node_telemetry_api "https://github.com/ndeshpan30/laif/blob/main/backend/app/api/telemetry.py"
click node_telemetry_engine "https://github.com/ndeshpan30/laif/blob/main/backend/app/services/telemetry_engine.py"
click node_tracker_api "https://github.com/ndeshpan30/laif/blob/main/backend/app/api/trackers.py"
click node_user_api "https://github.com/ndeshpan30/laif/blob/main/backend/app/api/user.py"
click node_database "https://github.com/ndeshpan30/laif/blob/main/backend/app/database.py"
click node_models "https://github.com/ndeshpan30/laif/tree/main/backend/app/models"

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_conversation_ui,node_speech,node_sound,node_ledger_ui,node_graph_ui,node_graph_view,node_user,node_browser_audio,node_client toneBlue
class node_api,node_conversation_api,node_conversation_service,node_llm,node_scheduler,node_schedule_api toneAmber
class node_semantic_api,node_rag,node_kg_api,node_knowledge_graph toneMint
class node_telemetry_api,node_telemetry_engine,node_tracker_api toneRose
class node_user_api,node_database,node_models,node_external_llm toneIndigo
```

## Components

### User Experience

- [Conversation UI](https://github.com/ndeshpan30/laif/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Speech Manager](https://github.com/ndeshpan30/laif/blob/main/frontend/components/SpeechManager.ts): `frontend/components/SpeechManager.ts`
- [Sound Manager](https://github.com/ndeshpan30/laif/blob/main/frontend/components/SoundManager.ts): `frontend/components/SoundManager.ts`
- [Ledger Dashboard](https://github.com/ndeshpan30/laif/blob/main/frontend/app/ledger/page.tsx): `frontend/app/ledger/page.tsx`
- [Knowledge Graph UI](https://github.com/ndeshpan30/laif/blob/main/frontend/app/web/page.tsx): `frontend/app/web/page.tsx`
- [Graph View & Details](https://github.com/ndeshpan30/laif/blob/main/frontend/components/KnowledgeGraphView.tsx): `frontend/components/KnowledgeGraphView.tsx`

### Conversation & Scheduling

- [FastAPI App](https://github.com/ndeshpan30/laif/blob/main/backend/app/main.py): `backend/app/main.py`
- [Conversation API](https://github.com/ndeshpan30/laif/blob/main/backend/app/api/conversation.py): `backend/app/api/conversation.py`
- [Conversation Service](https://github.com/ndeshpan30/laif/blob/main/backend/app/services/conversation.py): `backend/app/services/conversation.py`
- [Goal & Telemetry Extraction](https://github.com/ndeshpan30/laif/blob/main/backend/app/services/gemini_client.py): `backend/app/services/gemini_client.py`
- [CP-SAT Scheduler](https://github.com/ndeshpan30/laif/blob/main/backend/app/solver/scheduler.py): `backend/app/solver/scheduler.py`
- [Schedule API](https://github.com/ndeshpan30/laif/blob/main/backend/app/api/schedule.py): `backend/app/api/schedule.py`

### Memory & Knowledge Graph

- [Semantic API](https://github.com/ndeshpan30/laif/blob/main/backend/app/api/semantic.py): `backend/app/api/semantic.py`
- [Syllabus & Constraint RAG](https://github.com/ndeshpan30/laif/blob/main/backend/app/services/rag.py): `backend/app/services/rag.py`
- [Knowledge Graph API](https://github.com/ndeshpan30/laif/blob/main/backend/app/api/knowledge_graph.py): `backend/app/api/knowledge_graph.py`
- [Knowledge Graph Service](https://github.com/ndeshpan30/laif/blob/main/backend/app/services/knowledge_graph.py): `backend/app/services/knowledge_graph.py`

### BuJo Telemetry & Ledger

- [Telemetry API](https://github.com/ndeshpan30/laif/blob/main/backend/app/api/telemetry.py): `backend/app/api/telemetry.py`
- [Telemetry Engine](https://github.com/ndeshpan30/laif/blob/main/backend/app/services/telemetry_engine.py): `backend/app/services/telemetry_engine.py`
- [Tracker API](https://github.com/ndeshpan30/laif/blob/main/backend/app/api/trackers.py): `backend/app/api/trackers.py`

### Persistence

- [User API](https://github.com/ndeshpan30/laif/blob/main/backend/app/api/user.py): `backend/app/api/user.py`
- [Database Session & Schema](https://github.com/ndeshpan30/laif/blob/main/backend/app/database.py): `backend/app/database.py`
- [Domain Models](https://github.com/ndeshpan30/laif/tree/main/backend/app/models): `backend/app/models`

### Other components

- **User**
- **LLM Provider**
- **Browser Audio & Speech**
- **Frontend Client**

## Connections

- User → Conversation UI: states goals
- Conversation UI → Speech Manager: captures speech
- Conversation UI → FastAPI App: sends requests
- FastAPI App → Conversation API: dispatches
- Conversation API → Conversation Service: handles conversation
- Conversation Service → Goal & Telemetry Extraction: extracts intent
- Goal & Telemetry Extraction → LLM Provider: requests generation
- Conversation Service → CP-SAT Scheduler: solves schedule
- Conversation Service → Syllabus & Constraint RAG: retrieves context
- Conversation UI → Sound Manager: plays feedback
- Sound Manager → Browser Audio & Speech: generates tones
- Speech Manager → Browser Audio & Speech: uses speech APIs
- User → Semantic API: uploads syllabus
- FastAPI App → Semantic API: dispatches
- Semantic API → Syllabus & Constraint RAG: ingests and retrieves
- Syllabus & Constraint RAG → Database Session & Schema: reads and writes context
- User → Schedule API: manages schedule
- FastAPI App → Schedule API: dispatches
- Schedule API → CP-SAT Scheduler: solves schedule
- Schedule API → Database Session & Schema: reads and writes schedule
- User → Telemetry API: logs activities
- FastAPI App → Telemetry API: dispatches
- Telemetry API → Goal & Telemetry Extraction: extracts data points
- Telemetry API → Telemetry Engine: processes logs
- Telemetry Engine → Database Session & Schema: reads and writes trackers and logs
- Telemetry Engine → Knowledge Graph Service: syncs logged nodes
- User → Tracker API: manages trackers
- FastAPI App → Tracker API: dispatches
- Tracker API → Database Session & Schema: reads and writes trackers
- User → User API: manages profile
- FastAPI App → User API: dispatches
- User API → Database Session & Schema: reads and writes user
- Database Session & Schema → Domain Models: maps records
- Frontend Client → Ledger Dashboard: views ledger
- Frontend Client → Knowledge Graph UI: explores graph
- Knowledge Graph UI → FastAPI App: fetches graph
- FastAPI App → Knowledge Graph API: dispatches
- Knowledge Graph API → Knowledge Graph Service: builds graph
- Knowledge Graph Service → Database Session & Schema: reads graph data
- Knowledge Graph UI → Graph View & Details: renders filtered graph
- Ledger Dashboard → FastAPI App: loads ledger data