# 3lmglow/phosphene architecture

> Architecture diagram of the GitHub repository 3lmglow/phosphene, 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/3lmglow/phosphene
- Repository: https://github.com/3lmglow/phosphene

## Overview

Phosphene is a self-hosted task, points, and rewards space shared by one user and one AI. The user works through the web app; the AI uses MCP to create and review tasks, inspect state, and manage rewards. The domain workflow covers task submission and approval, point/achievement settlement, and redemption followed by fulfillment; events support webhook delivery or history polling. Backup/restore, account security, private proof images, and PWA access are important supporting capabilities. Routes and startup wiring are sampled; several service internals are not, so uncertain calls are omitted.

Main entry points: [`src/server/db/client.ts`](https://github.com/3lmglow/phosphene/blob/main/src/server/db/client.ts) (Database access), [`src/server/routes.ts`](https://github.com/3lmglow/phosphene/blob/main/src/server/routes.ts) (HTTP routes), [`src/server/index.ts`](https://github.com/3lmglow/phosphene/blob/main/src/server/index.ts) (HTTP server), [`src/server/services/domain.ts`](https://github.com/3lmglow/phosphene/blob/main/src/server/services/domain.ts) (Task and reward rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User and AI clients"]
  node_web["Web PWA<br/>[App.tsx]"]
  node_browserapi["Web API client<br/>[api.ts]"]
  node_sw["PWA offline shell<br/>[sw.js]"]
end

subgraph group_entry["Application interfaces"]
  node_server["HTTP server<br/>[index.ts]"]
  node_routes["HTTP routes<br/>[routes.ts]"]
  node_mcp["MCP interface<br/>[mcp.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_recovery["Password recovery<br/>[recovery.ts]"]
end

subgraph group_domain["Task and reward domain"]
  node_domain["Task and reward rules<br/>[domain.ts]"]
  node_ledger["Points and achievements<br/>[constants.ts]"]
  node_events["Events and webhook settings<br/>[events.ts]"]
  node_worker["Webhook delivery worker<br/>[webhook-worker.ts]"]
  node_backup["Backup and restore<br/>[backup.ts]"]
end

subgraph group_state["Persistence and operations"]
  node_storage["Proof image storage<br/>[storage.ts]"]
  node_dbclient["Database access<br/>[client.ts]"]
  node_schema["Data schema<br/>[schema.ts]"]
  node_database[("SQLite database<br/>[client.ts]")]
  node_filesystem[("Persistent data volume")]
end

node_user(("User"))
node_ai(("AI client"))
node_aihost(("AI host"))
node_webhookendpoint["Webhook endpoint"]

node_user -->|"uses"| node_web
node_web -->|"requests"| node_browserapi
node_browserapi -->|"HTTP calls"| node_server
node_server -->|"dispatches API"| node_routes
node_server -->|"dispatches MCP"| node_mcp
node_routes -->|"authenticates"| node_auth
node_routes -->|"resets password"| node_recovery
node_routes -->|"queries and updates"| node_domain
node_routes -->|"handles proof images"| node_storage
node_routes -->|"exports and restores"| node_backup
node_mcp -->|"checks AI token"| node_auth
node_mcp -->|"task and reward tools"| node_domain
node_domain -->|"reads and writes"| node_dbclient
node_auth -->|"reads and writes"| node_dbclient
node_recovery -->|"reads and writes"| node_dbclient
node_events -->|"stores events"| node_dbclient
node_worker -->|"claims and updates"| node_events
node_worker -.->|"posts signed events"| node_webhookendpoint
node_ai -->|"MCP requests"| node_mcp
node_ai -.->|"polls event history"| node_routes
node_events -.->|"provides history"| node_aihost
node_domain -->|"records business events"| node_events
node_domain -->|"applies point rules"| node_ledger
node_storage -->|"reads asset references"| node_dbclient
node_storage -->|"stores image files"| node_filesystem
node_backup -->|"backs up business data"| node_dbclient
node_backup -->|"includes images"| node_filesystem
node_dbclient -->|"queries"| node_database
node_schema -->|"defines tables"| node_dbclient
node_server -->|"starts worker"| node_worker
node_server -->|"initializes database"| node_dbclient
node_server -->|"initializes storage"| node_storage
node_web -->|"registers offline support"| node_sw
node_sw -->|"caches app shell"| node_web

click node_web "https://github.com/3lmglow/phosphene/blob/main/src/web/App.tsx"
click node_browserapi "https://github.com/3lmglow/phosphene/blob/main/src/web/api.ts"
click node_server "https://github.com/3lmglow/phosphene/blob/main/src/server/index.ts"
click node_routes "https://github.com/3lmglow/phosphene/blob/main/src/server/routes.ts"
click node_mcp "https://github.com/3lmglow/phosphene/blob/main/src/server/mcp.ts"
click node_auth "https://github.com/3lmglow/phosphene/blob/main/src/server/services/auth.ts"
click node_recovery "https://github.com/3lmglow/phosphene/blob/main/src/server/services/recovery.ts"
click node_domain "https://github.com/3lmglow/phosphene/blob/main/src/server/services/domain.ts"
click node_ledger "https://github.com/3lmglow/phosphene/blob/main/src/shared/constants.ts"
click node_events "https://github.com/3lmglow/phosphene/blob/main/src/server/services/events.ts"
click node_worker "https://github.com/3lmglow/phosphene/blob/main/src/server/services/webhook-worker.ts"
click node_backup "https://github.com/3lmglow/phosphene/blob/main/src/server/services/backup.ts"
click node_storage "https://github.com/3lmglow/phosphene/blob/main/src/server/services/storage.ts"
click node_dbclient "https://github.com/3lmglow/phosphene/blob/main/src/server/db/client.ts"
click node_schema "https://github.com/3lmglow/phosphene/blob/main/src/server/db/schema.ts"
click node_database "https://github.com/3lmglow/phosphene/blob/main/src/server/db/client.ts"
click node_sw "https://github.com/3lmglow/phosphene/blob/main/public/sw.js"

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_web,node_browserapi,node_sw,node_user,node_ai toneBlue
class node_server,node_routes,node_mcp,node_auth,node_recovery toneAmber
class node_domain,node_ledger,node_events,node_worker,node_backup,node_webhookendpoint toneMint
class node_storage,node_dbclient,node_schema,node_database,node_filesystem toneRose
class node_aihost toneIndigo
```

## Components

### User and AI clients

- [Web PWA](https://github.com/3lmglow/phosphene/blob/main/src/web/App.tsx): `src/web/App.tsx`
- [Web API client](https://github.com/3lmglow/phosphene/blob/main/src/web/api.ts): `src/web/api.ts`
- [PWA offline shell](https://github.com/3lmglow/phosphene/blob/main/public/sw.js): `public/sw.js`

### Application interfaces

- [HTTP server](https://github.com/3lmglow/phosphene/blob/main/src/server/index.ts): `src/server/index.ts`
- [HTTP routes](https://github.com/3lmglow/phosphene/blob/main/src/server/routes.ts): `src/server/routes.ts`
- [MCP interface](https://github.com/3lmglow/phosphene/blob/main/src/server/mcp.ts): `src/server/mcp.ts`
- [Authentication](https://github.com/3lmglow/phosphene/blob/main/src/server/services/auth.ts): `src/server/services/auth.ts`
- [Password recovery](https://github.com/3lmglow/phosphene/blob/main/src/server/services/recovery.ts): `src/server/services/recovery.ts`

### Task and reward domain

- [Task and reward rules](https://github.com/3lmglow/phosphene/blob/main/src/server/services/domain.ts): `src/server/services/domain.ts`
- [Points and achievements](https://github.com/3lmglow/phosphene/blob/main/src/shared/constants.ts): `src/shared/constants.ts`
- [Events and webhook settings](https://github.com/3lmglow/phosphene/blob/main/src/server/services/events.ts): `src/server/services/events.ts`
- [Webhook delivery worker](https://github.com/3lmglow/phosphene/blob/main/src/server/services/webhook-worker.ts): `src/server/services/webhook-worker.ts`
- [Backup and restore](https://github.com/3lmglow/phosphene/blob/main/src/server/services/backup.ts): `src/server/services/backup.ts`

### Persistence and operations

- [Proof image storage](https://github.com/3lmglow/phosphene/blob/main/src/server/services/storage.ts): `src/server/services/storage.ts`
- [Database access](https://github.com/3lmglow/phosphene/blob/main/src/server/db/client.ts): `src/server/db/client.ts`
- [Data schema](https://github.com/3lmglow/phosphene/blob/main/src/server/db/schema.ts): `src/server/db/schema.ts`
- [SQLite database](https://github.com/3lmglow/phosphene/blob/main/src/server/db/client.ts): `src/server/db/client.ts`
- **Persistent data volume**

### Other components

- **User**
- **AI client**
- **AI host**
- **Webhook endpoint**

## Connections

- User → Web PWA: uses
- Web PWA → Web API client: requests
- Web API client → HTTP server: HTTP calls
- HTTP server → HTTP routes: dispatches API
- HTTP server → MCP interface: dispatches MCP
- HTTP routes → Authentication: authenticates
- HTTP routes → Password recovery: resets password
- HTTP routes → Task and reward rules: queries and updates
- HTTP routes → Proof image storage: handles proof images
- HTTP routes → Backup and restore: exports and restores
- MCP interface → Authentication: checks AI token
- MCP interface → Task and reward rules: task and reward tools
- Task and reward rules → Database access: reads and writes
- Authentication → Database access: reads and writes
- Password recovery → Database access: reads and writes
- Events and webhook settings → Database access: stores events
- Webhook delivery worker → Events and webhook settings: claims and updates
- Webhook delivery worker → Webhook endpoint: posts signed events
- AI client → MCP interface: MCP requests
- AI client → HTTP routes: polls event history
- Events and webhook settings → AI host: provides history
- Task and reward rules → Events and webhook settings: records business events
- Task and reward rules → Points and achievements: applies point rules
- Proof image storage → Database access: reads asset references
- Proof image storage → Persistent data volume: stores image files
- Backup and restore → Database access: backs up business data
- Backup and restore → Persistent data volume: includes images
- Database access → SQLite database: queries
- Data schema → Database access: defines tables
- HTTP server → Webhook delivery worker: starts worker
- HTTP server → Database access: initializes database
- HTTP server → Proof image storage: initializes storage
- Web PWA → PWA offline shell: registers offline support
- PWA offline shell → Web PWA: caches app shell