# mostafaai10/dopa_pal architecture

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

- Interactive diagram: https://gitdiagram.com/mostafaai10/dopa_pal
- Repository: https://github.com/mostafaai10/dopa_pal

## Overview

dopaPal is an ADHD-oriented desktop cognitive companion: users capture tasks through the ambient bubble or dashboard, the backend parses and prioritizes them, and the client presents manageable work. The broader product also covers energy/state tracking, focus, rewards, voice, chat, and Google/Notion sync. The graph reflects documented capabilities and indexed references; unsampled route internals and client IPC details limit some relationships.

Main entry points: [`server/app/services/ai/service.py`](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/service.py) (AI service), [`server/app/api/v1/tasks.py`](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/tasks.py) (Task routes), [`server/app/services/task_service.py`](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/task_service.py) (Task service), [`client/src/renderer/services/api.js`](https://github.com/mostafaai10/dopa_pal/blob/main/client/src/renderer/services/api.js) (Client API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop client"]
  node_bubble["Ambient bubble<br/>[Bubble.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_clientapi["Client API<br/>[api.js]"]
end

subgraph group_api["Backend API"]
  node_routes_tasks["Task routes<br/>[tasks.py]"]
  node_routes_state["State routes<br/>[state.py]"]
  node_routes_rewards["Reward routes<br/>[rewards.py]"]
  node_routes_chat["Chat routes<br/>[chat.py]"]
  node_routes_users["User routes<br/>[users.py]"]
  node_routes_integrations["Integration routes<br/>[integrations.py]"]
  node_routes_auth["OAuth routes<br/>[auth_google.py]"]
  node_routes_notion_auth["Notion OAuth<br/>[auth_notion.py]"]
  node_routes_sync["Sync routes<br/>[sync.py]"]
end

subgraph group_planning["Task intelligence"]
  node_task_service["Task service<br/>[task_service.py]"]
  node_ai_service["AI service<br/>[service.py]"]
  node_ingestion["Task ingestion<br/>[ingestion.py]"]
  node_chunking["Task chunking<br/>[chunking.py]"]
  node_pinch["PINCH ranking<br/>[pinch.py]"]
  node_segmentation["Task segmentation<br/>[segmentation.py]"]
  node_schemas["AI schemas<br/>[schemas.py]"]
  node_nvidia["NVIDIA LLM client<br/>[nvidia_client.py]"]
end

subgraph group_services["Support services"]
  node_state_service["State scoring<br/>[state_service.py]"]
  node_reward_service["Rewards and vault<br/>[reward_service.py]"]
  node_focus["Focus mode<br/>[focus_mode.py]"]
  node_speech["Speech transcription<br/>[speech_to_text.py]"]
  node_notifications["Notifications"]
  node_websocket["WebSocket manager"]
  node_integration_service["Integration manager"]
  node_google_service["Google sync<br/>[google_service.py]"]
  node_notion_service["Notion sync<br/>[notion_service.py]"]
end

subgraph group_persistence["Persistence"]
  node_store[("SQL database<br/>[database.py]")]
  node_task_model["Tasks and blocks<br/>[task.py]"]
  node_user_model["Users<br/>[user.py]"]
  node_state_model["State logs<br/>[state.py]"]
end

node_user(("User"))

node_user -->|"captures tasks"| node_bubble
node_user -->|"manages work"| node_dashboard
node_bubble -->|"requests data"| node_clientapi
node_dashboard -->|"requests data"| node_clientapi
node_clientapi -.->|"calls API"| node_routes_tasks
node_clientapi -.->|"calls API"| node_routes_users
node_routes_tasks -->|"delegates tasks"| node_task_service
node_routes_tasks -->|"transcribes audio"| node_speech
node_routes_tasks -->|"toggles focus"| node_focus
node_routes_tasks -->|"uses notifications"| node_notifications
node_routes_tasks -->|"broadcasts updates"| node_websocket
node_task_service -->|"requests analysis"| node_ai_service
node_task_service -->|"persists tasks"| node_task_model
node_ai_service -->|"parses input"| node_ingestion
node_ai_service -->|"chunks tasks"| node_chunking
node_ai_service -->|"scores tasks"| node_pinch
node_ai_service -->|"plans steps"| node_segmentation
node_ai_service -->|"enriches with LLM"| node_nvidia
node_ingestion -.->|"optionally enriches"| node_nvidia
node_routes_state -.->|"computes state"| node_state_service
node_state_service -.->|"stores scores"| node_state_model
node_routes_rewards -.->|"manages rewards"| node_reward_service
node_routes_chat -.->|"uses AI"| node_ai_service
node_routes_integrations -.->|"manages providers"| node_integration_service
node_routes_auth -->|"stores OAuth"| node_integration_service
node_routes_notion_auth -->|"stores OAuth"| node_integration_service
node_routes_sync -.->|"manages sync"| node_google_service
node_routes_sync -.->|"manages sync"| node_notion_service
node_integration_service -->|"configures sync"| node_notion_service
node_google_service -->|"ingests tasks"| node_task_service
node_notion_service -->|"ingests tasks"| node_task_service
node_task_model -->|"uses ORM base"| node_store
node_user_model -->|"uses ORM base"| node_store

click node_bubble "https://github.com/mostafaai10/dopa_pal/blob/main/client/src/renderer/components/Bubble/Bubble.jsx"
click node_dashboard "https://github.com/mostafaai10/dopa_pal/blob/main/client/src/renderer/components/Dashboard/Dashboard.jsx"
click node_clientapi "https://github.com/mostafaai10/dopa_pal/blob/main/client/src/renderer/services/api.js"
click node_routes_tasks "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/tasks.py"
click node_routes_state "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/state.py"
click node_routes_rewards "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/rewards.py"
click node_routes_chat "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/chat.py"
click node_routes_users "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/users.py"
click node_routes_integrations "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/integrations.py"
click node_routes_auth "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/auth_google.py"
click node_routes_notion_auth "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/auth_notion.py"
click node_routes_sync "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/sync.py"
click node_task_service "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/task_service.py"
click node_ai_service "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/service.py"
click node_ingestion "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/ingestion.py"
click node_chunking "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/chunking.py"
click node_pinch "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/pinch.py"
click node_segmentation "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/segmentation.py"
click node_schemas "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/schemas.py"
click node_nvidia "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/llm/nvidia_client.py"
click node_state_service "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/state_service.py"
click node_reward_service "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/reward_service.py"
click node_focus "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/focus_mode.py"
click node_speech "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/speech_to_text.py"
click node_notifications "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/enhanced_notification.py"
click node_websocket "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/websocket_manager.py"
click node_integration_service "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/integration_service.py"
click node_google_service "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/google_service.py"
click node_notion_service "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/notion_service.py"
click node_store "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/core/database.py"
click node_task_model "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/models/task.py"
click node_user_model "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/models/user.py"
click node_state_model "https://github.com/mostafaai10/dopa_pal/blob/main/server/app/models/state.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_bubble,node_dashboard,node_clientapi,node_user toneBlue
class node_routes_tasks,node_routes_state,node_routes_rewards,node_routes_chat,node_routes_users,node_routes_integrations,node_routes_auth,node_routes_notion_auth,node_routes_sync toneAmber
class node_task_service,node_ai_service,node_ingestion,node_chunking,node_pinch,node_segmentation,node_schemas,node_nvidia toneMint
class node_state_service,node_reward_service,node_focus,node_speech,node_notifications,node_websocket,node_integration_service,node_google_service,node_notion_service toneRose
class node_store,node_task_model,node_user_model,node_state_model toneIndigo
```

## Components

### Desktop client

- [Ambient bubble](https://github.com/mostafaai10/dopa_pal/blob/main/client/src/renderer/components/Bubble/Bubble.jsx): `client/src/renderer/components/Bubble/Bubble.jsx`
- [Dashboard](https://github.com/mostafaai10/dopa_pal/blob/main/client/src/renderer/components/Dashboard/Dashboard.jsx): `client/src/renderer/components/Dashboard/Dashboard.jsx`
- [Client API](https://github.com/mostafaai10/dopa_pal/blob/main/client/src/renderer/services/api.js): `client/src/renderer/services/api.js`

### Backend API

- [Task routes](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/tasks.py): `server/app/api/v1/tasks.py`
- [State routes](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/state.py): `server/app/api/v1/state.py`
- [Reward routes](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/rewards.py): `server/app/api/v1/rewards.py`
- [Chat routes](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/chat.py): `server/app/api/v1/chat.py`
- [User routes](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/users.py): `server/app/api/v1/users.py`
- [Integration routes](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/integrations.py): `server/app/api/v1/integrations.py`
- [OAuth routes](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/auth_google.py): `server/app/api/v1/auth_google.py`
- [Notion OAuth](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/auth_notion.py): `server/app/api/v1/auth_notion.py`
- [Sync routes](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/api/v1/sync.py): `server/app/api/v1/sync.py`

### Task intelligence

- [Task service](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/task_service.py): `server/app/services/task_service.py`
- [AI service](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/service.py): `server/app/services/ai/service.py`
- [Task ingestion](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/ingestion.py): `server/app/services/ai/ingestion.py`
- [Task chunking](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/chunking.py): `server/app/services/ai/chunking.py`
- [PINCH ranking](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/pinch.py): `server/app/services/ai/pinch.py`
- [Task segmentation](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/segmentation.py): `server/app/services/ai/segmentation.py`
- [AI schemas](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/schemas.py): `server/app/services/ai/schemas.py`
- [NVIDIA LLM client](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/ai/llm/nvidia_client.py): `server/app/services/ai/llm/nvidia_client.py`

### Support services

- [State scoring](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/state_service.py): `server/app/services/state_service.py`
- [Rewards and vault](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/reward_service.py): `server/app/services/reward_service.py`
- [Focus mode](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/focus_mode.py): `server/app/services/focus_mode.py`
- [Speech transcription](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/speech_to_text.py): `server/app/services/speech_to_text.py`
- [Notifications](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/enhanced_notification.py): `server/app/services/enhanced_notification.py`
- [WebSocket manager](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/websocket_manager.py): `server/app/services/websocket_manager.py`
- [Integration manager](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/integration_service.py): `server/app/services/integration_service.py`
- [Google sync](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/google_service.py): `server/app/services/google_service.py`
- [Notion sync](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/services/notion_service.py): `server/app/services/notion_service.py`

### Persistence

- [SQL database](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/core/database.py): `server/app/core/database.py`
- [Tasks and blocks](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/models/task.py): `server/app/models/task.py`
- [Users](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/models/user.py): `server/app/models/user.py`
- [State logs](https://github.com/mostafaai10/dopa_pal/blob/main/server/app/models/state.py): `server/app/models/state.py`

### Other components

- **User**

## Connections

- User → Ambient bubble: captures tasks
- User → Dashboard: manages work
- Ambient bubble → Client API: requests data (evidence: `client/src/renderer/components/Bubble/Bubble.jsx`)
- Dashboard → Client API: requests data (evidence: `client/src/renderer/components/Dashboard/Dashboard.jsx`)
- Client API → Task routes: calls API
- Client API → User routes: calls API
- Task routes → Task service: delegates tasks (evidence: `server/app/api/v1/tasks.py`)
- Task routes → Speech transcription: transcribes audio (evidence: `server/app/api/v1/tasks.py`)
- Task routes → Focus mode: toggles focus (evidence: `server/app/api/v1/tasks.py`)
- Task routes → Notifications: uses notifications (evidence: `server/app/api/v1/tasks.py`)
- Task routes → WebSocket manager: broadcasts updates (evidence: `server/app/api/v1/tasks.py`)
- Task service → AI service: requests analysis (evidence: `server/app/services/task_service.py`)
- Task service → Tasks and blocks: persists tasks (evidence: `server/app/services/task_service.py`)
- AI service → Task ingestion: parses input (evidence: `server/app/services/ai/service.py`)
- AI service → Task chunking: chunks tasks (evidence: `server/app/services/ai/service.py`)
- AI service → PINCH ranking: scores tasks (evidence: `server/app/services/ai/service.py`)
- AI service → Task segmentation: plans steps (evidence: `server/app/services/ai/service.py`)
- AI service → NVIDIA LLM client: enriches with LLM (evidence: `server/app/services/ai/service.py`)
- Task ingestion → NVIDIA LLM client: optionally enriches (evidence: `server/app/services/ai/ingestion.py`)
- State routes → State scoring: computes state
- State scoring → State logs: stores scores
- Reward routes → Rewards and vault: manages rewards
- Chat routes → AI service: uses AI
- Integration routes → Integration manager: manages providers
- OAuth routes → Integration manager: stores OAuth (evidence: `server/app/api/v1/auth_google.py`)
- Notion OAuth → Integration manager: stores OAuth (evidence: `server/app/api/v1/auth_notion.py`)
- Sync routes → Google sync: manages sync
- Sync routes → Notion sync: manages sync
- Integration manager → Notion sync: configures sync (evidence: `server/app/services/integration_service.py`)
- Google sync → Task service: ingests tasks (evidence: `server/app/services/google_service.py`)
- Notion sync → Task service: ingests tasks (evidence: `server/app/services/notion_service.py`)
- Tasks and blocks → SQL database: uses ORM base (evidence: `server/app/models/task.py`)
- Users → SQL database: uses ORM base (evidence: `server/app/models/user.py`)
