Skip to content

Backend Services Blueprint Services Blueprint Services

Jump to bottom
github-actions[bot] edited this page May 2, 2026 · 4 revisions

Blueprint Services

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document describes the Flask blueprint services architecture used in the Python backend. It explains how the application is organized into modular blueprints for distinct service domains: beats, chords, lyrics, audio, youtube, health, and docs. It covers routing patterns, request validation via dedicated validators modules, service integration, blueprint registration and URL prefixing strategy, and the separation of concerns that enables independent development and testing across domains.

Project Structure

The Flask application follows the application factory pattern and registers blueprints centrally. Blueprints are grouped under blueprints// with per-domain routes and validators. Services are initialized in the factory and attached to the Flask app for use in routes.

graph TB
A["Flask App Factory<br/>create_app()"] --> B["Register Blueprints<br/>register_blueprints()"]
B --> C["Health Blueprint<br/>/"]
B --> D["Docs Blueprint<br/>/docs/*"]
B --> E["Beats Blueprint<br/>/api/detect-beats*"]
B --> F["Chords Blueprint<br/>/api/recognize-chords*"]
B --> G["Lyrics Blueprint<br/>/api/genius-lyrics, /api/lrclib-lyrics"]
B --> H["Audio Blueprint<br/>validators only"]
B --> I["YouTube Blueprint<br/>validators only"]
A --> J["Init Services<br/>init_services()"]
J --> K["Beat Detection Service"]
J --> L["Chord Recognition Service"]
J --> M["Lyrics Orchestrator"]
Loading

Diagram sources

Section sources

Core Components

  • Application factory: Creates and configures the Flask app, initializes extensions, registers blueprints, and sets up a service container.
  • Blueprints: Modular route groups for each domain, each with its own routes and validators.
  • Validators: Centralized validation logic for each domain’s endpoints.
  • Services: Domain services injected into the app and used by routes (beat detection, chord recognition, lyrics orchestration).
  • Error handlers: Centralized JSON error responses and custom exception classes.

Section sources

Architecture Overview

The Flask app is created via an application factory that:

  • Applies compatibility patches
  • Loads configuration
  • Initializes extensions (CORS, rate limiting)
  • Registers blueprints
  • Initializes services and attaches them to app.extensions

Each blueprint defines its routes and uses validators to enforce request constraints. Routes call into services to perform domain-specific work and return structured JSON responses.

sequenceDiagram
participant Client as "Client"
participant App as "Flask App"
participant BP as "Blueprint Route"
participant Val as "Validators"
participant Svc as "Domain Service"
participant Ext as "Extensions"
Client->>App : HTTP Request
App->>BP : Route Dispatch
BP->>Val : validate_*_request()
Val-->>BP : Validation Result
alt Valid
BP->>Svc : Invoke service method
Svc-->>BP : Result
BP-->>Client : JSON Response
else Invalid
BP-->>Client : 400 JSON Error
end
App->>Ext : Rate limit, logging
Loading

Diagram sources

Detailed Component Analysis

Health Blueprint

  • Purpose: Basic health checks and root endpoint.
  • Routes:
    • GET /: Returns a simple health status.
    • GET /health: Cloud Run-friendly health check.
  • Registration: Always registered.
flowchart TD
Start(["Request to / or /health"]) --> CheckPath{"Path"}
CheckPath --> |"/"| Root["Return {status: healthy, message}"]
CheckPath --> |"/health"| Health["Return {status: healthy}"]
Loading

Diagram sources

Section sources

Beats Blueprint

  • Purpose: Beat detection, model availability tests, and model info.
  • Routes:
    • POST /api/detect-beats: Detect beats from uploaded file or path; supports detector selection and force override.
    • POST /api/detect-beats-firebase: Detect beats from Firebase Storage URL.
    • GET /api/model-info: Available detectors and defaults.
    • GET /api/test-beat-transformer, /api/test-madmom, /api/test-librosa, /api/test-all-models, /api/test-dbn-isolation: Model availability and diagnostics.
  • Validators:
    • validate_beat_detection_request(): Validates file or path, detector, force.
    • validate_firebase_beat_detection_request(): Validates Firebase URL and detector.
    • validate_file_size(): Enforces per-detector size limits unless force is true.
  • Service integration: Uses BeatDetectionService from app.extensions.
sequenceDiagram
participant C as "Client"
participant R as "detect-beats Route"
participant V as "Beats Validators"
participant S as "BeatDetectionService"
participant FS as "File System"
C->>R : POST /api/detect-beats
R->>V : validate_beat_detection_request()
V-->>R : {valid, params, file}
alt File Upload
R->>V : validate_file_size(file, detector, force)
V-->>R : {ok}
R->>FS : save temp file
FS-->>R : path
else Path
R->>FS : check exists(path)
FS-->>R : ok/fail
end
R->>S : detect_beats(file_path, detector, force)
S-->>R : result
R-->>C : JSON result
Loading

Diagram sources

Section sources

Chords Blueprint

  • Purpose: Chord recognition across multiple models and model info/testing.
  • Routes:
    • POST /api/recognize-chords: Recognize chords from file, path, or JSON audioUrl; supports detector selection, chord dictionaries, force, and Spleeter.
    • POST /api/recognize-chords-firebase: Recognize chords from Firebase URL.
    • GET /api/chord-model-info: Flask chord-model discovery with available chord models and defaults.
    • GET /api/test-chord-cnn-lstm, /api/test-btc-sl, /api/test-btc-pl, /api/test-all-chord-models: Model availability and diagnostics.
  • Validators:
    • validate_chord_recognition_request(): Validates inputs, detector, force, use_spleeter, chord_dict.
    • validate_firebase_chord_recognition_request(): Validates Firebase URL and detector.
    • validate_file_size(): Enforces per-detector size limits unless force is true.
    • normalize_audio_url_to_path(): Converts relative URLs to absolute paths.
  • Service integration: Uses ChordRecognitionService from app.extensions.
sequenceDiagram
participant C as "Client"
participant R as "recognize-chords Route"
participant V as "Chords Validators"
participant S as "ChordRecognitionService"
participant FS as "File System"
C->>R : POST /api/recognize-chords
R->>V : validate_chord_recognition_request()
V-->>R : {valid, params, file}
alt JSON audioUrl
R->>V : normalize_audio_url_to_path(url, AUDIO_DIR)
V-->>R : path
else File Upload
R->>V : validate_file_size(file, detector, force)
V-->>R : {ok}
R->>FS : save temp file
FS-->>R : path
else Path
R->>FS : check exists(path)
FS-->>R : ok/fail
end
R->>S : recognize_chords(file_path, detector, chord_dict, force, use_spleeter)
S-->>R : result
R-->>C : JSON result
Loading

Diagram sources

Section sources

Lyrics Blueprint

  • Purpose: Fetch lyrics from multiple providers (Genius, LRClib) with a unified interface.
  • Routes:
    • POST /api/genius-lyrics: Fetch lyrics from Genius.
    • POST /api/lrclib-lyrics: Fetch lyrics from LRClib.
  • Validators:
    • validate_lyrics_request(): Ensures JSON payload with either search_query or both artist and title; enforces length limits.
  • Service integration: Uses Lyrics Orchestrator from app.extensions.
sequenceDiagram
participant C as "Client"
participant R as "Genius/LRClib Route"
participant V as "Lyrics Validators"
participant O as "Lyrics Orchestrator"
C->>R : POST /api/genius-lyrics or /api/lrclib-lyrics
R->>V : validate_lyrics_request()
V-->>R : {valid, params}
R->>O : fetch_from_provider(artist,title,search_query)
O-->>R : result
R-->>C : JSON result
Loading

Diagram sources

Section sources

Audio Blueprint

  • Purpose: Provides validation utilities for audio extraction requests.
  • Validators:
    • validate_audio_extraction_request(): Validates videoId format, boolean flags, and optional parameters.
    • validate_video_id(), sanitize_video_id(), validate_timeout_parameter(), get_extraction_display_name(): Supporting validations and helpers.

Section sources

YouTube Blueprint

  • Purpose: Provides validation utilities for YouTube search requests.
  • Validators:
    • validate_youtube_search_request(): Validates query and maxResults; sanitizes query.
    • validate_search_query(), sanitize_search_query(), validate_max_results(), get_search_source_display_name(): Supporting validations and helpers.

Section sources

Docs Blueprint

  • Purpose: Documentation endpoints.
  • Registration: Registered alongside other blueprints.

Section sources

Dependency Analysis

  • Blueprint registration: Centralized in the factory; debug blueprint conditionally registered based on configuration.
  • Service container: Created once in the factory and stored in app.extensions for routes to access.
  • Validators: Pure functions invoked by routes; they depend on Flask request context and return structured tuples for route handling.
  • Error handling: Centralized error handlers provide consistent JSON responses and custom exception classes.
graph TB
AF["app_factory.py:create_app"] --> RB["register_blueprints"]
AF --> IS["init_services"]
RB --> HB["health_bp"]
RB --> CB["chords_bp"]
RB --> BB["beats_bp"]
RB --> LB["lyrics_bp"]
RB --> AB["audio_bp (validators)"]
RB --> YTB["youtube_bp (validators)"]
IS --> BDS["BeatDetectionService"]
IS --> CRS["ChordRecognitionService"]
IS --> LOS["Lyrics Orchestrator"]
Loading

Diagram sources

Section sources

Performance Considerations

  • Rate limiting: Each blueprint leverages Flask-Limiter via config.get_rate_limit to throttle endpoints by workload category (light, moderate, heavy, test, health).
  • File size validation: Prevents oversized uploads and selects appropriate detectors or forces overrides.
  • Temporary file handling: Routes use temporary files for uploads and ensure cleanup to avoid disk pressure.
  • Model availability checks: Tests endpoints provide visibility into model readiness and device info, aiding operational decisions.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • Validation failures: Validators return structured error messages; routes respond with 400 and JSON bodies indicating the issue.
  • File size errors: When uploads exceed limits, routes return 413 with guidance to adjust detector or force parameter.
  • Model unavailability: Test endpoints return 404 or detailed errors when models are missing or misconfigured.
  • Unexpected errors: Centralized handlers catch unhandled exceptions, log stack traces, and return 500 with optional traceback in non-production modes.
  • Custom exceptions: Use ModelUnavailableError, FileTooLargeError, AudioProcessingError, ExternalServiceError for domain-specific failures.

Section sources

Conclusion

The Flask blueprint services architecture cleanly separates concerns across domains (beats, chords, lyrics, audio, youtube, health, docs). Each blueprint encapsulates its routes and validation logic, integrates with a shared service container, and adheres to centralized error handling and rate limiting. This modularity enables independent development, testing, and deployment of service areas while maintaining consistent behavior and reliability.

ChordMiniApp Wiki

General

API Reference

Architecture and Design

Audio Processing and Analysis

Backend Services

Database and Storage

Deployment and Operations

Experimental Features

Frontend Application

Lyrics and Text Processing

Machine Learning Models

Project Overview

Visualization and User Interface

Clone this wiki locally