# ccmarin14/tts-service architecture

> Architecture diagram of the GitHub repository ccmarin14/tts-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ccmarin14/tts-service
- Repository: https://github.com/ccmarin14/tts-service

## Overview

##### Project type and purpose
- This is a backend-only, full-stack Microservice/API (no UI) built on FastAPI.
- Purpose: Expose REST endpoints to convert text→speech via multiple online TTS providers, cache results, store metadata in MySQL, store audio files in AWS S3, and support zip-upload of sample audio files.

##### File structure
Top-level:
- app/: main application code
- controllers/: FastAPI endpoint handlers
- validators/: request validation logic
- services/:
- tts/: core TTS orchestration
- database/: MySQL operations
- storage/: local file & S3 operations
- zip_service: zip-upload processing
- container_service: service-locator bootstrap
- providers/: concrete TTS providers (PlayHT, Polly, Voicemaker) behind a base interface
- models/: Pydantic models for payloads & DB metadata
- utils/: YAML config loader
- static_files.py & resources/: for mounting temporary folders
- main.py: instantiates FastAPI, includes routers, middleware, static mounts
- config.yaml: deployment config
- .env.example: secret definitions
- Dockerfile + docker-compose.yml: container setup
- requirements.txt: Python deps

##### README insights
- Highlights a two-level cache of audio_hash→URL.
- Emphasizes Docker, AWS S3, MySQL, YAML config.

##### Detailed checklist
- API Layer: FastAPI (main.py + controllers)
- Validation: tts_validator
- Service Layer: container_service, tts_service, zip_service, db_service, file_service, s3_service
- Provider Layer: base_provider + playht_provider, polly_provider, voicemaker_provider
- Data stores: MySQL, in-memory cache
- External: AWS S3, TTS APIs
- Config: YAML loader, .env
- Deployment: Docker container, ports, environment variables

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Client"
        Client["Client"]
    end

    subgraph "App Container"
        Main["FastAPI App\n(main.py)"]:::internal
        Controller["TTS Controller\n(controllers)"]:::internal
        Validator["TTS Validator\n(validators)"]:::internal
        ContainerService["Container Service\n(services/container_service)"]:::internal
        TTSService["TTS Service\n(services/tts/tts_service)"]:::internal
        DBService["DB Service\n(services/database/db_service)"]:::internal
        FileService["File Service\n(services/storage/file_service)"]:::internal
        S3Service["S3 Service\n(services/storage/s3_service)"]:::internal
        ZipService["Zip Service\n(services/zip_service)"]:::internal
        BaseProvider["Base Provider\n(providers/base_provider)"]:::internal
        PlayHTProv["PlayHT Provider\n(providers/playht_provider)"]:::internal
        PollyProv["Amazon Polly Provider\n(providers/polly_provider)"]:::internal
        VoicemProv["Voicemaker Provider\n(providers/voicemaker_provider)"]:::internal
        Models["Pydantic Models\n(app/models)"]:::internal
        StaticFiles["Static Files Mount\n(static_files.py)"]:::internal
        YAMLLoader["YAML Config Loader\n(utils/yaml_loader.py)"]:::internal
    end

    subgraph "External Systems"
        MySQL[(MySQL Database)]:::storage
        S3Bucket[(AWS S3 Bucket)]:::external
        PlayHTAPI["Play.ht API"]:::external
        PollyAPI["Amazon Polly API"]:::external
        VoicemAPI["Voicemaker API"]:::external
    end

    Client -->|"POST /tts"| Main
    Main --> Controller
    Controller --> Validator
    Validator --> DBService
    DBService -->|"cache hit query"| MySQL
    DBService -->|cacheMiss| TTSService
    TTSService --> BaseProvider
    BaseProvider --> PlayHTProv
    BaseProvider --> PollyProv
    BaseProvider --> VoicemProv
    PlayHTProv -->|"generate audio"| PlayHTAPI
    PollyProv -->|"generate audio"| PollyAPI
    VoicemProv -->|"generate audio"| VoicemAPI
    BaseProvider --> FileService
    FileService --> S3Service
    S3Service -->|"upload"| S3Bucket
    S3Service --> DBService
    DBService -->|"store metadata"| MySQL
    DBService --> Controller
    Controller --> Client

    Controller -->|"POST /tts/zip"| ZipService
    ZipService --> FileService
    FileService --> S3Service
    S3Service --> DBService
    DBService --> MySQL

    Main --> ContainerService
    ContainerService --> YAMLLoader
    ContainerService --> Models
    Main --> StaticFiles

    %% Click events
    click Main "https://github.com/ccmarin14/tts-service/blob/main/app/main.py"
    click Controller "https://github.com/ccmarin14/tts-service/blob/main/app/controllers/tts_controller.py"
    click Validator "https://github.com/ccmarin14/tts-service/blob/main/app/validators/tts_validator.py"
    click TTSService "https://github.com/ccmarin14/tts-service/blob/main/app/services/tts/tts_service.py"
    click DBService "https://github.com/ccmarin14/tts-service/blob/main/app/services/database/db_service.py"
    click FileService "https://github.com/ccmarin14/tts-service/blob/main/app/services/storage/file_service.py"
    click S3Service "https://github.com/ccmarin14/tts-service/blob/main/app/services/storage/s3_service.py"
    click ZipService "https://github.com/ccmarin14/tts-service/blob/main/app/services/zip_service.py"
    click ContainerService "https://github.com/ccmarin14/tts-service/blob/main/app/services/container_service.py"
    click BaseProvider "https://github.com/ccmarin14/tts-service/blob/main/app/providers/base_provider.py"
    click PlayHTProv "https://github.com/ccmarin14/tts-service/blob/main/app/providers/playht_provider.py"
    click PollyProv "https://github.com/ccmarin14/tts-service/blob/main/app/providers/polly_provider.py"
    click VoicemProv "https://github.com/ccmarin14/tts-service/blob/main/app/providers/voicemaker_provider.py"
    click Models "https://github.com/ccmarin14/tts-service/blob/main/app/models/tts_model.py"
    click Models "https://github.com/ccmarin14/tts-service/blob/main/app/models/information_model.py"
    click StaticFiles "https://github.com/ccmarin14/tts-service/blob/main/app/static_files.py"
    click YAMLLoader "https://github.com/ccmarin14/tts-service/blob/main/app/utils/yaml_loader.py"

    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef external fill:#E6FFEA,stroke:#1C7430,color:#1C7430;
    classDef storage fill:#FFF4E5,stroke:#D97706,color:#D97706;
```
