# lucifer-kj/personal-os-edge architecture

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

- Interactive diagram: https://gitdiagram.com/lucifer-kj/personal-os-edge
- Repository: https://github.com/lucifer-kj/personal-os-edge

## Overview

Personal OS Edge is a Cloudflare Workers API for lead management, voice capture, MCP tools, and n8n automation. Clients enter through the Hono worker/router; authenticated requests pass through token authorization before domain handlers process them. Leads are validated, scored, deduplicated and stored; voice is transcribed, recorded in the inbox and optionally forwarded; MCP exposes CRM and Personal OS tools; n8n dispatch triggers workflows. The handlers use a shared Supabase REST/RPC client. README capabilities not visible in sampled handlers are retained where documented; no implementation detail is inferred for them.

Main entry points: [`src/lib/supabase.ts`](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/lib/supabase.ts) (Supabase REST client), [`src/index.ts`](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/index.ts) (Hono worker), [`src/routes/voice.ts`](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/voice.ts) (Voice transcription), [`src/lib/auth.ts`](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/lib/auth.ts) (Token middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Worker entry"]
  node_worker["Hono worker<br/>[index.ts]"]
  node_health["Health probe<br/>[health.ts]"]
end

subgraph group_security["Authorization"]
  node_auth["Token middleware<br/>[auth.ts]"]
end

subgraph group_leads["Lead management"]
  node_lead_api["Lead API<br/>[leads.ts]"]
  node_lead_webhook["Lead ingestion<br/>[leads.ts]"]
end

subgraph group_voice["Voice capture"]
  node_voice_api["Voice transcription<br/>[voice.ts]"]
  node_whisper["Workers AI Whisper"]
  node_inbox[("Voice inbox items")]
end

subgraph group_agents["Agent integrations"]
  node_mcp["MCP server<br/>[mcp.ts]"]
  node_n8n_api["Workflow dispatch<br/>[n8n.ts]"]
end

subgraph group_data["Persistence"]
  node_supabase_client["Supabase REST client<br/>[supabase.ts]"]
  node_supabase[("Supabase data")]
end

node_clients(("API clients"))
node_n8n(("n8n agents"))
node_lead_sources(("Lead sources"))

node_clients -->|"send requests"| node_worker
node_worker -->|"routes to"| node_health
node_worker -->|"routes to"| node_lead_api
node_worker -->|"routes to"| node_lead_webhook
node_worker -->|"routes to"| node_voice_api
node_worker -->|"routes to"| node_mcp
node_worker -->|"routes to"| node_n8n_api
node_lead_api -->|"checks scope"| node_auth
node_voice_api -->|"checks scope"| node_auth
node_mcp -->|"checks scope"| node_auth
node_n8n_api -->|"checks scope"| node_auth
node_health -->|"queries status"| node_supabase_client
node_auth -->|"resolves tokens"| node_supabase_client
node_lead_api -->|"reads and converts"| node_supabase_client
node_lead_webhook -->|"deduplicates and stores"| node_supabase_client
node_mcp -->|"executes tools"| node_supabase_client
node_supabase_client -->|"REST and RPC"| node_supabase
node_voice_api -->|"transcribes audio"| node_whisper
node_voice_api -->|"records transcript"| node_supabase_client
node_supabase_client -->|"stores memo"| node_inbox
node_lead_sources -->|"submit leads"| node_lead_webhook
node_n8n -->|"uses MCP tools"| node_mcp
node_voice_api -->|"forwards transcript"| node_n8n
node_lead_webhook -->|"notifies ingestion"| node_n8n
node_n8n_api -->|"dispatches workflow"| node_n8n

click node_worker "https://github.com/lucifer-kj/personal-os-edge/blob/main/src/index.ts"
click node_health "https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/health.ts"
click node_auth "https://github.com/lucifer-kj/personal-os-edge/blob/main/src/lib/auth.ts"
click node_lead_api "https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/leads.ts"
click node_lead_webhook "https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/leads.ts"
click node_voice_api "https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/voice.ts"
click node_mcp "https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/mcp.ts"
click node_n8n_api "https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/n8n.ts"
click node_supabase_client "https://github.com/lucifer-kj/personal-os-edge/blob/main/src/lib/supabase.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_worker,node_health,node_clients toneBlue
class node_auth toneAmber
class node_lead_api,node_lead_webhook toneMint
class node_voice_api,node_whisper,node_inbox toneRose
class node_mcp,node_n8n_api,node_n8n,node_lead_sources toneIndigo
class node_supabase_client,node_supabase toneTeal
```

## Components

### Worker entry

- [Hono worker](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/index.ts): `src/index.ts`
- [Health probe](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/health.ts): `src/routes/health.ts`

### Authorization

- [Token middleware](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/lib/auth.ts): `src/lib/auth.ts`

### Lead management

- [Lead API](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/leads.ts): `src/routes/leads.ts`
- [Lead ingestion](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/leads.ts): `src/routes/leads.ts`

### Voice capture

- [Voice transcription](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/voice.ts): `src/routes/voice.ts`
- **Workers AI Whisper**
- **Voice inbox items**

### Agent integrations

- [MCP server](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/mcp.ts): `src/routes/mcp.ts`
- [Workflow dispatch](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/routes/n8n.ts): `src/routes/n8n.ts`

### Persistence

- [Supabase REST client](https://github.com/lucifer-kj/personal-os-edge/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`
- **Supabase data**

### Other components

- **API clients**
- **n8n agents**
- **Lead sources**

## Connections

- API clients → Hono worker: send requests (evidence: `src/index.ts`)
- Hono worker → Health probe: routes to (evidence: `src/index.ts`)
- Hono worker → Lead API: routes to (evidence: `src/index.ts`)
- Hono worker → Lead ingestion: routes to (evidence: `src/index.ts`)
- Hono worker → Voice transcription: routes to (evidence: `src/index.ts`)
- Hono worker → MCP server: routes to (evidence: `src/index.ts`)
- Hono worker → Workflow dispatch: routes to (evidence: `src/index.ts`)
- Lead API → Token middleware: checks scope (evidence: `src/routes/leads.ts`)
- Voice transcription → Token middleware: checks scope (evidence: `src/routes/voice.ts`)
- MCP server → Token middleware: checks scope (evidence: `src/routes/mcp.ts`)
- Workflow dispatch → Token middleware: checks scope (evidence: `src/routes/n8n.ts`)
- Health probe → Supabase REST client: queries status (evidence: `src/routes/health.ts`)
- Token middleware → Supabase REST client: resolves tokens (evidence: `src/lib/auth.ts`)
- Lead API → Supabase REST client: reads and converts (evidence: `src/routes/leads.ts`)
- Lead ingestion → Supabase REST client: deduplicates and stores (evidence: `src/routes/leads.ts`)
- MCP server → Supabase REST client: executes tools (evidence: `src/routes/mcp.ts`)
- Supabase REST client → Supabase data: REST and RPC (evidence: `src/lib/supabase.ts`)
- Voice transcription → Workers AI Whisper: transcribes audio (evidence: `src/routes/voice.ts`)
- Voice transcription → Supabase REST client: records transcript (evidence: `src/routes/voice.ts`)
- Supabase REST client → Voice inbox items: stores memo
- Lead sources → Lead ingestion: submit leads (evidence: `README.md`)
- n8n agents → MCP server: uses MCP tools (evidence: `README.md`)
- Voice transcription → n8n agents: forwards transcript (evidence: `src/routes/voice.ts`)
- Lead ingestion → n8n agents: notifies ingestion (evidence: `src/routes/leads.ts`)
- Workflow dispatch → n8n agents: dispatches workflow (evidence: `src/routes/n8n.ts`)
