How 3lmglow/phosphene works
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: client.ts Database access · routes.ts HTTP routes · index.ts HTTP server · domain.ts Task and reward rules
Components 22
User and AI clients
- Web PWA
src/web/App.tsx - Web API client
src/web/api.ts - PWA offline shell
public/sw.js
Application interfaces
- HTTP server
src/server/index.ts - HTTP routes
src/server/routes.ts - MCP interface
src/server/mcp.ts - Authentication
src/server/services/auth.ts - Password recovery
src/server/services/recovery.ts
Task and reward domain
- Task and reward rules
src/server/services/domain.ts - Points and achievements
src/shared/constants.ts - Events and webhook settings
src/server/services/events.ts - Webhook delivery worker
src/server/services/webhook-worker.ts - Backup and restore
src/server/services/backup.ts
Persistence and operations
- Proof image storage
src/server/services/storage.ts - Database access
src/server/db/client.ts - Data schema
src/server/db/schema.ts - SQLite database
src/server/db/client.ts - Persistent data volume
Other components
- User
- AI client
- AI host
- Webhook endpoint
Connections 34
- 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