# t1mothys/orbit architecture

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

- Interactive diagram: https://gitdiagram.com/t1mothys/orbit
- Repository: https://github.com/t1mothys/orbit

## Overview

Orbit is a chat-first personal workspace, available as Web and Electron. A user signs in, starts in the main conversation, and uses it to manage schedules, reminders, notes, and other personal work; schedule writes require confirmation. Separate areas provide knowledge/library, search, research, and local or cloud daily reports. The server exposes authenticated routes and persists application data across database stores; optional CalDAV, mail, AI providers, and cloud reporting extend the core. The graph combines README capabilities with indexed and excerpted source; some subsystem links are documented only at product level.

Main entry points: [`server/routes/ai.ts`](https://github.com/t1mothys/orbit/blob/main/server/routes/ai.ts) (AI conversation), [`server/application.ts`](https://github.com/t1mothys/orbit/blob/main/server/application.ts) (HTTP application), [`src/App.tsx`](https://github.com/t1mothys/orbit/blob/main/src/App.tsx) (Web app), [`server/search-service.ts`](https://github.com/t1mothys/orbit/blob/main/server/search-service.ts) (Global search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web app<br/>[App.tsx]"]
  node_auth["Authentication<br/>[useAuth.ts]"]
  node_electron["Electron host<br/>[main.ts]"]
end

subgraph group_workflow["Conversation and planning"]
  node_ai["AI conversation<br/>[ai.ts]"]
  node_chat["Chat experience<br/>[useOrbitChat.ts]"]
  node_queue["Conversation queue<br/>[orbit-queue.ts]"]
  node_scheduling["Schedule management<br/>[schedule-store.ts]"]
  node_reminders["Reminders<br/>[reminder-store.ts]"]
  node_caldav["CalDAV bridge<br/>[caldav-service.ts]"]
  node_ai_provider["AI providers"]
end

subgraph group_knowledge["Knowledge and research"]
  node_notes["Notes and images"]
  node_library["Knowledge library<br/>[library-service.ts]"]
  node_search["Global search<br/>[search-service.ts]"]
  node_research["Digest research"]
  node_digest["Digest V3<br/>[digest-v3-store.ts]"]
end

subgraph group_reports["Reports and activity"]
  node_activity[("Activity reports<br/>[activity-store.ts]")]
  node_daily["Daily reports"]
  node_cloud[("Cloud reporting")]
  node_email["Email service<br/>[email-service.ts]"]
end

subgraph group_platform["Server and persistence"]
  node_server["HTTP application<br/>[application.ts]"]
  node_db[("Application database<br/>[connection.ts]")]
  node_persistence["Durable persistence<br/>[persistence.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"checks session"| node_auth
node_auth -->|"auth requests"| node_server
node_web -.->|"uses API"| node_server
node_electron -.->|"hosts"| node_web
node_server -->|"mounts routes"| node_ai
node_server -.->|"mounts routes"| node_search
node_server -->|"mounts routes"| node_research
node_server -->|"mounts routes"| node_digest
node_chat -.->|"sends messages"| node_ai
node_ai -.->|"queues work"| node_queue
node_ai -->|"uses providers"| node_ai_provider
node_ai -.->|"manages schedules"| node_scheduling
node_ai -.->|"manages notes"| node_notes
node_ai -.->|"manages reminders"| node_reminders
node_search -->|"reads projections"| node_reminders
node_search -.->|"searches conversations"| node_ai
node_research -->|"uses stores"| node_activity
node_digest -->|"persists digest data"| node_activity
node_daily -.->|"stores reports"| node_activity
node_daily -.->|"uses cloud store"| node_cloud
node_caldav -->|"reads schedules"| node_scheduling
node_caldav -->|"reads reminders"| node_reminders
node_db -->|"persists database"| node_persistence
node_server -.->|"initializes stores"| node_db
node_email -.->|"delivers reports"| node_daily

click node_web "https://github.com/t1mothys/orbit/blob/main/src/App.tsx"
click node_auth "https://github.com/t1mothys/orbit/blob/main/src/hooks/useAuth.ts"
click node_electron "https://github.com/t1mothys/orbit/blob/main/electron/main.ts"
click node_server "https://github.com/t1mothys/orbit/blob/main/server/application.ts"
click node_ai "https://github.com/t1mothys/orbit/blob/main/server/routes/ai.ts"
click node_chat "https://github.com/t1mothys/orbit/blob/main/src/hooks/useOrbitChat.ts"
click node_queue "https://github.com/t1mothys/orbit/blob/main/server/orbit-queue.ts"
click node_scheduling "https://github.com/t1mothys/orbit/blob/main/server/schedule-store.ts"
click node_reminders "https://github.com/t1mothys/orbit/blob/main/server/reminder-store.ts"
click node_caldav "https://github.com/t1mothys/orbit/blob/main/server/caldav-service.ts"
click node_notes "https://github.com/t1mothys/orbit/blob/main/server/note-item-service.ts"
click node_library "https://github.com/t1mothys/orbit/blob/main/server/library-service.ts"
click node_search "https://github.com/t1mothys/orbit/blob/main/server/search-service.ts"
click node_research "https://github.com/t1mothys/orbit/blob/main/server/digest-research-store.ts"
click node_digest "https://github.com/t1mothys/orbit/blob/main/server/digest-v3-store.ts"
click node_activity "https://github.com/t1mothys/orbit/blob/main/server/activity-store.ts"
click node_daily "https://github.com/t1mothys/orbit/blob/main/server/daily-report-service.ts"
click node_cloud "https://github.com/t1mothys/orbit/blob/main/server/daily-report-cloud-store.ts"
click node_db "https://github.com/t1mothys/orbit/blob/main/server/database/connection.ts"
click node_persistence "https://github.com/t1mothys/orbit/blob/main/server/persistence.ts"
click node_ai_provider "https://github.com/t1mothys/orbit/blob/main/server/ai-provider-contract.ts"
click node_email "https://github.com/t1mothys/orbit/blob/main/server/email-service.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_auth,node_electron,node_user toneBlue
class node_ai,node_chat,node_queue,node_scheduling,node_reminders,node_caldav,node_ai_provider toneAmber
class node_notes,node_library,node_search,node_research,node_digest toneMint
class node_activity,node_daily,node_cloud,node_email toneRose
class node_server,node_db,node_persistence toneIndigo
```

## Components

### User experience

- [Web app](https://github.com/t1mothys/orbit/blob/main/src/App.tsx): `src/App.tsx`
- [Authentication](https://github.com/t1mothys/orbit/blob/main/src/hooks/useAuth.ts): `src/hooks/useAuth.ts`
- [Electron host](https://github.com/t1mothys/orbit/blob/main/electron/main.ts): `electron/main.ts`

### Conversation and planning

- [AI conversation](https://github.com/t1mothys/orbit/blob/main/server/routes/ai.ts): `server/routes/ai.ts`
- [Chat experience](https://github.com/t1mothys/orbit/blob/main/src/hooks/useOrbitChat.ts): `src/hooks/useOrbitChat.ts`
- [Conversation queue](https://github.com/t1mothys/orbit/blob/main/server/orbit-queue.ts): `server/orbit-queue.ts`
- [Schedule management](https://github.com/t1mothys/orbit/blob/main/server/schedule-store.ts): `server/schedule-store.ts`
- [Reminders](https://github.com/t1mothys/orbit/blob/main/server/reminder-store.ts): `server/reminder-store.ts`
- [CalDAV bridge](https://github.com/t1mothys/orbit/blob/main/server/caldav-service.ts): `server/caldav-service.ts`
- [AI providers](https://github.com/t1mothys/orbit/blob/main/server/ai-provider-contract.ts): `server/ai-provider-contract.ts`

### Knowledge and research

- [Notes and images](https://github.com/t1mothys/orbit/blob/main/server/note-item-service.ts): `server/note-item-service.ts`
- [Knowledge library](https://github.com/t1mothys/orbit/blob/main/server/library-service.ts): `server/library-service.ts`
- [Global search](https://github.com/t1mothys/orbit/blob/main/server/search-service.ts): `server/search-service.ts`
- [Digest research](https://github.com/t1mothys/orbit/blob/main/server/digest-research-store.ts): `server/digest-research-store.ts`
- [Digest V3](https://github.com/t1mothys/orbit/blob/main/server/digest-v3-store.ts): `server/digest-v3-store.ts`

### Reports and activity

- [Activity reports](https://github.com/t1mothys/orbit/blob/main/server/activity-store.ts): `server/activity-store.ts`
- [Daily reports](https://github.com/t1mothys/orbit/blob/main/server/daily-report-service.ts): `server/daily-report-service.ts`
- [Cloud reporting](https://github.com/t1mothys/orbit/blob/main/server/daily-report-cloud-store.ts): `server/daily-report-cloud-store.ts`
- [Email service](https://github.com/t1mothys/orbit/blob/main/server/email-service.ts): `server/email-service.ts`

### Server and persistence

- [HTTP application](https://github.com/t1mothys/orbit/blob/main/server/application.ts): `server/application.ts`
- [Application database](https://github.com/t1mothys/orbit/blob/main/server/database/connection.ts): `server/database/connection.ts`
- [Durable persistence](https://github.com/t1mothys/orbit/blob/main/server/persistence.ts): `server/persistence.ts`

### Other components

- **User**

## Connections

- User → Web app: uses (evidence: `README.md`)
- Web app → Authentication: checks session (evidence: `src/App.tsx`)
- Authentication → HTTP application: auth requests (evidence: `src/hooks/useAuth.ts`)
- Web app → HTTP application: uses API
- Electron host → Web app: hosts
- HTTP application → AI conversation: mounts routes (evidence: `server/application.ts`)
- HTTP application → Global search: mounts routes
- HTTP application → Digest research: mounts routes (evidence: `server/application.ts`)
- HTTP application → Digest V3: mounts routes (evidence: `server/application.ts`)
- Chat experience → AI conversation: sends messages
- AI conversation → Conversation queue: queues work (evidence: `server/routes/ai.ts`)
- AI conversation → AI providers: uses providers (evidence: `server/routes/ai.ts`)
- AI conversation → Schedule management: manages schedules (evidence: `server/routes/ai.ts`)
- AI conversation → Notes and images: manages notes
- AI conversation → Reminders: manages reminders (evidence: `server/routes/ai.ts`)
- Global search → Reminders: reads projections (evidence: `server/search-service.ts`)
- Global search → AI conversation: searches conversations (evidence: `server/routes/ai.ts`)
- Digest research → Activity reports: uses stores (evidence: `server/routes/research.ts`)
- Digest V3 → Activity reports: persists digest data (evidence: `server/activity-store.ts`)
- Daily reports → Activity reports: stores reports
- Daily reports → Cloud reporting: uses cloud store
- CalDAV bridge → Schedule management: reads schedules (evidence: `server/caldav-service.ts`)
- CalDAV bridge → Reminders: reads reminders (evidence: `server/caldav-service.ts`)
- Application database → Durable persistence: persists database (evidence: `server/database/connection.ts`)
- HTTP application → Application database: initializes stores
- Email service → Daily reports: delivers reports
