# code-with-antonio/nightcode architecture

> Architecture diagram of the GitHub repository code-with-antonio/nightcode, 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/code-with-antonio/nightcode
- Repository: https://github.com/code-with-antonio/nightcode

## Overview

NightCode is a terminal-based AI coding agent. A user chooses or creates a session, chats in plan or build mode, and receives streamed model output; build mode can use local project tools. The CLI communicates with an authenticated Hono API, which gates new work on Polar credits, streams AI responses, and persists sessions and messages in Postgres. The graph also includes documented OAuth, model selection, and billing capabilities. Some links reflect README or SOURCE INDEX evidence rather than inspected implementation; unsampled modules are represented only at paths supported by the tree.

Main entry points: [`packages/server/src/routes/chat.ts`](https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/routes/chat.ts) (Chat streaming route), [`packages/cli/src/lib/api-client.ts`](https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/lib/api-client.ts) (API client), [`packages/cli/src/screens/session.tsx`](https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/screens/session.tsx) (Session screen), [`packages/server/src/routes/sessions.ts`](https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/routes/sessions.ts) (Session routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Terminal CLI"]
  node_cli["CLI entry and screens<br/>[index.tsx]"]
  node_session["Session screen<br/>[session.tsx]"]
  node_shell["Session shell and input<br/>[session-shell.tsx]"]
  node_messages["Chat messages<br/>[bot-message.tsx]"]
  node_chat_hook["Chat client<br/>[use-chat.ts]"]
  node_tools["Local project tools<br/>[local-tools.ts]"]
  node_oauth["CLI OAuth flow<br/>[oauth.ts]"]
  node_api_client["API client<br/>[api-client.ts]"]
  node_cli_dialogs["Model and session dialogs"]
end

subgraph group_api["API and workflow"]
  node_auth_routes["OAuth routes<br/>[auth.ts]"]
  node_session_routes["Session routes<br/>[sessions.ts]"]
  node_chat_route["Chat streaming route<br/>[chat.ts]"]
  node_auth_middleware["Authentication middleware<br/>[require-auth.ts]"]
  node_credit_gate["Credit balance gate"]
  node_billing["Billing routes<br/>[billing.ts]"]
end

subgraph group_domain["Shared AI domain"]
  node_models["Model registry<br/>[models.ts]"]
  node_prompt["System prompt<br/>[system-prompt.ts]"]
  node_credits["Usage metering<br/>[credits.ts]"]
  node_shared["Shared schemas and models<br/>[schemas.ts]"]
end

subgraph group_data["Persistence"]
  node_db_client["Prisma client<br/>[client.ts]"]
  node_postgres[("Postgres")]
end

subgraph group_services["External services"]
  node_clerk["Clerk OAuth"]
  node_polar["Polar credits"]
  node_ai["AI model providers"]
end

node_user(("User"))

node_user -->|"uses"| node_cli
node_cli -.->|"routes to"| node_session
node_session -->|"renders"| node_shell
node_session -->|"submits chat"| node_chat_hook
node_session -->|"loads session"| node_api_client
node_shell -->|"displays"| node_messages
node_chat_hook -->|"sends chat"| node_api_client
node_chat_hook -->|"executes tools"| node_tools
node_api_client -.->|"calls API"| node_auth_routes
node_api_client -.->|"calls API"| node_session_routes
node_api_client -.->|"calls API"| node_chat_route
node_oauth -->|"completes OAuth"| node_auth_routes
node_auth_routes -.->|"authenticates"| node_clerk
node_session_routes -->|"reads and writes"| node_db_client
node_chat_route -->|"persists history"| node_db_client
node_db_client -.->|"stores data"| node_postgres
node_session_routes -->|"checks credits"| node_credit_gate
node_chat_route -->|"checks credits"| node_credit_gate
node_session_routes -->|"requires auth"| node_auth_middleware
node_chat_route -->|"requires auth"| node_auth_middleware
node_auth_middleware -->|"verifies token"| node_clerk
node_credit_gate -->|"checks balance"| node_polar
node_chat_route -->|"selects model"| node_models
node_chat_route -->|"builds context"| node_prompt
node_chat_route -->|"streams response"| node_ai
node_chat_route -->|"meters usage"| node_credits
node_credits -->|"ingests usage"| node_polar
node_billing -.->|"creates checkout"| node_polar
node_cli_dialogs -->|"loads sessions"| node_api_client
node_cli_dialogs -.->|"chooses model"| node_models

click node_cli "https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/index.tsx"
click node_session "https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/screens/session.tsx"
click node_shell "https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/components/session-shell.tsx"
click node_messages "https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/components/messages/bot-message.tsx"
click node_chat_hook "https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/hooks/use-chat.ts"
click node_tools "https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/lib/local-tools.ts"
click node_oauth "https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/lib/oauth.ts"
click node_api_client "https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/lib/api-client.ts"
click node_cli_dialogs "https://github.com/code-with-antonio/nightcode/tree/main/packages/cli/src/components/dialogs"
click node_auth_routes "https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/routes/auth.ts"
click node_session_routes "https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/routes/sessions.ts"
click node_chat_route "https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/routes/chat.ts"
click node_auth_middleware "https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/middleware/require-auth.ts"
click node_credit_gate "https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/middleware/require-credits-balance.ts"
click node_billing "https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/routes/billing.ts"
click node_models "https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/lib/models.ts"
click node_prompt "https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/system-prompt.ts"
click node_credits "https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/lib/credits.ts"
click node_shared "https://github.com/code-with-antonio/nightcode/blob/main/packages/shared/src/schemas.ts"
click node_db_client "https://github.com/code-with-antonio/nightcode/blob/main/packages/database/src/client.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_cli,node_session,node_shell,node_messages,node_chat_hook,node_tools,node_oauth,node_api_client,node_cli_dialogs,node_user toneBlue
class node_auth_routes,node_session_routes,node_chat_route,node_auth_middleware,node_credit_gate,node_billing toneAmber
class node_models,node_prompt,node_credits,node_shared toneMint
class node_db_client,node_postgres toneRose
class node_clerk,node_polar,node_ai toneIndigo
```

## Components

### Terminal CLI

- [CLI entry and screens](https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/index.tsx): `packages/cli/src/index.tsx`
- [Session screen](https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/screens/session.tsx): `packages/cli/src/screens/session.tsx`
- [Session shell and input](https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/components/session-shell.tsx): `packages/cli/src/components/session-shell.tsx`
- [Chat messages](https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/components/messages/bot-message.tsx): `packages/cli/src/components/messages/bot-message.tsx`
- [Chat client](https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/hooks/use-chat.ts): `packages/cli/src/hooks/use-chat.ts`
- [Local project tools](https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/lib/local-tools.ts): `packages/cli/src/lib/local-tools.ts`
- [CLI OAuth flow](https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/lib/oauth.ts): `packages/cli/src/lib/oauth.ts`
- [API client](https://github.com/code-with-antonio/nightcode/blob/main/packages/cli/src/lib/api-client.ts): `packages/cli/src/lib/api-client.ts`
- [Model and session dialogs](https://github.com/code-with-antonio/nightcode/tree/main/packages/cli/src/components/dialogs): `packages/cli/src/components/dialogs`

### API and workflow

- [OAuth routes](https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/routes/auth.ts): `packages/server/src/routes/auth.ts`
- [Session routes](https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/routes/sessions.ts): `packages/server/src/routes/sessions.ts`
- [Chat streaming route](https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/routes/chat.ts): `packages/server/src/routes/chat.ts`
- [Authentication middleware](https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/middleware/require-auth.ts): `packages/server/src/middleware/require-auth.ts`
- [Credit balance gate](https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/middleware/require-credits-balance.ts): `packages/server/src/middleware/require-credits-balance.ts`
- [Billing routes](https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/routes/billing.ts): `packages/server/src/routes/billing.ts`

### Shared AI domain

- [Model registry](https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/lib/models.ts): `packages/server/src/lib/models.ts`
- [System prompt](https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/system-prompt.ts): `packages/server/src/system-prompt.ts`
- [Usage metering](https://github.com/code-with-antonio/nightcode/blob/main/packages/server/src/lib/credits.ts): `packages/server/src/lib/credits.ts`
- [Shared schemas and models](https://github.com/code-with-antonio/nightcode/blob/main/packages/shared/src/schemas.ts): `packages/shared/src/schemas.ts`

### Persistence

- [Prisma client](https://github.com/code-with-antonio/nightcode/blob/main/packages/database/src/client.ts): `packages/database/src/client.ts`
- **Postgres**

### External services

- **Clerk OAuth**
- **Polar credits**
- **AI model providers**

### Other components

- **User**

## Connections

- User → CLI entry and screens: uses (evidence: `README.md`)
- CLI entry and screens → Session screen: routes to
- Session screen → Session shell and input: renders (evidence: `packages/cli/src/screens/session.tsx`)
- Session screen → Chat client: submits chat (evidence: `packages/cli/src/screens/session.tsx`)
- Session screen → API client: loads session (evidence: `packages/cli/src/screens/session.tsx`)
- Session shell and input → Chat messages: displays (evidence: `packages/cli/src/components/session-shell.tsx`)
- Chat client → API client: sends chat (evidence: `packages/cli/src/hooks/use-chat.ts`)
- Chat client → Local project tools: executes tools (evidence: `packages/cli/src/hooks/use-chat.ts`)
- API client → OAuth routes: calls API
- API client → Session routes: calls API
- API client → Chat streaming route: calls API
- CLI OAuth flow → OAuth routes: completes OAuth (evidence: `README.md`)
- OAuth routes → Clerk OAuth: authenticates (evidence: `README.md`)
- Session routes → Prisma client: reads and writes (evidence: `packages/server/src/routes/sessions.ts`)
- Chat streaming route → Prisma client: persists history (evidence: `packages/server/src/routes/chat.ts`)
- Prisma client → Postgres: stores data (evidence: `README.md`)
- Session routes → Credit balance gate: checks credits (evidence: `packages/server/src/routes/sessions.ts`)
- Chat streaming route → Credit balance gate: checks credits (evidence: `packages/server/src/routes/chat.ts`)
- Session routes → Authentication middleware: requires auth (evidence: `packages/server/src/routes/sessions.ts`)
- Chat streaming route → Authentication middleware: requires auth (evidence: `packages/server/src/routes/chat.ts`)
- Authentication middleware → Clerk OAuth: verifies token (evidence: `packages/server/src/middleware/require-auth.ts`)
- Credit balance gate → Polar credits: checks balance (evidence: `packages/server/src/middleware/require-credits-balance.ts`)
- Chat streaming route → Model registry: selects model (evidence: `packages/server/src/routes/chat.ts`)
- Chat streaming route → System prompt: builds context (evidence: `packages/server/src/routes/chat.ts`)
- Chat streaming route → AI model providers: streams response (evidence: `README.md`)
- Chat streaming route → Usage metering: meters usage (evidence: `packages/server/src/routes/chat.ts`)
- Usage metering → Polar credits: ingests usage (evidence: `README.md`)
- Billing routes → Polar credits: creates checkout (evidence: `README.md`)
- Model and session dialogs → API client: loads sessions (evidence: `packages/cli/src/components/dialogs/sessions-dialog.tsx`)
- Model and session dialogs → Model registry: chooses model (evidence: `README.md`)
