# vikassri/lifeos architecture

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

- Interactive diagram: https://gitdiagram.com/vikassri/lifeos
- Repository: https://github.com/vikassri/lifeos

## Overview

lifeOS is a private, single-user personal management application. The main workflow is sign-in to the protected vault, where users manage personal records—projects, documents, notes, journal entries, links, investments, and liabilities—and can use AI agents and chat. Server actions and API routes mediate feature operations; SQLite stores application data, with session, CSRF, and API-guard controls protecting access. The README describes local encryption and encrypted cookies. Some feature and integration relationships are supported by the source index rather than full excerpts, so unsampled internals are represented conservatively.

Main entry points: [`app/api/auth/login/route.ts`](https://github.com/vikassri/lifeos/blob/main/app/api/auth/login/route.ts) (Login endpoint), [`lib/db/client.ts`](https://github.com/vikassri/lifeos/blob/main/lib/db/client.ts) (SQLite database), [`lib/middleware/api-guard.ts`](https://github.com/vikassri/lifeos/blob/main/lib/middleware/api-guard.ts) (API guard), [`app/(vault)/dashboard/page.tsx`](https://github.com/vikassri/lifeos/blob/main/app/(vault)/dashboard/page.tsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and security"]
  node_login["Login page<br/>[page.tsx]"]
  node_login_api["Login endpoint<br/>[route.ts]"]
  node_session["Session management<br/>[session.ts]"]
  node_local_auth["Local authentication<br/>[local-auth.ts]"]
  node_api_guard["API guard<br/>[api-guard.ts]"]
  node_csrf["CSRF protection<br/>[csrf.ts]"]
end

subgraph group_personal["Personal workspace"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_notes["Notes<br/>[NotesClient.tsx]"]
  node_journal["Journal<br/>[JournalClient.tsx]"]
  node_links["Personal links<br/>[LinksClient.tsx]"]
  node_markdown["Markdown editor<br/>[MarkdownEditor.tsx]"]
end

subgraph group_finance["Finance tracking"]
  node_investments["Investments"]
  node_net_worth["Net worth<br/>[NetWorthClient.tsx]"]
  node_finance_actions["Finance actions<br/>[actions.ts]"]
end

subgraph group_projects["Projects and files"]
  node_documents["Documents"]
  node_projects_ui["Project workspace<br/>[ProjectsClient.tsx]"]
  node_project_files["Project file storage<br/>[project-files.ts]"]
  node_google_drive["Google Drive integration<br/>[google-drive.ts]"]
end

subgraph group_intelligence["AI assistance"]
  node_agents_ui["Agent workspace<br/>[AgentsClient.tsx]"]
  node_agent_api["Agent API<br/>[route.ts]"]
  node_agent_logic["Agent logic<br/>[agents.ts]"]
  node_chat_ui["Chat interface<br/>[ChatWindow.tsx]"]
  node_chat_api["Chat API<br/>[route.ts]"]
  node_chat_logic["Chat service<br/>[chat.ts]"]
end

subgraph group_platform["Storage and platform"]
  node_database[("SQLite database<br/>[client.ts]")]
  node_vault_crypto["Vault encryption<br/>[vault.ts]"]
  node_audit["Audit logging<br/>[log.ts]"]
end

node_user(("Single user"))

node_user -->|"signs in"| node_login
node_login -->|"submits credentials"| node_login_api
node_login_api -->|"verifies credentials"| node_local_auth
node_login_api -->|"creates session"| node_session
node_login_api -->|"upserts user"| node_database
node_login_api -->|"records sign-in"| node_audit
node_login_api -->|"generates token"| node_csrf
node_user -->|"opens vault"| node_dashboard
node_dashboard -->|"checks session"| node_session
node_dashboard -->|"reads dashboard data"| node_database
node_notes -->|"edits text"| node_markdown
node_journal -->|"edits entries"| node_markdown
node_documents -.->|"uploads files"| node_google_drive
node_documents -.->|"manages document records"| node_database
node_projects_ui -.->|"manages project files"| node_project_files
node_projects_ui -.->|"saves projects"| node_database
node_investments -->|"records snapshots"| node_finance_actions
node_net_worth -->|"loads net worth data"| node_database
node_agents_ui -.->|"uses agent API"| node_agent_api
node_agent_api -->|"guards requests"| node_api_guard
node_agent_api -->|"dispatches agent operations"| node_agent_logic
node_agent_logic -->|"reads agent data"| node_database
node_chat_ui -.->|"sends messages"| node_chat_api
node_chat_api -->|"guards requests"| node_api_guard
node_chat_api -->|"dispatches chat"| node_chat_logic
node_api_guard -->|"validates session"| node_session
node_api_guard -->|"checks tokens"| node_csrf
node_api_guard -->|"logs access blocks"| node_audit
node_vault_crypto -.->|"protects vault data"| node_user

click node_login "https://github.com/vikassri/lifeos/blob/main/app/(auth)/login/page.tsx"
click node_login_api "https://github.com/vikassri/lifeos/blob/main/app/api/auth/login/route.ts"
click node_session "https://github.com/vikassri/lifeos/blob/main/lib/auth/session.ts"
click node_local_auth "https://github.com/vikassri/lifeos/blob/main/lib/auth/local-auth.ts"
click node_api_guard "https://github.com/vikassri/lifeos/blob/main/lib/middleware/api-guard.ts"
click node_csrf "https://github.com/vikassri/lifeos/blob/main/lib/security/csrf.ts"
click node_dashboard "https://github.com/vikassri/lifeos/blob/main/app/(vault)/dashboard/page.tsx"
click node_notes "https://github.com/vikassri/lifeos/blob/main/components/notes/NotesClient.tsx"
click node_journal "https://github.com/vikassri/lifeos/blob/main/components/journal/JournalClient.tsx"
click node_links "https://github.com/vikassri/lifeos/blob/main/components/links/LinksClient.tsx"
click node_markdown "https://github.com/vikassri/lifeos/blob/main/components/markdown/MarkdownEditor.tsx"
click node_documents "https://github.com/vikassri/lifeos/blob/main/components/documents/DocumentsClient.tsx"
click node_projects_ui "https://github.com/vikassri/lifeos/blob/main/components/projects/ProjectsClient.tsx"
click node_project_files "https://github.com/vikassri/lifeos/blob/main/lib/storage/project-files.ts"
click node_investments "https://github.com/vikassri/lifeos/blob/main/components/investments/InvestmentsClient.tsx"
click node_net_worth "https://github.com/vikassri/lifeos/blob/main/components/net-worth/NetWorthClient.tsx"
click node_finance_actions "https://github.com/vikassri/lifeos/blob/main/app/(vault)/vault/finance/actions.ts"
click node_agents_ui "https://github.com/vikassri/lifeos/blob/main/components/agents/AgentsClient.tsx"
click node_agent_api "https://github.com/vikassri/lifeos/blob/main/app/api/v1/agents/route.ts"
click node_agent_logic "https://github.com/vikassri/lifeos/blob/main/lib/ai/agents.ts"
click node_chat_ui "https://github.com/vikassri/lifeos/blob/main/components/chat/ChatWindow.tsx"
click node_chat_api "https://github.com/vikassri/lifeos/blob/main/app/api/v1/chat/route.ts"
click node_chat_logic "https://github.com/vikassri/lifeos/blob/main/lib/ai/chat.ts"
click node_google_drive "https://github.com/vikassri/lifeos/blob/main/lib/storage/google-drive.ts"
click node_database "https://github.com/vikassri/lifeos/blob/main/lib/db/client.ts"
click node_vault_crypto "https://github.com/vikassri/lifeos/blob/main/lib/crypto/vault.ts"
click node_audit "https://github.com/vikassri/lifeos/blob/main/lib/audit/log.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_login,node_login_api,node_session,node_local_auth,node_api_guard,node_csrf,node_user toneBlue
class node_dashboard,node_notes,node_journal,node_links,node_markdown toneAmber
class node_investments,node_net_worth,node_finance_actions toneMint
class node_documents,node_projects_ui,node_project_files,node_google_drive toneRose
class node_agents_ui,node_agent_api,node_agent_logic,node_chat_ui,node_chat_api,node_chat_logic toneIndigo
class node_database,node_vault_crypto,node_audit toneTeal
```

## Components

### Access and security

- [Login page](https://github.com/vikassri/lifeos/blob/main/app/(auth)/login/page.tsx): `app/(auth)/login/page.tsx`
- [Login endpoint](https://github.com/vikassri/lifeos/blob/main/app/api/auth/login/route.ts): `app/api/auth/login/route.ts`
- [Session management](https://github.com/vikassri/lifeos/blob/main/lib/auth/session.ts): `lib/auth/session.ts`
- [Local authentication](https://github.com/vikassri/lifeos/blob/main/lib/auth/local-auth.ts): `lib/auth/local-auth.ts`
- [API guard](https://github.com/vikassri/lifeos/blob/main/lib/middleware/api-guard.ts): `lib/middleware/api-guard.ts`
- [CSRF protection](https://github.com/vikassri/lifeos/blob/main/lib/security/csrf.ts): `lib/security/csrf.ts`

### Personal workspace

- [Dashboard](https://github.com/vikassri/lifeos/blob/main/app/(vault)/dashboard/page.tsx): `app/(vault)/dashboard/page.tsx`
- [Notes](https://github.com/vikassri/lifeos/blob/main/components/notes/NotesClient.tsx): `components/notes/NotesClient.tsx`
- [Journal](https://github.com/vikassri/lifeos/blob/main/components/journal/JournalClient.tsx): `components/journal/JournalClient.tsx`
- [Personal links](https://github.com/vikassri/lifeos/blob/main/components/links/LinksClient.tsx): `components/links/LinksClient.tsx`
- [Markdown editor](https://github.com/vikassri/lifeos/blob/main/components/markdown/MarkdownEditor.tsx): `components/markdown/MarkdownEditor.tsx`

### Finance tracking

- [Investments](https://github.com/vikassri/lifeos/blob/main/components/investments/InvestmentsClient.tsx): `components/investments/InvestmentsClient.tsx`
- [Net worth](https://github.com/vikassri/lifeos/blob/main/components/net-worth/NetWorthClient.tsx): `components/net-worth/NetWorthClient.tsx`
- [Finance actions](https://github.com/vikassri/lifeos/blob/main/app/(vault)/vault/finance/actions.ts): `app/(vault)/vault/finance/actions.ts`

### Projects and files

- [Documents](https://github.com/vikassri/lifeos/blob/main/components/documents/DocumentsClient.tsx): `components/documents/DocumentsClient.tsx`
- [Project workspace](https://github.com/vikassri/lifeos/blob/main/components/projects/ProjectsClient.tsx): `components/projects/ProjectsClient.tsx`
- [Project file storage](https://github.com/vikassri/lifeos/blob/main/lib/storage/project-files.ts): `lib/storage/project-files.ts`
- [Google Drive integration](https://github.com/vikassri/lifeos/blob/main/lib/storage/google-drive.ts): `lib/storage/google-drive.ts`

### AI assistance

- [Agent workspace](https://github.com/vikassri/lifeos/blob/main/components/agents/AgentsClient.tsx): `components/agents/AgentsClient.tsx`
- [Agent API](https://github.com/vikassri/lifeos/blob/main/app/api/v1/agents/route.ts): `app/api/v1/agents/route.ts`
- [Agent logic](https://github.com/vikassri/lifeos/blob/main/lib/ai/agents.ts): `lib/ai/agents.ts`
- [Chat interface](https://github.com/vikassri/lifeos/blob/main/components/chat/ChatWindow.tsx): `components/chat/ChatWindow.tsx`
- [Chat API](https://github.com/vikassri/lifeos/blob/main/app/api/v1/chat/route.ts): `app/api/v1/chat/route.ts`
- [Chat service](https://github.com/vikassri/lifeos/blob/main/lib/ai/chat.ts): `lib/ai/chat.ts`

### Storage and platform

- [SQLite database](https://github.com/vikassri/lifeos/blob/main/lib/db/client.ts): `lib/db/client.ts`
- [Vault encryption](https://github.com/vikassri/lifeos/blob/main/lib/crypto/vault.ts): `lib/crypto/vault.ts`
- [Audit logging](https://github.com/vikassri/lifeos/blob/main/lib/audit/log.ts): `lib/audit/log.ts`

### Other components

- **Single user**

## Connections

- Single user → Login page: signs in (evidence: `README.md`)
- Login page → Login endpoint: submits credentials (evidence: `app/api/auth/login/route.ts`)
- Login endpoint → Local authentication: verifies credentials (evidence: `app/api/auth/login/route.ts`)
- Login endpoint → Session management: creates session (evidence: `app/api/auth/login/route.ts`)
- Login endpoint → SQLite database: upserts user (evidence: `app/api/auth/login/route.ts`)
- Login endpoint → Audit logging: records sign-in (evidence: `app/api/auth/login/route.ts`)
- Login endpoint → CSRF protection: generates token (evidence: `app/api/auth/login/route.ts`)
- Single user → Dashboard: opens vault (evidence: `README.md`)
- Dashboard → Session management: checks session (evidence: `app/(vault)/dashboard/page.tsx`)
- Dashboard → SQLite database: reads dashboard data (evidence: `app/(vault)/dashboard/page.tsx`)
- Notes → Markdown editor: edits text (evidence: `components/notes/NotesClient.tsx`)
- Journal → Markdown editor: edits entries (evidence: `components/journal/JournalClient.tsx`)
- Documents → Google Drive integration: uploads files
- Documents → SQLite database: manages document records
- Project workspace → Project file storage: manages project files
- Project workspace → SQLite database: saves projects
- Investments → Finance actions: records snapshots (evidence: `components/investments/InvestmentsClient.tsx`)
- Net worth → SQLite database: loads net worth data (evidence: `app/(vault)/net-worth/page.tsx`)
- Agent workspace → Agent API: uses agent API
- Agent API → API guard: guards requests (evidence: `app/api/v1/agents/route.ts`)
- Agent API → Agent logic: dispatches agent operations (evidence: `app/api/v1/agents/route.ts`)
- Agent logic → SQLite database: reads agent data (evidence: `lib/ai/agents.ts`)
- Chat interface → Chat API: sends messages
- Chat API → API guard: guards requests (evidence: `app/api/v1/chat/route.ts`)
- Chat API → Chat service: dispatches chat (evidence: `app/api/v1/chat/route.ts`)
- API guard → Session management: validates session (evidence: `lib/middleware/api-guard.ts`)
- API guard → CSRF protection: checks tokens (evidence: `lib/middleware/api-guard.ts`)
- API guard → Audit logging: logs access blocks (evidence: `lib/middleware/api-guard.ts`)
- Vault encryption → Single user: protects vault data
