# signalapp/signal-server architecture

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

- Interactive diagram: https://gitdiagram.com/signalapp/signal-server
- Repository: https://github.com/signalapp/signal-server

## Overview

##### Project Type & Purpose
- This is Signal-Server: a backend service (Java/Dropwizard) that powers Signal messenger. It exposes HTTP/REST and gRPC endpoints, a WebSocket tunnel, handles authentication, message persistence, push notifications, attachments, backups, and payments integrations.

##### File Structure & Key Modules
- Top-level Maven modules:
- api-doc: an OpenAPI extension plugin
- integration-tests: end-to-end test suite
- service: the core Dropwizard application
- websocket-resources: reusable WebSocket resource provider library
- In `service/src/main/java`:
- controllers: HTTP‐JSON/GraphQL bridges (Jersey resources)
- grpc: gRPC service implementations & interceptors
- websocket: WebSocket handshake + tunnel server
- auth: authentication filters (REST & gRPC)
- storage: DynamoDB data stores & Redis message cache scripts
- push: APNs/FCM push manager
- attachments: GCS/S3/Tus providers
- config: service-level configuration classes
- workers & scheduler: cron‐style background jobs (backups, metrics, cleanup)
- subscriptions & payments: Braintree/Stripe/Google Play billing clients
- gcp/pubsub: Google Pub/Sub publishers for notifications
- External dependencies signaled by `configuration/*Configuration` classes: DynamoDB, Redis Cluster, Pub/Sub, TURN servers (Cloudflare), metrics (Datadog), S3, secure storage.

a. & Represent Main Components
- Clients: Mobile apps (iOS/Android), Web clients
- Entry Points:
- HTTP REST/Jersey (Dropwizard)
- gRPC server
- WebSocket tunnel server
- Core Services:
- Authentication Layer (REST filters & gRPC interceptors)
- Rate limiting & Spam checks
- Controllers / gRPC handlers
- Message persistence (Redis cache → DynamoDB)
- Attachment service (Tus/GCS/S3)
- Push service (APNs, FCM)
- Subscription & Payment service (Braintree GraphQL, Stripe, Google)
- Key distribution & verification (Key Transparency client)
- TURN server credential manager (Cloudflare)
- Data Stores & Middleware:
- DynamoDB tables
- Redis cluster (pub/sub & cache)
- Google Pub/Sub
- Secret store & dynamic config
- Background Workers:
- Job Scheduler (Quartz/Virt Threads)
- Backup/cleanup commands
- Metrics exporters (Micrometer → Datadog)

b. Relationships & Data Flows
- Auth filters precede controllers; controllers call storage and push layers
- Message flow: REST/gRPC → MessagePersister → Redis → DynamoDB
- Push flow: Controller → PushNotificationManager → APNs/FCM
- Attachment flow: Controller → AttachmentGenerator → GCS/S3
- Payment flow: Controller → Braintree/Stripe client → external payment gateway
- Key transparency & TURN credentials are fetched on demand via external service clients
- Background job flow: Scheduler → Worker commands → database/Redis modifications

c. Architectural Patterns & Principles
- Layered architecture: presentation (controllers), service (business logic), data (storage)
- Asynchronous pub/sub for message delivery (Redis, Pub/Sub)
- Modularization: distinct packages for auth, grpc, controllers, storage, push, subscriptions
- Configuration-driven and discoverable services (Dropwizard “Discoverable” modules via META-INF/services)
- Resilience: circuit breakers around external calls, fault-tolerant Redis & HTTP clients
- Secure channels: Noise protocol in gRPC/WebSocket net layer

d. Call Out Major Technologies & Frameworks
- Java 17 (or later) with Maven
- Dropwizard (HTTP, Jackson, Jetty)
- gRPC + Protobuf definitions
- Redis (Lettuce client, Lua scripts)
- AWS DynamoDB, S3, GCS
- Google Pub/Sub
- Cloudflare TURN service
- Micrometer / Datadog metrics
- APNs / FCM push
- Braintree GraphQL, Stripe & Google Play billing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        direction TB
        MobileApps["Mobile Apps (iOS/Android)"]:::external
        WebClient["Web Client"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        HTTP["HTTP REST (Dropwizard Jersey)"]:::api
        GRPC["gRPC Server"]:::api
        WS["WebSocket Tunnel Server"]:::api
    end

    %% Auth Layer
    subgraph "Authentication Layer"
        direction TB
        AuthREST["REST Filters"]:::biz
        AuthGRPC["gRPC Interceptors"]:::biz
    end

    %% Business Layer
    subgraph "Business Layer"
        direction TB
        Controllers["Controllers / Handlers"]:::biz
        RateSpam["Rate Limiting & Spam Filter"]:::biz
        MessagePersister["MessagePersister Service"]:::biz
        AttachmentSvc["Attachment Service"]:::biz
        PushSvc["PushNotification Manager"]:::biz
        SubscriptionSvc["Subscription & Payment Service"]:::biz
        KeyDist["Key Distribution / Verification"]:::biz
        TURNCredMgr["TURN Credentials Manager"]:::biz
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Redis["Redis Cluster (Cache, Pub/Sub)"]:::data
        DynamoDB["DynamoDB Tables"]:::data
        PubSub["Google Pub/Sub"]:::data
        SecretStore["Secret Store & Config"]:::data
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        APNs["APNs"]:::external
        FCM["FCM"]:::external
        Braintree["Braintree Gateway"]:::external
        Stripe["Stripe Gateway"]:::external
        GooglePlay["Google Play Billing"]:::external
        GCS["Google Cloud Storage"]:::external
        S3["AWS S3"]:::external
        KeyTransparency["Key Transparency Service"]:::external
        TURNServer["Cloudflare TURN Servers"]:::external
    end

    %% Scheduler & Workers
    subgraph "Scheduler & Workers"
        direction TB
        JobScheduler["Job Scheduler"]:::sched
        Workers["Background Workers"]:::sched
    end

    %% Entry point
    WhisperServer["Dropwizard Application\n(WhisperServerService)"]:::api
    click WhisperServer "https://github.com/signalapp/signal-server/blob/main/service/src/main/java/org/whispersystems/textsecuregcm/WhisperServerService.java"

    %% Configuration
    Config["Service Configuration"]:::biz
    click Config "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/configuration"

    %% Mappings click events
    click Controllers "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/controllers"
    click GRPC "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/grpc"
    click WS "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/websocket"
    click WS "https://github.com/signalapp/signal-server/blob/main/service/src/main/java/org/whispersystems/textsecuregcm/grpc/net/websocket/NoiseWebSocketTunnelServer.java"
    click AuthREST "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/auth"
    click AuthGRPC "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/auth/grpc"
    click MessagePersister "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/storage"
    click MessagePersister "https://github.com/signalapp/signal-server/tree/main/service/src/main/resources/lua"
    click PushSvc "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/push"
    click AttachmentSvc "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/attachments"
    click SubscriptionSvc "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/subscriptions"
    click SubscriptionSvc "https://github.com/signalapp/signal-server/tree/main/service/src/main/graphql/braintree"
    click PubSub "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/gcp/pubsub"
    click PubSub "https://github.com/signalapp/signal-server/blob/main/service/src/main/java/org/whispersystems/textsecuregcm/configuration/DefaultPubSubPublisherFactory.java"
    click JobScheduler "https://github.com/signalapp/signal-server/blob/main/service/src/main/java/org/whispersystems/textsecuregcm/scheduler/JobScheduler.java"
    click Workers "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/workers"
    click RateSpam "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/limits"
    click RateSpam "https://github.com/signalapp/signal-server/tree/main/service/src/main/java/org/whispersystems/textsecuregcm/spam"
    click Config "https://github.com/signalapp/signal-server/blob/main/service/src/main/java/org/whispersystems/textsecuregcm/configuration/DatadogConfiguration.java"
    click TURNCredMgr "https://github.com/signalapp/signal-server/blob/main/service/src/main/java/org/whispersystems/textsecuregcm/auth/CloudflareTurnCredentialsManager.java"
    click Config "https://github.com/signalapp/signal-server/blob/main/service/src/main/java/org/whispersystems/textsecuregcm/configuration/CloudflareTurnConfiguration.java"

    %% Flows
    MobileApps -->|HTTP, gRPC, WS| HTTP
    MobileApps -->|gRPC| GRPC
    MobileApps -->|WebSocket| WS
    WebClient -->|HTTP, WebSocket| HTTP
    HTTP --> WhisperServer
    GRPC --> WhisperServer
    WS --> WhisperServer

    WhisperServer --> Config

    WhisperServer --> AuthREST
    WhisperServer --> AuthGRPC

    AuthREST --> Controllers
    AuthGRPC --> Controllers

    Controllers --> RateSpam
    RateSpam --> Controllers

    Controllers --> MessagePersister
    Controllers --> AttachmentSvc
    Controllers --> PushSvc
    Controllers --> SubscriptionSvc
    Controllers --> KeyDist
    Controllers --> TURNCredMgr

    MessagePersister --> Redis
    MessagePersister --> DynamoDB

    Redis ---|Pub/Sub| PubSub

    PushSvc --> APNs
    PushSvc --> FCM

    AttachmentSvc --> GCS
    AttachmentSvc --> S3

    SubscriptionSvc --> Braintree
    SubscriptionSvc --> Stripe
    SubscriptionSvc --> GooglePlay

    KeyDist --> KeyTransparency
    TURNCredMgr --> TURNServer

    %% Scheduler flows
    JobScheduler --> Workers
    Workers --> Redis
    Workers --> DynamoDB

    %% Styles
    classDef api fill:#FADADD,stroke:#C04080,color:#000;
    classDef biz fill:#D0E1F9,stroke:#1F4E79,color:#000;
    classDef data fill:#DFF2BF,stroke:#4F8A10,color:#000;
    classDef external fill:#FFE4B5,stroke:#C07A00,color:#000;
    classDef sched fill:#E2D1F9,stroke:#6A1B9A,color:#000;
```
