# karim-coder/life-os architecture

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

- Interactive diagram: https://gitdiagram.com/karim-coder/life-os
- Repository: https://github.com/karim-coder/life-os

## Overview

Life OS is a self-hosted personal productivity and knowledge-management app. Users sign in, capture or organize life items, then manage them across planning, reflection, and insight views; the API persists and aggregates this data. The README documents major capabilities beyond the sampled implementation, including focus, calendar, AI inbox processing, and backup/export. Edges are limited to documented product flows and source-index references; several UI-to-API details are not evidenced in the excerpts.

Main entry points: [`src/app/app/page.tsx`](https://github.com/karim-coder/life-os/blob/main/src/app/app/page.tsx) (Life OS app), [`src/lib/db.ts`](https://github.com/karim-coder/life-os/blob/main/src/lib/db.ts) (Prisma database), [`src/components/life-os/views/reviews-view.tsx`](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/reviews-view.tsx) (Reviews), [`src/components/life-os/quick-capture.tsx`](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/quick-capture.tsx) (Quick capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Life OS app<br/>[page.tsx]"]
  node_item_detail["Item detail"]
end

subgraph group_organizing["Life organization"]
  node_capture["Quick capture<br/>[quick-capture.tsx]"]
  node_inbox["Inbox<br/>[inbox-view.tsx]"]
  node_projects["Projects<br/>[projects-view.tsx]"]
  node_calendar["Master calendar<br/>[calendar-view.tsx]"]
  node_focus["Focus timer<br/>[focus-view.tsx]"]
  node_graph_view["Brain graph<br/>[graph-view.tsx]"]
end

subgraph group_reflection["Reflection and insight"]
  node_journal["Journal editor"]
  node_reviews["Reviews<br/>[reviews-view.tsx]"]
  node_insights["Insights dashboard<br/>[insights-view.tsx]"]
  node_sanctuary["Sanctuary<br/>[sanctuary-view.tsx]"]
end

subgraph group_services["Application services"]
  node_auth["Authentication"]
  node_items_api["Items API"]
  node_graph_api["Graph API<br/>[route.ts]"]
  node_insights_api["Insights API<br/>[route.ts]"]
  node_smart_inbox["AI inbox processing<br/>[route.ts]"]
  node_ai_provider["AI provider<br/>[ai-provider.ts]"]
  node_backup["Backup and export<br/>[route.ts]"]
end

subgraph group_persistence["Data and identity"]
  node_database[("Prisma database<br/>[db.ts]")]
  node_auth_logic["Session and TOTP<br/>[auth.ts]"]
  node_client_state["Client view state<br/>[life-os.ts]"]
end

node_person(("User"))

node_person -->|"signs in"| node_auth
node_person -->|"uses"| node_app
node_app -->|"captures items"| node_capture
node_capture -->|"processes later"| node_inbox
node_inbox -->|"requests suggestions"| node_smart_inbox
node_smart_inbox -.->|"uses provider"| node_ai_provider
node_app -->|"views items"| node_item_detail
node_app -->|"organizes projects"| node_projects
node_app -->|"plans dates"| node_calendar
node_app -->|"runs focus sessions"| node_focus
node_app -->|"explores connections"| node_graph_view
node_graph_view -.->|"loads graph data"| node_graph_api
node_graph_api -->|"reads links and items"| node_database
node_app -->|"writes journals"| node_journal
node_app -->|"reflects"| node_reviews
node_reviews -->|"reads view state"| node_client_state
node_reviews -->|"tracks progress"| node_insights
node_insights -.->|"loads summaries"| node_insights_api
node_insights_api -->|"aggregates records"| node_database
node_app -->|"visits"| node_sanctuary
node_person -->|"exports data"| node_backup
node_auth -.->|"uses session helpers"| node_auth_logic
node_auth_logic -->|"reads user data"| node_database
node_items_api -->|"reads and writes items"| node_database
node_backup -->|"reads data"| node_database

click node_app "https://github.com/karim-coder/life-os/blob/main/src/app/app/page.tsx"
click node_auth "https://github.com/karim-coder/life-os/tree/main/src/app/api/auth"
click node_item_detail "https://github.com/karim-coder/life-os/blob/main/src/components/life-os/item-detail-sheet.tsx"
click node_capture "https://github.com/karim-coder/life-os/blob/main/src/components/life-os/quick-capture.tsx"
click node_inbox "https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/inbox-view.tsx"
click node_items_api "https://github.com/karim-coder/life-os/tree/main/src/app/api/items"
click node_projects "https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/projects-view.tsx"
click node_calendar "https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/calendar-view.tsx"
click node_focus "https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/focus-view.tsx"
click node_graph_view "https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/graph-view.tsx"
click node_graph_api "https://github.com/karim-coder/life-os/blob/main/src/app/api/graph/route.ts"
click node_journal "https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/journal-editor-view.tsx"
click node_reviews "https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/reviews-view.tsx"
click node_insights "https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/insights-view.tsx"
click node_insights_api "https://github.com/karim-coder/life-os/blob/main/src/app/api/insights/route.ts"
click node_sanctuary "https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/sanctuary-view.tsx"
click node_smart_inbox "https://github.com/karim-coder/life-os/blob/main/src/app/api/ai/smart-inbox/route.ts"
click node_ai_provider "https://github.com/karim-coder/life-os/blob/main/src/lib/ai-provider.ts"
click node_backup "https://github.com/karim-coder/life-os/blob/main/src/app/api/backup/route.ts"
click node_database "https://github.com/karim-coder/life-os/blob/main/src/lib/db.ts"
click node_auth_logic "https://github.com/karim-coder/life-os/blob/main/src/lib/auth.ts"
click node_client_state "https://github.com/karim-coder/life-os/blob/main/src/store/life-os.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_app,node_item_detail,node_person toneBlue
class node_capture,node_inbox,node_projects,node_calendar,node_focus,node_graph_view toneAmber
class node_journal,node_reviews,node_insights,node_sanctuary toneMint
class node_auth,node_items_api,node_graph_api,node_insights_api,node_smart_inbox,node_ai_provider,node_backup toneRose
class node_database,node_auth_logic,node_client_state toneIndigo
```

## Components

### User experience

- [Life OS app](https://github.com/karim-coder/life-os/blob/main/src/app/app/page.tsx): `src/app/app/page.tsx`
- [Item detail](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/item-detail-sheet.tsx): `src/components/life-os/item-detail-sheet.tsx`

### Life organization

- [Quick capture](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/quick-capture.tsx): `src/components/life-os/quick-capture.tsx`
- [Inbox](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/inbox-view.tsx): `src/components/life-os/views/inbox-view.tsx`
- [Projects](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/projects-view.tsx): `src/components/life-os/views/projects-view.tsx`
- [Master calendar](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/calendar-view.tsx): `src/components/life-os/views/calendar-view.tsx`
- [Focus timer](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/focus-view.tsx): `src/components/life-os/views/focus-view.tsx`
- [Brain graph](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/graph-view.tsx): `src/components/life-os/views/graph-view.tsx`

### Reflection and insight

- [Journal editor](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/journal-editor-view.tsx): `src/components/life-os/views/journal-editor-view.tsx`
- [Reviews](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/reviews-view.tsx): `src/components/life-os/views/reviews-view.tsx`
- [Insights dashboard](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/insights-view.tsx): `src/components/life-os/views/insights-view.tsx`
- [Sanctuary](https://github.com/karim-coder/life-os/blob/main/src/components/life-os/views/sanctuary-view.tsx): `src/components/life-os/views/sanctuary-view.tsx`

### Application services

- [Authentication](https://github.com/karim-coder/life-os/tree/main/src/app/api/auth): `src/app/api/auth`
- [Items API](https://github.com/karim-coder/life-os/tree/main/src/app/api/items): `src/app/api/items`
- [Graph API](https://github.com/karim-coder/life-os/blob/main/src/app/api/graph/route.ts): `src/app/api/graph/route.ts`
- [Insights API](https://github.com/karim-coder/life-os/blob/main/src/app/api/insights/route.ts): `src/app/api/insights/route.ts`
- [AI inbox processing](https://github.com/karim-coder/life-os/blob/main/src/app/api/ai/smart-inbox/route.ts): `src/app/api/ai/smart-inbox/route.ts`
- [AI provider](https://github.com/karim-coder/life-os/blob/main/src/lib/ai-provider.ts): `src/lib/ai-provider.ts`
- [Backup and export](https://github.com/karim-coder/life-os/blob/main/src/app/api/backup/route.ts): `src/app/api/backup/route.ts`

### Data and identity

- [Prisma database](https://github.com/karim-coder/life-os/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Session and TOTP](https://github.com/karim-coder/life-os/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Client view state](https://github.com/karim-coder/life-os/blob/main/src/store/life-os.ts): `src/store/life-os.ts`

### Other components

- **User**

## Connections

- User → Authentication: signs in (evidence: `README.md`)
- User → Life OS app: uses (evidence: `README.md`)
- Life OS app → Quick capture: captures items (evidence: `README.md`)
- Quick capture → Inbox: processes later (evidence: `README.md`)
- Inbox → AI inbox processing: requests suggestions (evidence: `README.md`)
- AI inbox processing → AI provider: uses provider
- Life OS app → Item detail: views items (evidence: `README.md`)
- Life OS app → Projects: organizes projects (evidence: `README.md`)
- Life OS app → Master calendar: plans dates (evidence: `README.md`)
- Life OS app → Focus timer: runs focus sessions (evidence: `README.md`)
- Life OS app → Brain graph: explores connections (evidence: `README.md`)
- Brain graph → Graph API: loads graph data
- Graph API → Prisma database: reads links and items (evidence: `src/app/api/graph/route.ts`)
- Life OS app → Journal editor: writes journals (evidence: `README.md`)
- Life OS app → Reviews: reflects (evidence: `README.md`)
- Reviews → Client view state: reads view state (evidence: `src/components/life-os/views/reviews-view.tsx`)
- Reviews → Insights dashboard: tracks progress (evidence: `README.md`)
- Insights dashboard → Insights API: loads summaries
- Insights API → Prisma database: aggregates records (evidence: `src/app/api/insights/route.ts`)
- Life OS app → Sanctuary: visits (evidence: `README.md`)
- User → Backup and export: exports data (evidence: `README.md`)
- Authentication → Session and TOTP: uses session helpers
- Session and TOTP → Prisma database: reads user data (evidence: `src/lib/auth.ts`)
- Items API → Prisma database: reads and writes items (evidence: `src/app/api/items/route.ts`)
- Backup and export → Prisma database: reads data (evidence: `src/app/api/backup/route.ts`)
