# frezanz/kchat architecture

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

- Interactive diagram: https://gitdiagram.com/frezanz/kchat
- Repository: https://github.com/frezanz/kchat

## Overview

KChat is a browser-first AI chat workspace: users configure a model and prompt, manage local conversations, and send chat requests directly to their chosen API. The workspace also exposes tool integrations, custom API connections, and a sandboxed coding/browser runtime; account routes support workspace syncing. The README documents streaming chat and presentation controls, while the sampled page excerpt confirms conversation state, settings, and runtime requests. Some UI-to-route wiring and unsampled subsystems are inferred only from documented capabilities and the file tree.

Main entry points: [`app/page.tsx`](https://github.com/frezanz/kchat/blob/main/app/page.tsx) (Chat interface), [`app/api/runtime/route.ts`](https://github.com/frezanz/kchat/blob/main/app/api/runtime/route.ts) (Runtime actions), [`app/api/auth`](https://github.com/frezanz/kchat/tree/main/app/api/auth) (Auth endpoints), [`app/api/tools/execute/route.ts`](https://github.com/frezanz/kchat/blob/main/app/api/tools/execute/route.ts) (Tool execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Chat workspace"]
  node_client["Chat interface<br/>[page.tsx]"]
end

subgraph group_identity["Accounts"]
  node_auth_ui["Sign-in UI<br/>[AuthScreen.tsx]"]
  node_auth_routes["Auth endpoints"]
  node_auth_logic["Session and passwords<br/>[auth.ts]"]
end

subgraph group_integrations["Tools and connections"]
  node_tool_catalog["Tool catalog endpoint<br/>[route.ts]"]
  node_tool_registry["Tool definitions<br/>[tool-registry.ts]"]
  node_tool_exec["Tool execution<br/>[route.ts]"]
  node_custom_api["Custom API connector<br/>[route.ts]"]
end

subgraph group_runtime["Sandbox runtime"]
  node_runtime_api["Runtime actions<br/>[route.ts]"]
  node_runtime_db[("Sandbox ownership records<br/>[db.ts]")]
end

node_person(("Workspace user"))
node_db[("Postgres<br/>[db.ts]")]
node_local_state[("Browser session storage")]
node_model_api{{"Configured model API"}}
node_github{{"GitHub API"}}
node_netlify{{"Netlify API"}}
node_sandbox{{"E2B sandbox"}}
node_browser_agent["Playwright browser CLI"]

node_person -->|"uses"| node_client
node_client -->|"stores chats and key"| node_local_state
node_client -->|"sends chat requests"| node_model_api
node_client -->|"opens sign-in"| node_auth_ui
node_auth_ui -->|"submits credentials"| node_auth_routes
node_client -->|"checks and ends session"| node_auth_routes
node_auth_routes -->|"uses session helpers"| node_auth_logic
node_auth_routes -->|"reads and writes accounts"| node_db
node_auth_logic -->|"reads and writes sessions"| node_db
node_client -->|"requests tools"| node_tool_catalog
node_tool_catalog -->|"returns definitions"| node_tool_registry
node_client -->|"submits tool calls"| node_tool_exec
node_tool_exec -.->|"calls GitHub"| node_github
node_tool_exec -.->|"calls Netlify"| node_netlify
node_client -->|"sends connection requests"| node_custom_api
node_client -->|"requests sandbox actions"| node_runtime_api
node_runtime_api -->|"checks user"| node_auth_logic
node_runtime_api -->|"checks sandbox ownership"| node_runtime_db
node_runtime_api -.->|"creates or connects; runs commands"| node_sandbox
node_runtime_api -.->|"dispatches browser commands"| node_browser_agent
node_browser_agent -.->|"runs inside sandbox"| node_sandbox

click node_client "https://github.com/frezanz/kchat/blob/main/app/page.tsx"
click node_auth_ui "https://github.com/frezanz/kchat/blob/main/app/components/AuthScreen.tsx"
click node_auth_routes "https://github.com/frezanz/kchat/tree/main/app/api/auth"
click node_auth_logic "https://github.com/frezanz/kchat/blob/main/lib/auth.ts"
click node_db "https://github.com/frezanz/kchat/blob/main/lib/db.ts"
click node_tool_catalog "https://github.com/frezanz/kchat/blob/main/app/api/tools/catalog/route.ts"
click node_tool_registry "https://github.com/frezanz/kchat/blob/main/lib/tool-registry.ts"
click node_tool_exec "https://github.com/frezanz/kchat/blob/main/app/api/tools/execute/route.ts"
click node_custom_api "https://github.com/frezanz/kchat/blob/main/app/api/connectors/api/route.ts"
click node_runtime_api "https://github.com/frezanz/kchat/blob/main/app/api/runtime/route.ts"
click node_runtime_db "https://github.com/frezanz/kchat/blob/main/lib/db.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_client,node_person,node_browser_agent toneBlue
class node_auth_ui,node_auth_routes,node_auth_logic,node_db,node_local_state toneAmber
class node_tool_catalog,node_tool_registry,node_tool_exec,node_custom_api,node_model_api,node_github,node_netlify toneMint
class node_runtime_api,node_runtime_db toneRose
class node_sandbox toneIndigo
```

## Components

### Chat workspace

- [Chat interface](https://github.com/frezanz/kchat/blob/main/app/page.tsx): `app/page.tsx`

### Accounts

- [Sign-in UI](https://github.com/frezanz/kchat/blob/main/app/components/AuthScreen.tsx): `app/components/AuthScreen.tsx`
- [Auth endpoints](https://github.com/frezanz/kchat/tree/main/app/api/auth): `app/api/auth`
- [Session and passwords](https://github.com/frezanz/kchat/blob/main/lib/auth.ts): `lib/auth.ts`

### Tools and connections

- [Tool catalog endpoint](https://github.com/frezanz/kchat/blob/main/app/api/tools/catalog/route.ts): `app/api/tools/catalog/route.ts`
- [Tool definitions](https://github.com/frezanz/kchat/blob/main/lib/tool-registry.ts): `lib/tool-registry.ts`
- [Tool execution](https://github.com/frezanz/kchat/blob/main/app/api/tools/execute/route.ts): `app/api/tools/execute/route.ts`
- [Custom API connector](https://github.com/frezanz/kchat/blob/main/app/api/connectors/api/route.ts): `app/api/connectors/api/route.ts`

### Sandbox runtime

- [Runtime actions](https://github.com/frezanz/kchat/blob/main/app/api/runtime/route.ts): `app/api/runtime/route.ts`
- [Sandbox ownership records](https://github.com/frezanz/kchat/blob/main/lib/db.ts): `lib/db.ts`

### Other components

- **Workspace user**
- [Postgres](https://github.com/frezanz/kchat/blob/main/lib/db.ts): `lib/db.ts`
- **Browser session storage**
- **Configured model API**
- **GitHub API**
- **Netlify API**
- **E2B sandbox**
- **Playwright browser CLI**

## Connections

- Workspace user → Chat interface: uses
- Chat interface → Browser session storage: stores chats and key
- Chat interface → Configured model API: sends chat requests
- Chat interface → Sign-in UI: opens sign-in
- Sign-in UI → Auth endpoints: submits credentials
- Chat interface → Auth endpoints: checks and ends session
- Auth endpoints → Session and passwords: uses session helpers
- Auth endpoints → Postgres: reads and writes accounts
- Session and passwords → Postgres: reads and writes sessions
- Chat interface → Tool catalog endpoint: requests tools
- Tool catalog endpoint → Tool definitions: returns definitions
- Chat interface → Tool execution: submits tool calls
- Tool execution → GitHub API: calls GitHub
- Tool execution → Netlify API: calls Netlify
- Chat interface → Custom API connector: sends connection requests
- Chat interface → Runtime actions: requests sandbox actions
- Runtime actions → Session and passwords: checks user
- Runtime actions → Sandbox ownership records: checks sandbox ownership
- Runtime actions → E2B sandbox: creates or connects; runs commands
- Runtime actions → Playwright browser CLI: dispatches browser commands
- Playwright browser CLI → E2B sandbox: runs inside sandbox