How prabanjanjeyasankar/status-deck-server works
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