How slopus/happy-server works
Project type and purpose
• Happy Server is a standalone backend microservice written in TypeScript/Node.js.
• Its sole purpose is to act as a zero-knowledge synchronization backbone for end-to-end encrypted clients (“Claude Code”). It exposes both a RESTful HTTP API and a WebSocket layer to store encrypted blobs, manage sessions, and push real-time updates without ever seeing plaintext.
High-level file-structure analysis
• Top level: Dockerfile, deploy manifests, Prisma folder (database migrations + schema), tsconfig, package.json.
• sources/app/api: HTTP routes (account, auth, sessions, push, etc.) + WebSocket setup & handlers.
• sources/app/auth: cryptographic public-key signature logic.
• sources/app/events: in-process event router for internal pub/sub.
• sources/app/presence: session cache + timeout logic for online presence.
• sources/app/monitoring: metrics endpoints/integration.
• sources/storage: persistence abstractions (PostgreSQL via Prisma, Redis, file uploads, caching, sequencing).
• sources/modules: helper modules (encryption primitives, GitHub integration).
• sources/utils: general utilities (backoff, locking, logging, shutdown handling).
• main.ts is the composition root—wire up API, WebSocket, auth, monitoring, error handlers.
Main components
a. External Clients
• Mobile/Desktop Claude-Code apps (generate keys locally, call HTTP API & maintain WS).
b. Load Balancer / API Gateway (optional)
• Routes incoming HTTP & WS connections to one or more Happy Server instances.
c. Happy Server Container
• HTTP API Layer (routes in app/api/routes)
• WebSocket Server (app/api/socket/*.ts)
• Authentication Module (app/auth/auth.ts)
• Event Router (app/events/eventRouter.ts) for internal dispatch
• Presence Manager (app/presence/*.ts) for session state + timeouts
• Monitoring Middleware (app/monitoring/*.ts) for metrics endpoints
• Business logic modules (e.g., encryption in modules/, image processing)
• Persistence Abstraction (storage/ directory)
d. Data Stores
• PostgreSQL (Prisma ORM) – relational storage of encrypted blobs, sessions, metadata
• Redis – ephemeral caches, pub/sub for real-time sync, locks, repeat keys
• File storage (S3 or local FS via storage/files.ts) for any blob uploads
e. External Services
• Push Notification Providers (APNs, FCM) invoked by pushRoutes.ts
• (Optional) GitHub OAuth or other identity services if configured via modules/github.ts
Relationships & interactions
• Clients ↔ HTTP API: account management, session init, listing blobs
• Clients ↔ WebSocket: real-time sync updates (sessionUpdate, machineUpdate, usage events)
• API & WS handlers → Auth Module: verify public-key signatures on each request/connection
• API & WS → Event Router → Presence Manager & Storage Layer
• Storage Layer → PostgreSQL (via Prisma client) for durable state
• Storage Layer → Redis for caching and pub/sub notifications to other server instances
• PushRoutes → External Push Providers for notifying devices
• Monitoring middleware exposing metrics to Prometheus or other scrapers
Architectural patterns & design principles
• Layered architecture: API Layer → Business Logic → Persistence
• Event-driven internals: in-process event router for decoupling API and background tasks
• Pub/Sub via Redis for cross-instance real-time sync
• Zero-knowledge principle: encryption/decryption only on clients, server treats blobs as opaque
• Containerized microservice: Docker + Kubernetes manifests for horizontal scalability
Essential elements checklist
• [ ] External Clients and Load Balancer
• [ ] Happy Server container with internal layers clearly separated
• [ ] WebSocket channel and HTTP API ingress points
• [ ] Event Bus/pub-sub path
• [ ] Push Notification flow to external services