How lordthiouk/sodav-monitor works
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).