# signalapp/contactdiscoveryservice-icelake architecture

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

- Interactive diagram: https://gitdiagram.com/signalapp/contactdiscoveryservice-icelake
- Repository: https://github.com/signalapp/contactdiscoveryservice-icelake

## Overview

##### Project Type and Purpose
- CDSI is a hybrid full-stack service combining a Java (Micronaut) host-side server with an Intel SGX enclave implemented in C.
- It exposes a WebSocket/API endpoint for client contact-discovery requests, enforces authentication and multi-tier rate limiting, and uses a secure enclave to store and query directory data.
- It ingests account updates from AWS DynamoDB/Kinesis via an AWS Lambda “filter-cds-updates” function.

##### Main Components
a. Client Layer
- Signal mobile/desktop clients (or any WebSocket-capable client)
b. Host Application (Java/Micronaut)
- HTTP/WebSocket API layer (WebSocketHandler)
- Authentication filter (ExternalServiceTokenAuthenticationProvider)
- Rate-limiting filters
– Connection rate limiter (Redis-backed leaky-bucket)
– Directory query rate limiter (Cosmos DB token bucket)
- Account synchronization
– DynamoDbAccountPopulator (reads from DynamoDB + Kinesis via KinesisClientFactory)
– RandomAccountPopulator (dev/mock)
- EnclaveClient (JNI wrapper for native C enclave calls)
- Health & metrics endpoints
c. Enclave (C/Open Enclave)
- Native enclave binary (loaded via shim/JNI)
- Data structures and algorithms (ohtable, path_oram, noiseutil, etc.)
- Account directory storage and secure query logic
d. AWS Lambda: filter-cds-updates
- Consumes DynamoDB stream events, filters relevant updates, writes to Kinesis
e. External Services & Data Stores
- AWS DynamoDB table + update stream
- AWS Kinesis stream
- Azure Cosmos DB (directory query rate-limiter backend)
- Redis Cluster (connection rate-limiter backend)
- Authentication secret store (external service credentials)

##### Key Interactions & Data Flows
1. Account update in DynamoDB → DynamoDB stream → AWS Lambda (filter) → Kinesis
2. Host service Kinesis consumer → calls DynamoDbAccountPopulator → EnclaveClient.ingestAccount()
3. Client connects via WebSocket → Authentication → Connection rate limiter (Redis) → Directory query rate limiter (Cosmos) → EnclaveClient.queryDirectory() → results → client
4. Health checks & metrics reported to Micronaut actuator endpoints

##### Architectural Patterns & Principles
- Layered architecture: API layer → business logic → enclave boundary → native code
- Secure enclave boundary via JNI/OpenEnclave (Separation of trust domains)
- Event-driven ingestion (AWS Lambda → Kinesis → populator)
- Pluggable account sources (DynamoDB/Kinesis vs. random/mock)
- Circuit-breaker, retry, and back-pressure (via Micronaut, Kinesis retry configs)
- Reactive/non-blocking WebSocket I/O (Micronaut Netty)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Client Layer"
        Client["Signal Client"]:::client
    end

    %% AWS Production VPC
    subgraph "Production AWS VPC"
        subgraph "Event Ingestion"
            DynamoDB["AWS DynamoDB\n(table & stream)"]:::db
            Lambda["filter-cds-updates\n(Lambda)"]:::lambda
            Kinesis["AWS Kinesis\nstream"]:::stream
        end
        subgraph "Data Stores"
            Redis["Redis Cluster"]:::db
            Cosmos["Azure Cosmos DB"]:::db
        end
    end

    %% Host Process
    subgraph "Host Process (Java/Micronaut)"
        App["Application Entrypoint\n(Application.java)"]:::host
        WS["WebSocketHandler\n(WebSocketHandler.java)"]:::host
        Auth["ExternalServiceTokenAuthenticationProvider\n(AuthenticationProvider.java)"]:::host

        subgraph "Rate Limiters"
            LBFactory["LeakyBucketRedisClientFactory\n(LeakyBucketRedisClientFactory.java)"]:::host
            RedisLimiter["RedisLeakyBucketRateLimiter\n(RedisLeakyBucketRateLimiter.java)"]:::host
            CTFactory["CosmosClientFactory\n(CosmosClientFactory.java)"]:::host
            CosmosLimiter["CosmosTokenRateLimiter\n(CosmosTokenRateLimiter.java)"]:::host
            TokenBucket["TokenBucket\n(TokenBucket.java)"]:::host
        end

        subgraph "Account Synchronization"
            DynamoPop["DynamoDbAccountPopulator\n(DynamoDbAccountPopulator.java)"]:::host
            DynamoFactory["DynamoDbClientFactory\n(DynamoDbClientFactory.java)"]:::host
            KinesisFactory["KinesisClientFactory\n(KinesisClientFactory.java)"]:::host
            RandomPop["RandomAccountPopulator\n(RandomAccountPopulator.java)"]:::host
        end

        EnclaveClient["EnclaveClient (JNI wrapper)\n(EnclaveClient.java)"]:::host
        Health["Health & Metrics Endpoints\n(health/ & metrics/)"]:::host
    end

    %% SGX Enclave
    subgraph "SGX Enclave (C/Open Enclave)"
        EnclaveBin["Native Enclave Binary\n(enc.c, shim.h)"]:::enclave
    end

    %% Flows
    DynamoDB -->|"Stream events"| Lambda
    Lambda -->|"Filtered updates"| Kinesis
    Kinesis -->|"Consume events"| DynamoPop
    DynamoPop -->|"ingestAccount()"| EnclaveClient
    EnclaveClient -->|"JNI call"| EnclaveBin
    EnclaveBin -->|"response"| EnclaveClient

    Client -->|"WebSocket"| WS
    WS -->|"authenticate"| Auth
    Auth -->|"connection rate check"| RedisLimiter
    RedisLimiter -->|"query rate check"| CosmosLimiter
    CosmosLimiter -->|"queryDirectory()"| EnclaveClient
    EnclaveClient -->|"JNI call"| EnclaveBin
    EnclaveBin -->|"results"| EnclaveClient
    EnclaveClient -->|"respond"| WS
    WS -->|"WebSocket"| Client

    App --> Health

    %% Click Events
    click App "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/Application.java"
    click WS "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/WebSocketHandler.java"
    click Auth "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/auth/ExternalServiceTokenAuthenticationProvider.java"
    click LBFactory "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/limits/redis/LeakyBucketRedisClientFactory.java"
    click RedisLimiter "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/limits/redis/RedisLeakyBucketRateLimiter.java"
    click CosmosLimiter "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/limits/cosmos/CosmosTokenRateLimiter.java"
    click TokenBucket "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/limits/cosmos/TokenBucket.java"
    click CTFactory "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/limits/cosmos/CosmosClientFactory.java"
    click DynamoPop "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/account/aws/DynamoDbAccountPopulator.java"
    click DynamoFactory "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/account/aws/DynamoDbClientFactory.java"
    click KinesisFactory "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/account/aws/KinesisClientFactory.java"
    click RandomPop "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/account/RandomAccountPopulator.java"
    click EnclaveClient "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/src/main/java/org/signal/cdsi/enclave/EnclaveClient.java"
    click Lambda "https://github.com/signalapp/contactdiscoveryservice-icelake/blob/main/filter-cds-updates/src/main/java/org/signal/lambda/FilterCdsUpdatesHandler.java"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef host fill:#DFFFE0,stroke:#2E8B57,color:#2E8B57;
    classDef enclave fill:#FFE4B5,stroke:#FF8C00,color:#FF8C00;
    classDef lambda fill:#E5D0FF,stroke:#800080,color:#800080;
    classDef db fill:#E0FFFF,stroke:#20B2AA,color:#20B2AA;
    classDef stream fill:#FFF0F5,stroke:#C71585,color:#C71585;
```
