# thiagobraga/planner architecture

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

- Interactive diagram: https://gitdiagram.com/thiagobraga/planner
- Repository: https://github.com/thiagobraga/planner

## Overview

Planner is a Bullet Journal-style task manager: users plan daily tasks, organize collections, track habits, and sync changes across devices. The React app presents these workflows and calls the API; the API handles authentication, domain services, and persistence. AI-agent access is provided through MCP tools and OAuth. The standalone site is a separate product-facing landing page. Relationships are limited to those visible in sampled imports/calls or stated in the README; unsampled feature internals are represented at their source paths, with no inferred internal call chains.

Main entry points: [`app/src/App.tsx`](https://github.com/thiagobraga/planner/blob/main/app/src/App.tsx) (App shell), [`app/src/api/client.ts`](https://github.com/thiagobraga/planner/blob/main/app/src/api/client.ts) (API client), [`api/src/index.ts`](https://github.com/thiagobraga/planner/blob/main/api/src/index.ts) (HTTP API), [`api/src/services/authService.ts`](https://github.com/thiagobraga/planner/blob/main/api/src/services/authService.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Planner app"]
  node_app["App shell<br/>[App.tsx]"]
  node_daily["Daily planning<br/>[DailyPage.tsx]"]
  node_collections["Collections"]
  node_habits["Habit tracking<br/>[HabitsPage.tsx]"]
  node_settings["Settings and account<br/>[SettingsPage.tsx]"]
  node_taskdetail["Task detail"]
  node_api_client["API client<br/>[client.ts]"]
  node_offline["Offline and live sync"]
end

subgraph group_api["API services"]
  node_api_entry["HTTP API<br/>[index.ts]"]
  node_auth["Authentication<br/>[authService.ts]"]
  node_sessions["Session management<br/>[sessionService.ts]"]
  node_task_service["Task operations<br/>[taskService.ts]"]
  node_task_routes["Task endpoints<br/>[tasks.ts]"]
  node_recurrence["Recurrence engine"]
  node_database[("PostgreSQL<br/>[pool.ts]")]
  node_imports["Task imports<br/>[importService.ts]"]
  node_documents["Rich task documents<br/>[store.ts]"]
end

subgraph group_integrations["Agent integrations"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_mcp_tasks["MCP task tools<br/>[tasks.ts]"]
  node_oauth["OAuth authorization<br/>[oauthService.ts]"]
end

subgraph group_landing["Landing site"]
  node_landing_app["Marketing pages<br/>[App.tsx]"]
end

node_user(("Planner user"))
node_site_visitor(("Site visitor"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_daily
node_app -->|"routes to"| node_collections
node_app -->|"routes to"| node_habits
node_app -->|"routes to"| node_settings
node_daily -.->|"requests data"| node_api_client
node_collections -.->|"requests data"| node_api_client
node_habits -.->|"requests data"| node_api_client
node_taskdetail -.->|"controls detail state"| node_app
node_api_client -.->|"sends requests"| node_api_entry
node_offline -.->|"replays edits"| node_api_client
node_user -->|"authenticates"| node_api_entry
node_api_entry -.->|"handles auth"| node_auth
node_auth -->|"creates sessions"| node_sessions
node_api_entry -->|"routes requests"| node_task_routes
node_task_routes -->|"calls"| node_task_service
node_task_service -->|"queries"| node_database
node_auth -->|"queries"| node_database
node_user -->|"connects agent"| node_mcp
node_mcp -->|"registers tools"| node_mcp_tasks
node_mcp_tasks -->|"calls task operations"| node_task_service
node_user -->|"approves client"| node_oauth
node_oauth -.->|"stores grants"| node_database
node_user -.->|"imports tasks"| node_imports
node_user -.->|"edits documents"| node_documents
node_site_visitor -->|"visits"| node_landing_app

click node_app "https://github.com/thiagobraga/planner/blob/main/app/src/App.tsx"
click node_daily "https://github.com/thiagobraga/planner/blob/main/app/src/pages/DailyPage.tsx"
click node_collections "https://github.com/thiagobraga/planner/blob/main/app/src/pages/CollectionsPage.tsx"
click node_habits "https://github.com/thiagobraga/planner/blob/main/app/src/pages/HabitsPage.tsx"
click node_settings "https://github.com/thiagobraga/planner/blob/main/app/src/pages/SettingsPage.tsx"
click node_taskdetail "https://github.com/thiagobraga/planner/blob/main/app/src/hooks/useTaskDetailController.ts"
click node_api_client "https://github.com/thiagobraga/planner/blob/main/app/src/api/client.ts"
click node_offline "https://github.com/thiagobraga/planner/blob/main/app/src/hooks/useOfflineQueueReplay.ts"
click node_api_entry "https://github.com/thiagobraga/planner/blob/main/api/src/index.ts"
click node_auth "https://github.com/thiagobraga/planner/blob/main/api/src/services/authService.ts"
click node_sessions "https://github.com/thiagobraga/planner/blob/main/api/src/services/sessionService.ts"
click node_task_service "https://github.com/thiagobraga/planner/blob/main/api/src/services/taskService.ts"
click node_task_routes "https://github.com/thiagobraga/planner/blob/main/api/src/routes/tasks.ts"
click node_recurrence "https://github.com/thiagobraga/planner/blob/main/api/src/engines/recurrenceEngine.ts"
click node_database "https://github.com/thiagobraga/planner/blob/main/api/src/db/pool.ts"
click node_mcp "https://github.com/thiagobraga/planner/blob/main/api/src/mcp/server.ts"
click node_mcp_tasks "https://github.com/thiagobraga/planner/blob/main/api/src/mcp/tools/tasks.ts"
click node_oauth "https://github.com/thiagobraga/planner/blob/main/api/src/services/oauthService.ts"
click node_imports "https://github.com/thiagobraga/planner/blob/main/api/src/services/import/importService.ts"
click node_documents "https://github.com/thiagobraga/planner/blob/main/api/src/services/document/store.ts"
click node_landing_app "https://github.com/thiagobraga/planner/blob/main/site/src/App.tsx"

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_daily,node_collections,node_habits,node_settings,node_taskdetail,node_api_client,node_offline,node_user toneBlue
class node_api_entry,node_auth,node_sessions,node_task_service,node_task_routes,node_recurrence,node_database,node_imports,node_documents toneAmber
class node_mcp,node_mcp_tasks,node_oauth toneMint
class node_landing_app toneRose
class node_site_visitor toneIndigo
```

## Components

### Planner app

- [App shell](https://github.com/thiagobraga/planner/blob/main/app/src/App.tsx): `app/src/App.tsx`
- [Daily planning](https://github.com/thiagobraga/planner/blob/main/app/src/pages/DailyPage.tsx): `app/src/pages/DailyPage.tsx`
- [Collections](https://github.com/thiagobraga/planner/blob/main/app/src/pages/CollectionsPage.tsx): `app/src/pages/CollectionsPage.tsx`
- [Habit tracking](https://github.com/thiagobraga/planner/blob/main/app/src/pages/HabitsPage.tsx): `app/src/pages/HabitsPage.tsx`
- [Settings and account](https://github.com/thiagobraga/planner/blob/main/app/src/pages/SettingsPage.tsx): `app/src/pages/SettingsPage.tsx`
- [Task detail](https://github.com/thiagobraga/planner/blob/main/app/src/hooks/useTaskDetailController.ts): `app/src/hooks/useTaskDetailController.ts`
- [API client](https://github.com/thiagobraga/planner/blob/main/app/src/api/client.ts): `app/src/api/client.ts`
- [Offline and live sync](https://github.com/thiagobraga/planner/blob/main/app/src/hooks/useOfflineQueueReplay.ts): `app/src/hooks/useOfflineQueueReplay.ts`

### API services

- [HTTP API](https://github.com/thiagobraga/planner/blob/main/api/src/index.ts): `api/src/index.ts`
- [Authentication](https://github.com/thiagobraga/planner/blob/main/api/src/services/authService.ts): `api/src/services/authService.ts`
- [Session management](https://github.com/thiagobraga/planner/blob/main/api/src/services/sessionService.ts): `api/src/services/sessionService.ts`
- [Task operations](https://github.com/thiagobraga/planner/blob/main/api/src/services/taskService.ts): `api/src/services/taskService.ts`
- [Task endpoints](https://github.com/thiagobraga/planner/blob/main/api/src/routes/tasks.ts): `api/src/routes/tasks.ts`
- [Recurrence engine](https://github.com/thiagobraga/planner/blob/main/api/src/engines/recurrenceEngine.ts): `api/src/engines/recurrenceEngine.ts`
- [PostgreSQL](https://github.com/thiagobraga/planner/blob/main/api/src/db/pool.ts): `api/src/db/pool.ts`
- [Task imports](https://github.com/thiagobraga/planner/blob/main/api/src/services/import/importService.ts): `api/src/services/import/importService.ts`
- [Rich task documents](https://github.com/thiagobraga/planner/blob/main/api/src/services/document/store.ts): `api/src/services/document/store.ts`

### Agent integrations

- [MCP server](https://github.com/thiagobraga/planner/blob/main/api/src/mcp/server.ts): `api/src/mcp/server.ts`
- [MCP task tools](https://github.com/thiagobraga/planner/blob/main/api/src/mcp/tools/tasks.ts): `api/src/mcp/tools/tasks.ts`
- [OAuth authorization](https://github.com/thiagobraga/planner/blob/main/api/src/services/oauthService.ts): `api/src/services/oauthService.ts`

### Landing site

- [Marketing pages](https://github.com/thiagobraga/planner/blob/main/site/src/App.tsx): `site/src/App.tsx`

### Other components

- **Planner user**
- **Site visitor**

## Connections

- Planner user → App shell: uses (evidence: `README.md`)
- App shell → Daily planning: routes to (evidence: `app/src/App.tsx`)
- App shell → Collections: routes to (evidence: `app/src/App.tsx`)
- App shell → Habit tracking: routes to (evidence: `app/src/App.tsx`)
- App shell → Settings and account: routes to (evidence: `app/src/App.tsx`)
- Daily planning → API client: requests data
- Collections → API client: requests data
- Habit tracking → API client: requests data
- Task detail → App shell: controls detail state
- API client → HTTP API: sends requests
- Offline and live sync → API client: replays edits
- Planner user → HTTP API: authenticates (evidence: `README.md`)
- HTTP API → Authentication: handles auth
- Authentication → Session management: creates sessions (evidence: `api/src/services/authService.ts`)
- HTTP API → Task endpoints: routes requests (evidence: `api/src/index.ts`)
- Task endpoints → Task operations: calls (evidence: `api/src/routes/tasks.ts`)
- Task operations → PostgreSQL: queries (evidence: `api/src/services/taskService.ts`)
- Authentication → PostgreSQL: queries (evidence: `api/src/services/authService.ts`)
- Planner user → MCP server: connects agent (evidence: `README.md`)
- MCP server → MCP task tools: registers tools (evidence: `api/src/mcp/server.ts`)
- MCP task tools → Task operations: calls task operations (evidence: `api/src/mcp/tools/tasks.ts`)
- Planner user → OAuth authorization: approves client (evidence: `README.md`)
- OAuth authorization → PostgreSQL: stores grants (evidence: `api/src/services/oauthService.ts`)
- Planner user → Task imports: imports tasks
- Planner user → Rich task documents: edits documents
- Site visitor → Marketing pages: visits (evidence: `site/src/App.tsx`)
