# lordthiouk/sodav-monitor architecture

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

- Interactive diagram: https://gitdiagram.com/lordthiouk/sodav-monitor
- Repository: https://github.com/lordthiouk/sodav-monitor

## Overview

##### Project Type & Purpose
- The project is a full-stack application designed for monitoring radio/TV broadcasts in Senegal. Its core functionality is to capture audio streams, process them via advanced audio recognition algorithms, and provide real-time monitoring and analytics of music playbacks.
- The README clearly defines components like audio processing, music recognition (via local matching, MusicBrainz, and AudD), database operations, API endpoints, and a React-based frontend showing real-time dashboards and reports.

##### File Structure
- Two main directories – "backend" and "frontend" – indicate distinct separation of concerns.
- The backend directory includes numerous Python modules (e.g., main.py, routers, models, migrations, utilities) for API endpoints, audio processing, and database interactions. It also contains migration scripts and tests which hint at robust data management.
- The frontend directory contains React/TypeScript source files, components, services, and configuration files, which suggests a modern UI designed for real-time monitoring.
- Additionally, Docker-related files (Dockerfile, .dockerignore, nginx configuration) and deployment scripts (Procfile, railway.toml) support containerized and cloud deployments.

##### Main Components
a. Backend Components:
- API Gateway & Routers: Represented by the routers directory (analytics, channels, detections, reports) and the main FastAPI entry point.
- Business Logic & Audio Processing: Modules like music_recognition.py and audio_processor.py.
- Database Layer: Files such as database.py, init_db.py, and SQL schema scripts hint at a relational database (SQLite used in development, PostgreSQL mentioned in deployment).
- Migrations & ORM: Alembic/migrations files that manage schema changes.
- Utility Services: Logging, authentication, radio fetching, and caching components.

b. Frontend Components:
- UI Elements: React components (e.g., Navbar, Dashboard, LiveMonitor) and pages.
- Service Layer: Modules for API communication, WebSocket handling for real-time updates, and radio API integration.
- Styling/Theming: Use of themes and configuration files.

c. Integration & External Services:
- External APIs: MusicBrainz API and AudD for enriched metadata.
- Streaming & Audio Capture: Modules that handle 15-second segment capture from radio/TV streams.
- WebSocket: Used for real-time updates and notifications.

d. Database:
- Tables for radio_stations, tracks, and track_detections along with indexing and caching features.

##### Relationships and Data Flow
- Inputs: The audio streams from radio/TV sources feed into the backend’s audio processing components.
- Processing: The audio_processor module preprocesses data, then passes it to music_recognition which computes various metrics (spectral centroid, RMS, etc.) and determines the music score.
- Decision Flow: The recognition algorithm first performs a local database lookup and then cascades to external APIs (MusicBrainz, AudD) if necessary.
- Data Storage: Results of detections, metadata, and statistics are stored in the database.
- API Layer: Provides REST endpoints for channel management, detections, and analytics, which the frontend consumes.
- Real-Time Communications: WebSocket services update the frontend dashboard with live events.

##### Architectural Patterns & Design Principles
- Modular Design: Clear separation between UI (frontend) and business/data logic (backend).
- Layered Architecture: Distinct layers for routing/API handling, core processing (business logic), and persistence.
- Microservice Tendencies: While it functions as a monolith, it has clear boundaries (routers, audio processing, analytics) that could be decoupled into microservices, if needed.
- Use of Modern Frameworks: FastAPI for the backend and React/TypeScript for the frontend.
- Database Migrations & ORMs: Managed by Alembic suggesting version-controlled schema evolution.

##### Final Detailed Elements Checklist
- Clear labels for each component (Backend API, Audio Processor, Music Recognition, Database, Frontend Dashboard, WebSocket, External APIs).
- Audio flow from ingestion to processing.
- Data outcomes flowing to the database.
- Interaction between frontend and backend (API calls and WebSocket messages).

## Diagram (Mermaid)

```mermaid
graph TD
  %% Input Layer
  subgraph "Audio Input"
    A["Audio Capture (Radio/TV Streams)"]
  end

  %% Backend Layer
  subgraph "Backend Layer"
    D["API Gateway & Routers"]:::backend
    B["Audio Processor"]:::backend
    C["Music Recognition Module"]:::backend
    DM["Detect Music"]:::backend
    FP["Fingerprint"]:::backend
    E["Database Layer"]:::database
    IDB["Init DB"]:::database
    MDS["Models"]:::database
    F["Migrations & ORM"]:::backend
    MS["Migration Scripts"]:::backend
    G["Utility Services"]:::backend
    MWS["Backend WebSocket Service"]:::backend
    H["External API Integrations (MusicBrainz, AudD)"]:::external
  end

  %% Frontend Layer
  subgraph "Frontend Layer"
    I["Frontend UI Components"]:::frontend
    J["Frontend Service Layer"]:::frontend
    K["Frontend Styling/Theming"]:::frontend
    FWS["Frontend WebSocket Client"]:::frontend
  end
  
  %% Data Flow Connections
  A -->|"streamData"| B
  B -->|"preprocessedAudio"| C
  C -->|"includes"| DM
  C -->|"includes"| FP
  C -->|"localLookup"| E
  C -->|"fallback"| H
  E -->|"init"| IDB
  E -->|"models"| MDS
  F -->|"applyMigrations"| E
  F -->|"scripts"| MS
  D -->|"storeData"| E
  J -->|"APIRequest"| D
  D -->|"RESTResponse"| I
  G --> MWS
  MWS -->|"wsUpdates"| FWS
  I -->|"consumeWS"| FWS

  %% Styling Classes
  classDef backend fill:#ADD8E6,stroke:#000,stroke-width:2px;
  classDef frontend fill:#90EE90,stroke:#000,stroke-width:2px;
  classDef database fill:#FFC107,stroke:#000,stroke-width:2px;
  classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;

  %% Click Events - Backend Components
  click D "https://github.com/lordthiouk/sodav-monitor/tree/master/backend/routers"
  click B "https://github.com/lordthiouk/sodav-monitor/blob/master/backend/audio_processor.py"
  click C "https://github.com/lordthiouk/sodav-monitor/blob/master/backend/music_recognition.py"
  click DM "https://github.com/lordthiouk/sodav-monitor/blob/master/backend/detect_music.py"
  click FP "https://github.com/lordthiouk/sodav-monitor/blob/master/backend/fingerprint.py"
  click E "https://github.com/lordthiouk/sodav-monitor/blob/master/backend/database.py"
  click IDB "https://github.com/lordthiouk/sodav-monitor/blob/master/backend/init_db.py"
  click MDS "https://github.com/lordthiouk/sodav-monitor/blob/master/backend/models.py"
  click F "https://github.com/lordthiouk/sodav-monitor/tree/master/backend/alembic"
  click MS "https://github.com/lordthiouk/sodav-monitor/tree/master/backend/migrations"
  click G "https://github.com/lordthiouk/sodav-monitor/tree/master/backend/utils"
  click MWS "https://github.com/lordthiouk/sodav-monitor/blob/master/backend/utils/websocket.py"

  %% Click Events - Frontend Components
  click I "https://github.com/lordthiouk/sodav-monitor/tree/master/frontend/src/components"
  click J "https://github.com/lordthiouk/sodav-monitor/tree/master/frontend/src/services"
  click K "https://github.com/lordthiouk/sodav-monitor/tree/master/frontend/src/theme"
  click FWS "https://github.com/lordthiouk/sodav-monitor/blob/master/frontend/src/services/websocket.ts"
```
