# slopus/happy-server architecture

> Architecture diagram of the GitHub repository slopus/happy-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/slopus/happy-server
- Repository: https://github.com/slopus/happy-server

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients and Load Balancer
    Clients["Clients (Mobile/Desktop)"]:::external
    LB["Load Balancer / API Gateway"]:::ingress

    Clients -->|"HTTPS / WSS"| LB

    %% Happy Server Container
    subgraph "Happy Server Container"
        direction TB

        Main["Composition Root"]:::internal

        subgraph "Ingress Layer"
            direction TB
            HTTPAPI["HTTP API Layer"]:::ingress
            WS["WebSocket Server"]:::ingress
        end

        subgraph "Auth & Routing"
            direction TB
            Auth["Authentication Module"]:::internal
            EventRouter["Event Router"]:::internal
        end

        subgraph "Business Modules"
            direction TB
            Presence["Presence Manager"]:::internal
            Encryption["Encryption Primitives"]:::internal
            GitHub["GitHub Integration"]:::internal
            ProcessImage["Image Processing"]:::internal
        end

        subgraph "Monitoring"
            direction TB
            Metrics1["Metrics (metrics.ts)"]:::internal
            Metrics2["Metrics2 (metrics2.ts)"]:::internal
        end

        subgraph "Persistence Adapters"
            direction TB
            Postgres["PostgreSQL (Prisma)"]:::store
            RedisStore["Redis"]:::store
            Files["File Storage"]:::store
            InTx["Transaction Wrapper"]:::store
            Cache["Caching & Sequencing"]:::store
        end

        %% Internal flows
        Main --> HTTPAPI
        Main --> WS
        Main --> Auth
        Main --> Metrics1
        Main --> Metrics2

        HTTPAPI -->|authenticate| Auth
        WS -->|authenticate| Auth
        Auth --> EventRouter
        EventRouter --> Presence
        EventRouter --> InTx
        InTx --> Postgres
        EventRouter --> Cache
        Cache --> RedisStore
        EventRouter --> Files
        EventRouter --> ProcessImage
        EventRouter --> Encryption
        EventRouter --> GitHub
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Postgres
        RedisStore
        Files
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Push["Push Notification Providers"]:::external
        OAuth["OAuth Provider"]:::external
        Utils["Utility Library"]:::external
    end

    %% Flows to external services
    HTTPAPI -->|pushRoutes| Push
    GitHub -->|OAuth calls| OAuth
    RedisStore -.->|Redis Pub/Sub| HTTPAPI
    RedisStore -.->|Redis Pub/Sub| WS

    %% Click Events
    click HTTPAPI "https://github.com/slopus/happy-server/blob/main/sources/app/api/api.ts"
    click HTTPAPI "https://github.com/slopus/happy-server/tree/main/sources/app/api/routes/"
    click WS "https://github.com/slopus/happy-server/blob/main/sources/app/api/socket.ts"
    click WS "https://github.com/slopus/happy-server/blob/main/sources/app/api/socket/*.ts"
    click Auth "https://github.com/slopus/happy-server/blob/main/sources/app/auth/auth.ts"
    click EventRouter "https://github.com/slopus/happy-server/blob/main/sources/app/events/eventRouter.ts"
    click Presence "https://github.com/slopus/happy-server/blob/main/sources/app/presence/sessionCache.ts"
    click Presence "https://github.com/slopus/happy-server/blob/main/sources/app/presence/timeout.ts"
    click Metrics1 "https://github.com/slopus/happy-server/blob/main/sources/app/monitoring/metrics.ts"
    click Metrics2 "https://github.com/slopus/happy-server/blob/main/sources/app/monitoring/metrics2.ts"
    click Main "https://github.com/slopus/happy-server/blob/main/sources/main.ts"
    click Postgres "https://github.com/slopus/happy-server/blob/main/prisma/schema.prisma"
    click Postgres "https://github.com/slopus/happy-server/tree/main/prisma/migrations/"
    click RedisStore "https://github.com/slopus/happy-server/blob/main/sources/storage/redis.ts"
    click Files "https://github.com/slopus/happy-server/blob/main/sources/storage/files.ts"
    click InTx "https://github.com/slopus/happy-server/blob/main/sources/storage/inTx.ts"
    click Cache "https://github.com/slopus/happy-server/blob/main/sources/storage/simpleCache.ts"
    click Cache "https://github.com/slopus/happy-server/blob/main/sources/storage/seq.ts"
    click Encryption "https://github.com/slopus/happy-server/blob/main/sources/modules/encrypt.ts"
    click GitHub "https://github.com/slopus/happy-server/blob/main/sources/modules/github.ts"
    click ProcessImage "https://github.com/slopus/happy-server/blob/main/sources/storage/processImage.ts"
    click Utils "https://github.com/slopus/happy-server/tree/main/sources/utils/"
    click Push "https://github.com/slopus/happy-server/blob/main/sources/app/api/routes/pushRoutes.ts"
    click Dockerfile "https://github.com/slopus/happy-server/tree/main/Dockerfile"
    click RedisDeploy "https://github.com/slopus/happy-server/blob/main/deploy/happy-redis.yaml"
    click K8s "https://github.com/slopus/happy-server/blob/main/deploy/handy.yaml"

    %% Styles
    classDef ingress fill:#ADD8E6,stroke:#000
    classDef internal fill:#90EE90,stroke:#000
    classDef store fill:#FFA500,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
```
