# wsn22/speakbuddy architecture

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

- Interactive diagram: https://gitdiagram.com/wsn22/speakbuddy
- Repository: https://github.com/wsn22/speakbuddy

## Overview

##### Main components
- API/Web Layer (Controller): Represented by the controller packages under “api/src/main/java/com/speakbuddy/api/controller/v1/”. There are separate controllers for user management and audio/phrase processing.
- Service Layer: This contains business logic. For example, the “service/audio/phrase” and “service/user” packages show that each functionality (audio processing and user handling) is encapsulated in dedicated services.
- Database Access Layer: Found in the “database” package that includes managers, repositories (e.g., PhraseManager, UserManager, and their corresponding Repository classes), and entity definitions. This package shows how the system interacts with PostgreSQL.
- Audio Processing Utilities: Under “utility” and “utility/audio_processor” there are components like AudioProcessor, AiffConverter, and WavConverter, which handle file conversion and processing.
- Exception and Configuration Handling: There is a ControllerAdvisor and several custom Exception classes that manage error flows.
- Deployment Infrastructure: The Dockerfile and docker-compose.yml indicate that the system is containerized. Docker Compose configures both the API app and the PostgreSQL database, exposing necessary ports and connection information.

##### Relationships and interactions
- Client (or external system)   →   API Controllers: Incoming HTTP requests (including file uploads and user creation) are handled by the appropriate controller (e.g., UserController, PhraseController).
- Controllers   →   Service Layer: The controllers delegate tasks to services (like UserService and PhraseService) which implement business logic.
- Service Layer   →   Repository/Manager: Services work with Database Managers and/or Repositories to fetch, persist, or update data in the PostgreSQL database.
- Audio Processing Flow: When audio files are received, a utility component (such as AudioProcessor) calls specific converters (AiffConverter, WavConverter) to process incoming or outgoing audio files.
- Exception Handling: Exceptions thrown in any layer are intercepted by the ControllerAdvisor, which formats error messages (using classes like ErrorMessage).
- Deployment: The Docker compose configuration ensures that the API server and the PostgreSQL database are deployed together and can interact seamlessly.

##### Important architectural patterns/design principles
- Layered Architecture: Each layer is neatly separated (controller, service, data access, and utility).
- Modular Design: Different functionalities such as audio processing, user management, and database management are split into dedicated modules or packages.
- Exception Handling: Global exception management is provided through ControllerAdvisor.
- Containerization: The use of Docker & Docker Compose isolates the environment and simplifies deployment.
- Testability: Tests are split by feature (controllers, services, utilities) that indicate emphasis on integration and unit testing.

##### Relevant technologies/frameworks
- Java 21, Spring Boot (implied by structure and Gradle bootJar), and Gradle as the build tool.
- PostgreSQL as the database.
- Docker and Docker Compose for deployment.
- Audio processing libraries (likely custom-built converters for aiff and wav) and possibly file utilities that manage local file processing.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Entities
    Client["Client/External System"]:::external

    %% API/Web Layer
    subgraph "API/Web Layer"
        UC["UserController"]:::controller
        PC["PhraseController"]:::controller
    end

    %% Service Layer
    subgraph "Service Layer"
        US["UserService"]:::service
        PS["PhraseService"]:::service
        BPS["BasePhraseService"]:::service
    end

    %% Database Access Layer
    subgraph "Database Layer"
        UM["UserManager"]:::database
        PM["PhraseManager"]:::database
        UR["UserRepository"]:::database
        PR["PhraseRepository"]:::database
        UE["UserEntity"]:::database
        PE["PhraseEntity"]:::database
    end

    %% Audio Processing Utilities
    subgraph "Audio Processing Utilities"
        AP["AudioProcessor"]:::utility
        AC["AiffConverter"]:::utility
        WC["WavConverter"]:::utility
        LFP["LocalFileProcessor"]:::utility
    end

    %% Exception & Configuration
    subgraph "Exception & Configuration"
        CA["ControllerAdvisor"]:::exception
        EM["ErrorMessage"]:::exception
    end

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        APICont["API Container"]:::deployment
        PSQL["PostgreSQL Container"]:::deployment
        DF["Dockerfile"]:::deployment
        DC["docker-compose.yml"]:::deployment
    end

    %% Relationships and Interactions
    Client -->|"HTTPRequest"| UC
    Client -->|"HTTPRequest"| PC

    UC -->|"delegates"| US
    PC -->|"delegates"| PS

    PS -->|"calls"| BPS

    US -->|"calls"| UM
    PS -->|"calls"| PM

    UM -->|"DBQuery"| UR
    PM -->|"DBQuery"| PR

    UR -->|"assoc"| UE
    PR -->|"assoc"| PE

    PS -->|"triggerAudioConversion"| AP
    AP -->|"calls"| AC
    AP -->|"calls"| WC
    AP -->|"calls"| LFP

    %% Exception Handling (dotted arrows)
    UC -.->|"errorHandling"| CA
    PC -.->|"errorHandling"| CA
    US -.->|"errorHandling"| CA
    PS -.->|"errorHandling"| CA

    %% Deployment Connection
    APICont -->|"DBConnection"| PSQL

    %% Click Events for Components
    click UC "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/controller/v1/routes/user/UserController.java"
    click PC "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/controller/v1/routes/audio/phrase/PhraseController.java"
    click US "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/service/user/UserService.java"
    click PS "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/service/audio/phrase/PhraseService.java"
    click BPS "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/service/audio/phrase/BasePhraseService.java"
    click UM "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/database/manager/UserManager.java"
    click PM "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/database/manager/PhraseManager.java"
    click UR "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/database/repository/UserRepository.java"
    click PR "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/database/repository/PhraseRepository.java"
    click UE "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/database/repository/entity/UserEntity.java"
    click PE "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/database/repository/entity/PhraseEntity.java"
    click AP "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/utility/AudioProcessor.java"
    click AC "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/utility/audio_processor/AiffConverter.java"
    click WC "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/utility/audio_processor/WavConverter.java"
    click LFP "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/utility/impl/LocalFileProcessor.java"
    click CA "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/configuration/controller/ControllerAdvisor.java"
    click EM "https://github.com/wsn22/speakbuddy/blob/master/api/src/main/java/com/speakbuddy/api/configuration/controller/ErrorMessage.java"
    click DF "https://github.com/wsn22/speakbuddy/tree/master/Dockerfile"
    click DC "https://github.com/wsn22/speakbuddy/blob/master/docker-compose.yml"

    %% Styles
    classDef external fill:#F5F5F5,stroke:#333,stroke-width:2px;
    classDef controller fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef service fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef database fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef utility fill:#D8BFD8,stroke:#333,stroke-width:2px;
    classDef exception fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef deployment fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
