# prabanjanjeyasankar/status-deck-server architecture

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

- Interactive diagram: https://gitdiagram.com/prabanjanjeyasankar/status-deck-server
- Repository: https://github.com/prabanjanjeyasankar/status-deck-server

## Overview

##### Project Type and Purpose
- This is a backend-focused **API health monitoring platform** (“Status Deck”) built with FastAPI, Prisma (ORM for a relational database), Redis (cache and pub/sub), and WebSockets.
- It comprises:
- A REST API server for clients (e.g., dashboards, CLI) to create incidents, query status, manage organizations/users.
- Background monitors that poll/check external services and generate incident records.
- A WebSocket broadcaster service for real-time updates to connected clients.
- Prisma-managed relational database (e.g., PostgreSQL) for persistence.
- Redis for caching and cross‐process pub/sub.

##### File Structure Analysis
- **app/**: core Python modules
- auth/ – authentication routes & logic
- incidents/ – incident models & business logic
- monitors/ – background “monitors” and failure counting
- services/ – service definitions and status routes
- websocket/ – WebSocket routers & broadcast logic
- db.py – Prisma client initialization
- main.py – FastAPI app entrypoint for HTTP API
- **prisma/**: schema.prisma + migrations for database
- **scripts/**: `dev_run.sh` spins up all processes (API server, WS broadcaster, monitors), `full_clear.sh` clears caches/migrations
- **seed.py**: seeds test users and an organization
- **Procfile**: defines process types (for Heroku or Foreman)

##### Relevant README Insights
- Development spin-up concurrently starts:
- FastAPI (uvicorn) on port 8000
- WebSocket broadcaster on port 8001
- Auto Incident Monitor (polling service)
- Redis and Prisma caches used by various processes
- Prisma generate step to refresh client

##### Main Components & Interactions
A. HTTP API Server (FastAPI / uvicorn)
B. Background Monitors
C. WebSocket Broadcaster Service
D. Relational Database via Prisma Client
E. Redis (Cache & Pub/Sub)
F. Clients (e.g., Web Dashboard)

Interactions:
1. API Server <–> Database: uses Prisma client to read/write incidents, services, users.
2. API Server <–> Redis: caches lookup data (e.g., service statuses), optionally publishes notifications.
3. Monitors → fetch external service health → write incidents to DB → publish results on Redis channel.
4. WebSocket Broadcaster → subscribes to Redis channels → pushes updates to Clients over WS.
5. Clients ←→ HTTP API for CRUD & queries.
6. Clients ←→ WS for real-time status updates.

##### Architectural Patterns & Design Principles
- **Separation of concerns**: HTTP API, background jobs, and real-time broadcaster are distinct processes.
- **Pub/Sub pattern** via Redis for decoupling monitors from websocket broadcast logic.
- **Layered architecture**:
- Presentation layer (clients)
- API layer (FastAPI)
- Business logic & monitors
- Data access via Prisma + Redis
- **Configuration as Code**: `Procfile` and shell scripts define process orchestration for dev/prod parity.

##### Detailed Component Breakdown to Capture
- HTTP API routes (auth, incidents, services)
- Prisma client layer
- Redis utils (cache, pub/sub)
- Monitor modules: auto_incident_monitor, failure_counter_manager, latest_results, org_monitors
- WebSocket routers & broadcaster
- Shell scripts as orchestration layer (can be noted as “DevOps scripts”)
- Database schema (prisma/schema.prisma) and migrations

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Clients"
        Client["Clients\n(Web Dashboard, CLI)"]:::client
    end

    subgraph "Compute Processes"
        subgraph "API Server\nFastAPI + uvicorn (8000)"
            API["HTTP API Server"]:::compute
            subgraph "Auth Module"
                AuthRoutes["Auth Routes"]:::compute
            end
            subgraph "Incident Module"
                IncRoutes["Incident Routes"]:::compute
                IncModels["Incident Models"]:::compute
                IncServices["Incident Services"]:::compute
            end
            subgraph "Service Module"
                ServRoutes["Service Status Routes"]:::compute
                ServModels["Service Models"]:::compute
            end
            DBClient["Prisma Client"]:::compute
            RedisClient["Redis Utils"]:::compute
        end

        subgraph "Monitor Workers\nPython Monitors"
            MonAuto["Auto Incident Monitor"]:::compute
            MonFail["Failure Counter Manager"]:::compute
            MonLatest["Latest Results"]:::compute
            MonOrg["Org Monitors"]:::compute
        end

        subgraph "WebSocket Broadcaster\nWS Server (8001)"
            WSRouter["WS Incident Router"]:::compute
            MonUpdates["Monitor Updates Channel"]:::compute
            WSBroad["WS Broadcaster"]:::compute
        end
    end

    subgraph "Infrastructure"
        DB["PostgreSQL Database"]:::db
        Redis["Redis Cache & Pub/Sub"]:::db
    end

    subgraph "DevOps & Scripts"
        DevRun["dev_run.sh"]:::ops
        FullClear["full_clear.sh"]:::ops
        ProcfileNode["Procfile"]:::ops
        Seed["Seed Script"]:::ops
    end

    Client -->|HTTP| API
    Client -->|WebSocket| WSRouter

    API -->|reads/writes| DBClient
    API -->|caches/publishes| RedisClient
    DBClient -->|connects| DB
    RedisClient -->|connects| Redis

    MonAuto -->|writes incidents| DB
    MonFail -->|writes incidents| DB
    MonLatest -->|writes incidents| DB
    MonOrg -->|writes incidents| DB

    MonAuto -->|publishes| Redis
    MonFail -->|publishes| Redis
    MonLatest -->|publishes| Redis
    MonOrg -->|publishes| Redis

    Redis -->|subscribes| MonUpdates
    MonUpdates -->|pushes| WSBroad
    WSBroad -->|pushes updates| Client

    DevRun --> API
    DevRun --> MonAuto
    DevRun --> WSBroad
    FullClear --> Redis
    FullClear --> DB
    ProcfileNode --> DevRun
    ProcfileNode --> FullClear
    Seed --> DB

    click API "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/main.py"
    click AuthRoutes "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/auth/routes.py"
    click IncRoutes "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/incidents/routes.py"
    click IncModels "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/incidents/models.py"
    click IncServices "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/incidents/incident_services.py"
    click ServRoutes "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/services/routes.py"
    click ServModels "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/services/models.py"
    click DBClient "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/db.py"
    click DB "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/prisma/schema.prisma"
    click RedisClient "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/utils/redis_utils.py"
    click MonAuto "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/monitors/auto_incident_monitor.py"
    click MonFail "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/monitors/failure_counter_manager.py"
    click MonLatest "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/monitors/latest_results.py"
    click MonOrg "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/monitors/org_monitors.py"
    click WSRouter "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/websocket/incidents_ws_router.py"
    click MonUpdates "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/websocket/monitor_updates.py"
    click WSBroad "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/app/websocket/ws_broadcaster.py"
    click DevRun "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/scripts/dev_run.sh"
    click FullClear "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/scripts/full_clear.sh"
    click ProcfileNode "https://github.com/prabanjanjeyasankar/status-deck-server/tree/main/Procfile"
    click Seed "https://github.com/prabanjanjeyasankar/status-deck-server/blob/main/seed.py"

    classDef compute fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef db fill:#D1F2EB,stroke:#196F3D,color:#0B5345;
    classDef client fill:#FCF3CF,stroke:#A04000,color:#512E5F;
    classDef ops fill:#FADBD8,stroke:#922B21,color:#641E16;
```
