# thesabbirbd/omnidesk-bd architecture

> Architecture diagram of the GitHub repository thesabbirbd/omnidesk-bd, 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/thesabbirbd/omnidesk-bd
- Repository: https://github.com/thesabbirbd/omnidesk-bd

## Overview

Omnidesk BD is a local-first learning and engineering workspace. Learners bring in source material, develop structured study topics, and work through competency evidence, review, scheduling, and practical debugging; the app also provides a knowledge graph, analytics, and a persistent focus timer. The graph reflects documented product capabilities and sampled orchestration and validation code; some feature wiring is not shown in the excerpts, so uncertain internal call paths are omitted.

Main entry points: [`backend/main.py`](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/main.py) (FastAPI application), [`frontend/src/App.jsx`](https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/App.jsx) (Application routes), [`backend/app/db/session.py`](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/db/session.py) (Application database), [`backend/app/ai/service.py`](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/ai/service.py) (Provider cascade)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learning workspace"]
  node_app["Application routes<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_materials_ui["Materials hub<br/>[Materials.jsx]"]
  node_mindmap_ui["Mind map<br/>[MindMap.jsx]"]
  node_study_ui["Study engine<br/>[StudyEngine.jsx]"]
  node_timer["Focus timer<br/>[TimerContext.jsx]"]
end

subgraph group_content["Content pipeline"]
  node_materials_api["Materials API<br/>[materials.py]"]
  node_document_processor["Document processor"]
  node_parsers["Format parsers"]
  node_ai_api["AI API<br/>[ai.py]"]
  node_ai_service["Provider cascade<br/>[service.py]"]
end

subgraph group_learning["Study and mastery"]
  node_study_spaces_api["Study spaces API<br/>[study_spaces.py]"]
  node_topics_api["Topics API<br/>[topics.py]"]
  node_competency["Competency gates"]
  node_scheduler["Study scheduler<br/>[scheduler.py]"]
  node_knowledge_api["Knowledge graph API<br/>[knowledge_graph.py]"]
  node_knowledge_service["Knowledge graph builder"]
  node_lab_api["Sandboxed DevOps lab<br/>[lab.py]"]
  node_debug_api["Debug journals API<br/>[debug_journals.py]"]
  node_analytics_api["Analytics API<br/>[analytics.py]"]
end

subgraph group_platform["Backend platform"]
  node_database[("Application database<br/>[session.py]")]
  node_backend["FastAPI application<br/>[main.py]"]
end

node_learner(("Learner"))
node_gemini{{"Gemini service"}}
node_ollama{{"Ollama service"}}

node_learner -->|"uses"| node_app
node_app -->|"requests data"| node_api_client
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_materials_ui
node_app -->|"routes to"| node_mindmap_ui
node_app -->|"routes to"| node_study_ui
node_app -->|"provides timer"| node_timer
node_api_client -->|"sends API requests"| node_backend
node_backend -->|"dispatches"| node_materials_api
node_backend -->|"dispatches"| node_ai_api
node_backend -->|"dispatches"| node_study_spaces_api
node_backend -->|"dispatches"| node_topics_api
node_backend -->|"dispatches"| node_knowledge_api
node_backend -->|"dispatches"| node_lab_api
node_backend -->|"dispatches"| node_debug_api
node_backend -->|"dispatches"| node_analytics_api
node_materials_api -->|"processes material"| node_document_processor
node_document_processor -->|"parses formats"| node_parsers
node_ai_api -->|"requests analysis"| node_ai_service
node_ai_service -.->|"tries provider"| node_gemini
node_ai_service -.->|"tries provider"| node_ollama
node_ai_service -->|"returns structured result"| node_database
node_study_spaces_api -->|"reads and writes"| node_database
node_topics_api -->|"reads and writes"| node_database
node_topics_api -->|"validates completion"| node_competency
node_competency -->|"checks evidence and sessions"| node_database
node_scheduler -->|"uses study records"| node_database
node_knowledge_api -->|"builds topic graph"| node_knowledge_service
node_knowledge_service -->|"reads related records"| node_database
node_lab_api -.->|"records debugging"| node_debug_api
node_debug_api -->|"reads and writes"| node_database
node_analytics_api -->|"reads activity"| node_database

click node_app "https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/services/api.js"
click node_dashboard "https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/pages/Dashboard.jsx"
click node_materials_ui "https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/pages/Materials.jsx"
click node_mindmap_ui "https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/pages/MindMap.jsx"
click node_study_ui "https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/pages/StudyEngine.jsx"
click node_timer "https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/context/TimerContext.jsx"
click node_materials_api "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/materials.py"
click node_document_processor "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/services/document_processor.py"
click node_parsers "https://github.com/thesabbirbd/omnidesk-bd/tree/main/backend/app/ingestion/parsers"
click node_ai_api "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/ai.py"
click node_ai_service "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/ai/service.py"
click node_study_spaces_api "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/study_spaces.py"
click node_topics_api "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/topics.py"
click node_competency "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/services/competency_engine.py"
click node_scheduler "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/services/scheduler.py"
click node_knowledge_api "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/knowledge_graph.py"
click node_knowledge_service "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/services/knowledge_graph_service.py"
click node_lab_api "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/lab.py"
click node_debug_api "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/debug_journals.py"
click node_analytics_api "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/analytics.py"
click node_database "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/db/session.py"
click node_backend "https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/main.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_app,node_api_client,node_dashboard,node_materials_ui,node_mindmap_ui,node_study_ui,node_timer toneBlue
class node_materials_api,node_document_processor,node_parsers,node_ai_api,node_ai_service toneAmber
class node_study_spaces_api,node_topics_api,node_competency,node_scheduler,node_knowledge_api,node_knowledge_service,node_lab_api,node_debug_api,node_analytics_api toneMint
class node_database,node_backend toneRose
class node_learner,node_gemini,node_ollama toneIndigo
```

## Components

### Learning workspace

- [Application routes](https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Dashboard](https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Materials hub](https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/pages/Materials.jsx): `frontend/src/pages/Materials.jsx`
- [Mind map](https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/pages/MindMap.jsx): `frontend/src/pages/MindMap.jsx`
- [Study engine](https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/pages/StudyEngine.jsx): `frontend/src/pages/StudyEngine.jsx`
- [Focus timer](https://github.com/thesabbirbd/omnidesk-bd/blob/main/frontend/src/context/TimerContext.jsx): `frontend/src/context/TimerContext.jsx`

### Content pipeline

- [Materials API](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/materials.py): `backend/app/api/materials.py`
- [Document processor](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/services/document_processor.py): `backend/app/services/document_processor.py`
- [Format parsers](https://github.com/thesabbirbd/omnidesk-bd/tree/main/backend/app/ingestion/parsers): `backend/app/ingestion/parsers`
- [AI API](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/ai.py): `backend/app/api/ai.py`
- [Provider cascade](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/ai/service.py): `backend/app/ai/service.py`

### Study and mastery

- [Study spaces API](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/study_spaces.py): `backend/app/api/study_spaces.py`
- [Topics API](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/topics.py): `backend/app/api/topics.py`
- [Competency gates](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/services/competency_engine.py): `backend/app/services/competency_engine.py`
- [Study scheduler](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/services/scheduler.py): `backend/app/services/scheduler.py`
- [Knowledge graph API](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/knowledge_graph.py): `backend/app/api/knowledge_graph.py`
- [Knowledge graph builder](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/services/knowledge_graph_service.py): `backend/app/services/knowledge_graph_service.py`
- [Sandboxed DevOps lab](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/lab.py): `backend/app/api/lab.py`
- [Debug journals API](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/debug_journals.py): `backend/app/api/debug_journals.py`
- [Analytics API](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/api/analytics.py): `backend/app/api/analytics.py`

### Backend platform

- [Application database](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [FastAPI application](https://github.com/thesabbirbd/omnidesk-bd/blob/main/backend/main.py): `backend/main.py`

### Other components

- **Learner**
- **Gemini service**
- **Ollama service**

## Connections

- Learner → Application routes: uses
- Application routes → API client: requests data
- Application routes → Dashboard: routes to
- Application routes → Materials hub: routes to
- Application routes → Mind map: routes to
- Application routes → Study engine: routes to
- Application routes → Focus timer: provides timer
- API client → FastAPI application: sends API requests
- FastAPI application → Materials API: dispatches
- FastAPI application → AI API: dispatches
- FastAPI application → Study spaces API: dispatches
- FastAPI application → Topics API: dispatches
- FastAPI application → Knowledge graph API: dispatches
- FastAPI application → Sandboxed DevOps lab: dispatches
- FastAPI application → Debug journals API: dispatches
- FastAPI application → Analytics API: dispatches
- Materials API → Document processor: processes material
- Document processor → Format parsers: parses formats
- AI API → Provider cascade: requests analysis
- Provider cascade → Gemini service: tries provider
- Provider cascade → Ollama service: tries provider
- Provider cascade → Application database: returns structured result
- Study spaces API → Application database: reads and writes
- Topics API → Application database: reads and writes
- Topics API → Competency gates: validates completion
- Competency gates → Application database: checks evidence and sessions
- Study scheduler → Application database: uses study records
- Knowledge graph API → Knowledge graph builder: builds topic graph
- Knowledge graph builder → Application database: reads related records
- Sandboxed DevOps lab → Debug journals API: records debugging
- Debug journals API → Application database: reads and writes
- Analytics API → Application database: reads activity