# jambonz/jambonz-api-server architecture

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

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

## Overview

##### Main Components

a) API Layer:
- REST API Server (Express.js based on the structure)
- Authentication/Authorization middleware (JWT-based)
- Rate limiting system
- Swagger documentation endpoint

b) Database Layer:
- MySQL Database (primary data store)
- Redis (caching/session management)
- InfluxDB (time series data)

c) External Services:
- Homer Integration (monitoring/logging)
- Kubernetes Services (when running in K8S mode)
- Various Speech Services:
- Multiple TTS providers (AWS, Google, Microsoft, etc.)
- Multiple STT providers (AssemblyAI, Deepgram, etc.)

d) Storage Systems:
- Cloud Storage integrations (Azure, Google, S3) for recordings

##### Relationship Flows to Illustrate

a) Primary Data Flows:
- Client → API Server → Authentication → Business Logic → Database
- Recording Flows: API Server → Cloud Storage
- Speech Processing: API Server → Various Speech Services

b) Secondary Flows:
- Caching: API Server ↔ Redis
- Monitoring: API Server → InfluxDB
- Logging: API Server → Homer

##### Architectural Patterns to Highlight

- Model-View-Controller (MVC) pattern (evident from the /lib/models and /lib/routes structure)
- Middleware-based authentication
- Service-oriented architecture for external integrations
- Multi-tenant architecture (based on service-provider and account models)

**┌─────────────────────────────────────────────────────────┐**
- Client Applications                     │
- ┘
- ↓
**┌─────────────────────────────────────────────────────────┐**
- API Gateway Layer                     │
- (Rate Limiting, Auth, Swagger, Route Handlers)         │
- ┘
- ↓
**┌─────────────────────────────────────────────────────────┐**
- Business Logic Layer                  │
- (Models, Services, Utils)                              │
- ┘
- ↓
**┌──────────────┐    ┌──────────────┐    ┌────────────────┐**
- MySQL DB    │    │    Redis     │    │   InfluxDB     │
- (Main Data)  │    │   (Cache)    │    │  (Time Series) │
- ┘    └──────────────┘    └────────────────┘

##### Important Details

- Environment configuration points
- Security layers (JWT, encryption)
- Database schema references
- API versioning
- Kubernetes integration points (when applicable)
- Recording and speech processing workflows

##### Specific Implementation Notes

- Relationship between the various speech service providers
- Multi-tenant architecture
- Separation between API routes and business logic
- Integration points with cloud storage services
- Monitoring and logging flows

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Layer"]
        CL[Client Applications]
    end

    subgraph API["API Gateway Layer"]
        REST["REST API Server"]:::api
        AUTH["Authentication System"]:::security
        DOCS["API Documentation"]:::docs
        MIDDLEWARE["Middleware"]:::api
        ERROR["Error Handler"]:::api
    end

    subgraph BL["Business Logic Layer"]
        MODELS["Models & Business Logic"]:::logic
        EMAIL["Email Services"]:::service
        PAYMENT["Payment Integration"]:::service
        PWD["Password Management"]:::security
    end

    subgraph Storage["Storage Layer"]
        DB[(MySQL Database)]:::db
        REDIS[(Redis Cache)]:::cache
        INFLUX[(InfluxDB)]:::db
        
        subgraph Cloud["Cloud Storage"]
            S3["AWS S3"]:::storage
            AZURE["Azure Storage"]:::storage
            GCP["Google Storage"]:::storage
        end
    end

    subgraph External["External Services"]
        direction TB
        subgraph Speech["Speech Services"]
            TTS["TTS Providers"]:::service
            STT["STT Providers"]:::service
        end
        HOMER["Homer Monitoring"]:::monitoring
        STRIPE["Stripe Payment"]:::service
    end

    %% Relationships
    CL --> REST
    REST --> AUTH
    REST --> DOCS
    REST --> MIDDLEWARE
    REST --> ERROR
    
    AUTH --> MODELS
    MIDDLEWARE --> MODELS
    
    MODELS --> DB
    MODELS --> REDIS
    MODELS --> INFLUX
    
    MODELS --> EMAIL
    MODELS --> PAYMENT
    MODELS --> PWD
    
    PAYMENT --> STRIPE
    
    MODELS --> Cloud
    MODELS --> Speech
    MODELS --> HOMER

    %% Styling
    classDef api fill:#2374ab
    classDef security fill:#7952b3
    classDef docs fill:#17a2b8
    classDef logic fill:#28a745
    classDef service fill:#fd7e14
    classDef db fill:#20c997
    classDef cache fill:#ffc107
    classDef storage fill:#6f42c1
    classDef monitoring fill:#dc3545

    %% Click Events
    click REST "https://github.com/jambonz/jambonz-api-server/tree/main/lib/routes/api/"
    click AUTH "https://github.com/jambonz/jambonz-api-server/tree/main/lib/auth/"
    click DOCS "https://github.com/jambonz/jambonz-api-server/blob/main/lib/swagger/swagger.yaml"
    click MODELS "https://github.com/jambonz/jambonz-api-server/tree/main/lib/models/"
    click REDIS "https://github.com/jambonz/jambonz-api-server/blob/main/lib/helpers/cache-client.js"
    click S3 "https://github.com/jambonz/jambonz-api-server/blob/main/lib/record/s3-multipart-upload-stream.js"
    click AZURE "https://github.com/jambonz/jambonz-api-server/blob/main/lib/record/azure-storage.js"
    click GCP "https://github.com/jambonz/jambonz-api-server/blob/main/lib/record/google-storage.js"
    click TTS "https://github.com/jambonz/jambonz-api-server/blob/main/lib/utils/speech-data/tts-*.js"
    click STT "https://github.com/jambonz/jambonz-api-server/blob/main/lib/utils/speech-data/stt-*.js"
    click HOMER "https://github.com/jambonz/jambonz-api-server/blob/main/lib/utils/homer-utils.js"
    click PWD "https://github.com/jambonz/jambonz-api-server/blob/main/lib/utils/password-utils.js"
    click EMAIL "https://github.com/jambonz/jambonz-api-server/blob/main/lib/utils/email-utils.js"
    click PAYMENT "https://github.com/jambonz/jambonz-api-server/tree/main/lib/routes/stripe/"
    click DB "https://github.com/jambonz/jambonz-api-server/blob/main/db/jambones-sql.sql"
    click ERROR "https://github.com/jambonz/jambonz-api-server/blob/main/lib/routes/error.js"
    click MIDDLEWARE "https://github.com/jambonz/jambonz-api-server/blob/main/lib/middleware.js"
```
