Fastify Docker Server

Relevant source files

The following files were used as context for generating this wiki page:

• apps/server/docker/CLAUDE.md
• CLAUDE.md
• knowledge.md
• apps/server/workers/README.md
• apps/server/workers/src/index.ts

The Fastify Docker Server (also known as happy-server) is the core backend API for the Happy ecosystem. It is a TypeScript-based application built on the Fastify framework, designed to run within Docker containers. Its primary purpose is to facilitate remote control and session sharing for Claude Code and Codex by acting as a high-performance relay between CLI daemons and mobile or web clients.

Operating as a "zero-knowledge" relay, the server facilitates communication using end-to-end encryption. It manages session synchronization, authentication challenges, and data persistence without ever accessing the plaintext user data. It utilizes a robust stack including PostgreSQL for relational data, Redis for real-time pub/sub and caching, and S3-compatible storage for artifacts.

Sources: apps/server/docker/CLAUDE.md:12-25, CLAUDE.md:10-25, knowledge.md:27-38

System Architecture

The server follows an opinionated, modular architecture that separates application logic from reusable utility modules. It utilizes a CommonJS module system and maintains a strict directory structure to ensure scalability and maintainability.

Core Components

The following diagram illustrates the high-level architecture and external dependencies of the Fastify Docker server.

The server acts as a central hub connecting clients and maintaining state via external storage engines.
Sources: apps/server/docker/CLAUDE.md:102-124, CLAUDE.md:214-222

Logic Layers

Layer	Directory	Description
App Entry	/sources/app	API server setup and timeout handling.
Applications	/sources/apps	Application-specific logic, including API routes (/routes).
Modules	/sources/modules	Reusable logic (AI wrappers, event bus, locking, media tools).
Services	/sources/services	Core infrastructure services like Pub/Sub.
Storage	/sources/storage	Database clients (Prisma), transactions, and caching.
Utilities	/sources/utils	Low-level abstract utilities.

Sources: apps/server/docker/CLAUDE.md:102-124

Data and Event Flow

The server utilizes a combination of RESTful APIs for state management and WebSockets (via Socket.io) for real-time updates. It employs a Redis-backed Event Bus to synchronize events across multiple process instances in a cluster.

Session Synchronization Flow

The following sequence diagram describes how a session update flows from the CLI through the server to a mobile client.

The server functions as a "zero-knowledge" relay, ensuring it cannot decrypt the payloads moving through the system.
Sources: CLAUDE.md:214-222, apps/server/docker/CLAUDE.md:158-161

Authentication and Pairing

The server facilitates a challenge-response authentication flow, primarily used for pairing new devices via QR codes.

1. Request: The CLI generates a keypair and requests an authentication challenge from /v1/auth/request.
2. Scanning: A mobile app scans the QR code containing the public key.
3. Response: The mobile app approves the connection by sending a response to /v1/auth/response.
4. Validation: The server facilitates the signature verification without ever storing private keys.

Sources: CLAUDE.md:209-213, apps/server/docker/CLAUDE.md:195-201

Database and Persistence

Persistence is handled through Prisma ORM targeting a PostgreSQL database. The system emphasizes transaction safety and idempotency.

Persistence Strategy

• Prisma ORM: Used for all relational data mapping.
• Transactions: Operations are wrapped in an inTx utility to ensure atomicity.
• Event Integration: The server uses afterTx to emit events only after a database transaction has successfully committed.
• Schema: Complex data fields often utilize the Json type for flexibility.

Sources: apps/server/docker/CLAUDE.md:144-152, apps/server/docker/CLAUDE.md:158-161

Configuration Parameters

The server requires specific environment variables for Docker deployment.

Variable	Type	Description
DATABASE_URL	String	PostgreSQL connection string for Prisma.
REDIS_URL	String	Connection string for Redis pub/sub and caching.
HAPPY_MASTER_SECRET	String	32-byte hex key for JWT signing (formerly HANDY_MASTER_SECRET).
S3_ENDPOINT	String	Endpoint for S3-compatible storage (e.g., MinIO or AWS).
S3_BUCKET	String	Bucket name for storing session artifacts.

Sources: apps/server/docker/CLAUDE.md:46-55, CLAUDE.md:310-318

Deployment and Runtime

The server is packaged as a multi-stage Docker image, ensuring a minimal runtime footprint.

Docker Environment

• Runtime: Node.js 20.
• Dependencies: Requires FFmpeg for media processing and Python3 for specific backend tasks.
• Port: Exposes port 3000 by default.
• Process Management: Utilizes yarn start to initiate the Fastify instance.

Sources: apps/server/docker/CLAUDE.md:21-44, apps/server/docker/CLAUDE.md:175-181

Maintenance and Debugging

The server includes built-in diagnostic features for developers:

• Remote Logging: When DANGEROUSLY_LOG_TO_SERVER_FOR_AI_AUTO_DEBUGGING is enabled, the server aggregates logs from CLI and mobile clients into the .logs/ directory.
• Health Checks: Dedicated endpoints for verifying system readiness and connectivity.
• Secret Generation: A provided script ./scripts/generate-secrets.sh is used to bootstrap cryptographic keys for the environment.

Sources: apps/server/docker/CLAUDE.md:58-61, apps/server/docker/CLAUDE.md:185-191

The Fastify Docker Server provides a scalable, secure foundation for the Happy ecosystem, prioritizing end-to-end encryption and real-time responsiveness through a modular, service-oriented design.