# mechamogeo/spectra architecture

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

- Interactive diagram: https://gitdiagram.com/mechamogeo/spectra
- Repository: https://github.com/mechamogeo/spectra

## Overview

##### Project type and purpose
- SPECTRA is a backend-only, RESTful API service for speech analysis (no web UI).
- It ingests audio files, extracts speech features, runs classification (read vs. spontaneous), then post-processes results (readability score + natural language explanation).

##### File structure
- Top level
- src/core/app.py → FastAPI entry point (API layer)
- src/core/dtos/ → Data Transfer Objects between layers
- src/use_cases/ → Business logic (“use case” layer)
- resources/audios/ → Static storage location for input audio
- Key patterns
- Clean Architecture: Layers are strictly separated (API → DTOs → Use Cases → External services)
- No databases—state is transient, files live on disk.

##### Extract additional insights from the README
- Architecture subsection already calls out “clean architecture.”
- External dependencies: FastAPI (HTTP), Parselmouth (speech-feature extraction), Faster-Whisper (ASR), FFmpeg (format conversion), Ollama via LangChain (LLM explanations), NumPy.
- Input/Output: Client → HTTP GET /analyze?file_name=… → JSON response.

##### Components and relationships
a. Main components
- Client (e.g., curl, Postman, or another service)
- API Layer (FastAPI in src/core/app.py)
- DTO Layer (src/core/dtos)
- Use-Case Services
– AudioContextAnalyzer
– SpeechClassifier
- External/Infrastructure Services
– FFmpeg (audio conversion)
– Parselmouth (feature extraction)
– Faster-Whisper (speech-to-text)
– Ollama LLM via LangChain (natural language explanation)
- Storage
– Local file storage (resources/audios/)
b. Relationships and data flows
1. Client → HTTP request → FastAPI (API Layer)
2. API Layer validates request → builds request DTO → passes to Use-Case Services
3. Use-Case Services orchestrate:
- Load audio from resources/audios/
- Call FFmpeg if format needs conversion → pass standardized audio blob
- Invoke Parselmouth to compute speech features (word length, pauses, rate)
- Invoke Faster-Whisper for transcription (if needed by classification)
- Combine features into readability score
- Call Ollama LLM via LangChain to generate human-readable explanation
4. Use-Case returns response DTO → API Layer serializes to JSON → HTTP response → Client
c. Architectural patterns and principles
- Clean / Hexagonal Architecture:
– Strict layering—outer layers depend on abstractions in inner layers only
- Single Responsibility Principle: each use-case class does one thing
- Dependency Injection: services take interfaces/DTOs rather than concrete objects
d. Key technologies/frameworks
- FastAPI for HTTP interface
- Parselmouth & NumPy for DSP / feature stats
- Faster-Whisper for speech recognition
- FFmpeg for format conversion
- LangChain + Ollama for LLM-based explanations

##### Essential details to capture
- Component names (exact folder/module names)
- Data contract names (DTO classes like AnalysisDTO, TranscriptionDTO)
- Sequence of calls through layers and external services
- Protocols (HTTP, local file I/O, library calls)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client
    Client["Client"]:::external

    %% Core Layers
    subgraph "Core Layers"
        %% API Layer
        subgraph "API Layer"
            API["FastAPI\n(src/core/app.py)"]:::api
        end

        %% DTO Layer
        subgraph "DTO Layer"
            ADTO["AnalysisDTO\n(src/core/dtos/analysis_dtos.py)"]:::dto
            SDTO["StepsDTO\n(src/core/dtos/steps_dtos.py)"]:::dto
            TDTO["TranscriptionDTO\n(src/core/dtos/transcriptions_dtos.py)"]:::dto
        end

        %% Use-Case Layer
        subgraph "Use-Case Layer"
            ACA["AudioContextAnalyzer\n(src/use_cases/audio_context_analyser.py)"]:::usecase
            SC["SpeechClassifier\n(src/use_cases/speech_classifier.py)"]:::usecase
        end
    end

    %% Infrastructure Services
    subgraph "Infrastructure Services"
        FFMPEG["/FFmpeg/"]:::infra
        PARS["/Parselmouth/"]:::infra
        WHISPER["/Faster-Whisper/"]:::infra
        OLLAMA["/Ollama via LangChain/"]:::infra
    end

    %% Storage
    Storage["Audio Files\n(resources/audios/)"]:::storage

    %% Data Flows
    Client -->|"HTTP GET /analyze"| API
    API -->|"build AnalysisDTO"| ADTO
    ADTO -->|"pass DTO"| ACA
    ACA -->|"load audio"| Storage
    ACA -->|"convert audio"| FFMPEG
    ACA -->|"extract features"| PARS
    ACA -->|"transcription"| WHISPER
    ACA -->|"classify speech"| SC
    SC -->|"classification result"| ACA
    ACA -->|"generate explanation"| OLLAMA
    ACA -->|"build TranscriptionDTO\n& StepsDTO"| TDTO
    ACA -->|"build StepsDTO"| SDTO
    SDTO -->|"response DTO"| API
    TDTO -->|"response DTO"| API
    API -->|"JSON response"| Client

    %% Legend
    subgraph "Legend"
        L1["Rectangle: Core Layers (Blue)"]:::api
        L2["Parallelogram: Infrastructure (Green)"]:::infra
        L3["Cylinder: Storage (Yellow)"]:::storage
        L4["Rectangle: External Client (Red)"]:::external
    end

    %% Click events
    click API "https://github.com/mechamogeo/spectra/blob/main/src/core/app.py"
    click ADTO "https://github.com/mechamogeo/spectra/blob/main/src/core/dtos/analysis_dtos.py"
    click SDTO "https://github.com/mechamogeo/spectra/blob/main/src/core/dtos/steps_dtos.py"
    click TDTO "https://github.com/mechamogeo/spectra/blob/main/src/core/dtos/transcriptions_dtos.py"
    click ACA "https://github.com/mechamogeo/spectra/blob/main/src/use_cases/audio_context_analyser.py"
    click SC "https://github.com/mechamogeo/spectra/blob/main/src/use_cases/speech_classifier.py"
    click Storage "https://github.com/mechamogeo/spectra/tree/main/resources/audios/"

    %% Styles
    classDef api fill:#D6EAF8,stroke:#21618C,color:#1B4F72;
    classDef dto fill:#EBF5FB,stroke:#2E86C1,color:#1B4F72;
    classDef usecase fill:#D4EFDF,stroke:#239B56,color:#1D8348;
    classDef infra fill:#D5F5E3,stroke:#28B463,color:#1D8348,shape:rhombus;
    classDef storage fill:#FCF3CF,stroke:#B7950B,color:#7D6608,shape:cylinder;
    classDef external fill:#FADBD8,stroke:#C0392B,color:#78281F;
```
