# interval/server architecture

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

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

## Overview

##### Main Components

a) Core Server Components:
- HTTP/WebSocket Server (Port 3000)
- Authentication Service
- Transaction Processing Engine
- WebSocket State Management
- File Upload Service
- Email Service
- Notification System

b) External Services Integration:
- PostgreSQL Database
- S3/Compatible Storage
- Postmark (Email)
- WorkOS (SSO/Auth)
- Slack (Notifications)

c) Client Interface:
- Web Dashboard
- API/WebSocket Interface
- SDK Connection Layer

##### Component Relationships

**Client Layer**
**↓↑**
**HTTP/WebSocket Server**
**↓↑**
**Core Services Layer (Authentication, Transactions, etc.)**
**↓↑**
**External Services Layer (Database, Storage, etc.)**

##### Specific Implementation Details

- WebSocket-based real-time communication (/websocket endpoint)
- Transaction processing flow
- Authentication flow with multiple providers
- File upload pipeline
- Notification distribution system

##### Key Technical Elements

Crucial components:
- Environment configuration management
- Security layer (AUTH_COOKIE_SECRET, WSS_API_SECRET)
- Database connection pool
- WebSocket state management
- File upload processing pipeline

##### Architectural Patterns

Emphasize:
- Service-oriented architecture
- Real-time communication patterns
- Stateful WebSocket connections
- Authentication/Authorization flow

##### Component Details

For each major component, include:
- Input/Output interfaces
- Key dependencies
- Security boundaries
- Scaling considerations

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        WD[Web Dashboard]:::client
        SDK[SDK Connection]:::client
        API[API Interface]:::client
    end

    subgraph "Server Layer"
        HTTP[HTTP Server]:::server
        WSS[WebSocket Server]:::server
        click HTTP "https://github.com/interval/server/blob/main/src/server/index.ts"
        click WSS "https://github.com/interval/server/blob/main/src/wss/wss.ts"

        subgraph "Core Services"
            AUTH[Authentication Service]:::core
            TRANS[Transaction Engine]:::core
            WSM[WebSocket State Manager]:::core
            UPLOAD[File Upload Service]:::core
            EMAIL[Email Service]:::core
            NOTIFY[Notification System]:::core

            click AUTH "https://github.com/interval/server/tree/main/src/server/api/auth/"
            click TRANS "https://github.com/interval/server/blob/main/src/server/trpc/transaction.ts"
            click WSM "https://github.com/interval/server/tree/main/src/wss/inApp/wss_state/"
            click UPLOAD "https://github.com/interval/server/blob/main/src/server/trpc/uploads.ts"
            click EMAIL "https://github.com/interval/server/tree/main/src/emails/"
            click NOTIFY "https://github.com/interval/server/blob/main/src/server/api/notify.ts"
        end
    end

    subgraph "External Services"
        DB[(PostgreSQL)]:::external
        S3[S3 Storage]:::external
        PMARK[Postmark]:::external
        WORKOS[WorkOS SSO]:::external
        SLACK[Slack]:::external
    end

    %% Client to Server Connections
    WD --> HTTP
    SDK --> WSS
    API --> HTTP

    %% Server to Core Services
    HTTP --> AUTH
    HTTP --> TRANS
    WSS --> WSM
    HTTP --> UPLOAD
    HTTP --> EMAIL
    HTTP --> NOTIFY

    %% Core Services Interconnections
    AUTH <--> TRANS
    WSM <--> TRANS
    NOTIFY --> WSM
    UPLOAD --> WSM

    %% Core to External Services
    AUTH --> WORKOS
    UPLOAD --> S3
    EMAIL --> PMARK
    NOTIFY --> SLACK
    AUTH --> DB
    TRANS --> DB
    WSM --> DB
    UPLOAD --> DB
    EMAIL --> DB
    NOTIFY --> DB

    classDef client fill:#FFA500,stroke:#333,stroke-width:2px
    classDef server fill:#4169E1,stroke:#333,stroke-width:2px
    classDef core fill:#1E90FF,stroke:#333,stroke-width:2px
    classDef external fill:#32CD32,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        C1[Client Component]:::client
        S1[Server Component]:::server
        CS1[Core Service]:::core
        E1[External Service]:::external
    end
```
