# satya24713/second-brain architecture

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

- Interactive diagram: https://gitdiagram.com/satya24713/second-brain
- Repository: https://github.com/satya24713/second-brain

## Overview

Second Brain is a private personal planning app. Users work in the workspace to manage tasks (including tagged and dated items), journal entries, check-ins, and profile details; they can also ask Gemini for a plan and apply its proposed changes. The API layer authenticates and scopes operations, while D1 persists workspace data. The README documents the major capabilities; sampled server routes confirm the persistence and assistant flows. The workspace UI and several route implementations were not sampled, so their detailed client-side wiring is not shown.

Main entry points: [`components/workspace.tsx`](https://github.com/satya24713/second-brain/blob/main/components/workspace.tsx) (Workspace UI), [`db/index.ts`](https://github.com/satya24713/second-brain/blob/main/db/index.ts) (D1 access), [`lib/server.ts`](https://github.com/satya24713/second-brain/blob/main/lib/server.ts) (Request identity), [`app/api/assistant/route.ts`](https://github.com/satya24713/second-brain/blob/main/app/api/assistant/route.ts) (Assistant chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Workspace experience"]
  node_workspace["Workspace UI<br/>[workspace.tsx]"]
  node_task_ui["Task tools<br/>[task-editor.tsx]"]
  node_journal_ui["Journal editor<br/>[journal-editor.tsx]"]
  node_reminders["Reminders<br/>[reminders.tsx]"]
end

subgraph group_api["Application API"]
  node_workspace_api["Workspace load<br/>[route.ts]"]
  node_task_api["Task routes<br/>[route.ts]"]
  node_task_id_api["Task updates<br/>[route.ts]"]
  node_journal_api["Journal routes<br/>[route.ts]"]
  node_journal_id_api["Journal updates<br/>[route.ts]"]
  node_profile_api["Profile update<br/>[route.ts]"]
  node_tracker_api["Check-in updates<br/>[route.ts]"]
end

subgraph group_assistant["AI planning"]
  node_assistant_api["Assistant chat<br/>[route.ts]"]
  node_apply_api["Apply proposal<br/>[route.ts]"]
  node_gemini_settings["Gemini settings<br/>[route.ts]"]
  node_gemini["Gemini service<br/>[gemini.ts]"]
end

subgraph group_data["Persistent data"]
  node_db_access["D1 access<br/>[index.ts]"]
  node_schema["Data schema<br/>[schema.ts]"]
  node_d1[("D1 database")]
end

subgraph group_security["Identity and secrets"]
  node_identity["Request identity<br/>[server.ts]"]
  node_auth["Sites identity<br/>[chatgpt-auth.ts]"]
  node_key_crypto["Key encryption<br/>[keys.ts]"]
end

node_person(("Workspace user"))
node_google["Google Gemini"]

node_person -->|"uses"| node_workspace
node_workspace -->|"loads workspace"| node_workspace_api
node_workspace -->|"creates tasks"| node_task_api
node_workspace -->|"updates tasks"| node_task_id_api
node_workspace -->|"creates entries"| node_journal_api
node_workspace -->|"edits entries"| node_journal_id_api
node_workspace -->|"updates profile"| node_profile_api
node_workspace -->|"updates check-ins"| node_tracker_api
node_workspace -->|"sends prompts"| node_assistant_api
node_workspace -->|"manages key"| node_gemini_settings
node_task_ui -->|"provides task controls"| node_workspace
node_journal_ui -->|"provides journal controls"| node_workspace
node_reminders -->|"shows reminders"| node_workspace
node_workspace_api -->|"authenticates"| node_identity
node_task_api -->|"authenticates"| node_identity
node_task_id_api -->|"authenticates"| node_identity
node_journal_api -->|"authenticates"| node_identity
node_journal_id_api -->|"authenticates"| node_identity
node_profile_api -->|"authenticates"| node_identity
node_tracker_api -->|"authenticates"| node_identity
node_assistant_api -->|"authenticates"| node_identity
node_apply_api -->|"authenticates"| node_identity
node_gemini_settings -->|"authenticates"| node_identity
node_identity -->|"gets user identity"| node_auth
node_workspace_api -->|"reads workspace data"| node_db_access
node_task_api -->|"inserts tasks"| node_db_access
node_task_id_api -->|"updates or deletes tasks"| node_db_access
node_journal_api -->|"inserts entries"| node_db_access
node_journal_id_api -->|"updates or deletes entries"| node_db_access
node_profile_api -->|"updates profile"| node_db_access
node_tracker_api -->|"updates check-ins"| node_db_access
node_assistant_api -->|"generates plan"| node_gemini
node_assistant_api -->|"stores conversation"| node_db_access
node_apply_api -->|"applies proposal"| node_db_access
node_gemini_settings -->|"checks key"| node_gemini
node_gemini_settings -->|"encrypts key"| node_key_crypto
node_gemini -->|"requests generation"| node_google
node_gemini -->|"loads user context and key"| node_db_access
node_db_access -->|"queries and writes"| node_d1
node_schema -->|"defines tables"| node_d1

click node_workspace "https://github.com/satya24713/second-brain/blob/main/components/workspace.tsx"
click node_task_ui "https://github.com/satya24713/second-brain/blob/main/components/product/task-editor.tsx"
click node_journal_ui "https://github.com/satya24713/second-brain/blob/main/components/product/journal-editor.tsx"
click node_reminders "https://github.com/satya24713/second-brain/blob/main/components/product/reminders.tsx"
click node_workspace_api "https://github.com/satya24713/second-brain/blob/main/app/api/workspace/route.ts"
click node_task_api "https://github.com/satya24713/second-brain/blob/main/app/api/tasks/route.ts"
click node_task_id_api "https://github.com/satya24713/second-brain/blob/main/app/api/tasks/%5Bid%5D/route.ts"
click node_journal_api "https://github.com/satya24713/second-brain/blob/main/app/api/journal/route.ts"
click node_journal_id_api "https://github.com/satya24713/second-brain/blob/main/app/api/journal/%5Bid%5D/route.ts"
click node_profile_api "https://github.com/satya24713/second-brain/blob/main/app/api/profile/route.ts"
click node_tracker_api "https://github.com/satya24713/second-brain/blob/main/app/api/trackers/%5Bid%5D/route.ts"
click node_assistant_api "https://github.com/satya24713/second-brain/blob/main/app/api/assistant/route.ts"
click node_apply_api "https://github.com/satya24713/second-brain/blob/main/app/api/assistant/apply/route.ts"
click node_gemini_settings "https://github.com/satya24713/second-brain/blob/main/app/api/settings/gemini/route.ts"
click node_gemini "https://github.com/satya24713/second-brain/blob/main/lib/gemini.ts"
click node_identity "https://github.com/satya24713/second-brain/blob/main/lib/server.ts"
click node_auth "https://github.com/satya24713/second-brain/blob/main/app/chatgpt-auth.ts"
click node_key_crypto "https://github.com/satya24713/second-brain/blob/main/lib/keys.ts"
click node_db_access "https://github.com/satya24713/second-brain/blob/main/db/index.ts"
click node_schema "https://github.com/satya24713/second-brain/blob/main/db/schema.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_workspace,node_task_ui,node_journal_ui,node_reminders,node_person toneBlue
class node_workspace_api,node_task_api,node_task_id_api,node_journal_api,node_journal_id_api,node_profile_api,node_tracker_api toneAmber
class node_assistant_api,node_apply_api,node_gemini_settings,node_gemini toneMint
class node_db_access,node_schema,node_d1 toneRose
class node_identity,node_auth,node_key_crypto,node_google toneIndigo
```

## Components

### Workspace experience

- [Workspace UI](https://github.com/satya24713/second-brain/blob/main/components/workspace.tsx): `components/workspace.tsx`
- [Task tools](https://github.com/satya24713/second-brain/blob/main/components/product/task-editor.tsx): `components/product/task-editor.tsx`
- [Journal editor](https://github.com/satya24713/second-brain/blob/main/components/product/journal-editor.tsx): `components/product/journal-editor.tsx`
- [Reminders](https://github.com/satya24713/second-brain/blob/main/components/product/reminders.tsx): `components/product/reminders.tsx`

### Application API

- [Workspace load](https://github.com/satya24713/second-brain/blob/main/app/api/workspace/route.ts): `app/api/workspace/route.ts`
- [Task routes](https://github.com/satya24713/second-brain/blob/main/app/api/tasks/route.ts): `app/api/tasks/route.ts`
- [Task updates](https://github.com/satya24713/second-brain/blob/main/app/api/tasks/%5Bid%5D/route.ts): `app/api/tasks/[id]/route.ts`
- [Journal routes](https://github.com/satya24713/second-brain/blob/main/app/api/journal/route.ts): `app/api/journal/route.ts`
- [Journal updates](https://github.com/satya24713/second-brain/blob/main/app/api/journal/%5Bid%5D/route.ts): `app/api/journal/[id]/route.ts`
- [Profile update](https://github.com/satya24713/second-brain/blob/main/app/api/profile/route.ts): `app/api/profile/route.ts`
- [Check-in updates](https://github.com/satya24713/second-brain/blob/main/app/api/trackers/%5Bid%5D/route.ts): `app/api/trackers/[id]/route.ts`

### AI planning

- [Assistant chat](https://github.com/satya24713/second-brain/blob/main/app/api/assistant/route.ts): `app/api/assistant/route.ts`
- [Apply proposal](https://github.com/satya24713/second-brain/blob/main/app/api/assistant/apply/route.ts): `app/api/assistant/apply/route.ts`
- [Gemini settings](https://github.com/satya24713/second-brain/blob/main/app/api/settings/gemini/route.ts): `app/api/settings/gemini/route.ts`
- [Gemini service](https://github.com/satya24713/second-brain/blob/main/lib/gemini.ts): `lib/gemini.ts`

### Persistent data

- [D1 access](https://github.com/satya24713/second-brain/blob/main/db/index.ts): `db/index.ts`
- [Data schema](https://github.com/satya24713/second-brain/blob/main/db/schema.ts): `db/schema.ts`
- **D1 database**

### Identity and secrets

- [Request identity](https://github.com/satya24713/second-brain/blob/main/lib/server.ts): `lib/server.ts`
- [Sites identity](https://github.com/satya24713/second-brain/blob/main/app/chatgpt-auth.ts): `app/chatgpt-auth.ts`
- [Key encryption](https://github.com/satya24713/second-brain/blob/main/lib/keys.ts): `lib/keys.ts`

### Other components

- **Workspace user**
- **Google Gemini**

## Connections

- Workspace user → Workspace UI: uses
- Workspace UI → Workspace load: loads workspace
- Workspace UI → Task routes: creates tasks
- Workspace UI → Task updates: updates tasks
- Workspace UI → Journal routes: creates entries
- Workspace UI → Journal updates: edits entries
- Workspace UI → Profile update: updates profile
- Workspace UI → Check-in updates: updates check-ins
- Workspace UI → Assistant chat: sends prompts
- Workspace UI → Gemini settings: manages key
- Task tools → Workspace UI: provides task controls
- Journal editor → Workspace UI: provides journal controls
- Reminders → Workspace UI: shows reminders
- Workspace load → Request identity: authenticates
- Task routes → Request identity: authenticates
- Task updates → Request identity: authenticates
- Journal routes → Request identity: authenticates
- Journal updates → Request identity: authenticates
- Profile update → Request identity: authenticates
- Check-in updates → Request identity: authenticates
- Assistant chat → Request identity: authenticates
- Apply proposal → Request identity: authenticates
- Gemini settings → Request identity: authenticates
- Request identity → Sites identity: gets user identity
- Workspace load → D1 access: reads workspace data
- Task routes → D1 access: inserts tasks
- Task updates → D1 access: updates or deletes tasks
- Journal routes → D1 access: inserts entries
- Journal updates → D1 access: updates or deletes entries
- Profile update → D1 access: updates profile
- Check-in updates → D1 access: updates check-ins
- Assistant chat → Gemini service: generates plan
- Assistant chat → D1 access: stores conversation
- Apply proposal → D1 access: applies proposal
- Gemini settings → Gemini service: checks key
- Gemini settings → Key encryption: encrypts key
- Gemini service → Google Gemini: requests generation
- Gemini service → D1 access: loads user context and key
- D1 access → D1 database: queries and writes
- Data schema → D1 database: defines tables