# bounsic-a-s/tongi architecture

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

- Interactive diagram: https://gitdiagram.com/bounsic-a-s/tongi
- Repository: https://github.com/bounsic-a-s/tongi

## Overview

##### Project type and purpose
- Full-stack, cross-platform translation app
- Flutter-based UI (Android, iOS, Web, Linux, macOS, Windows)
- C++ REST API backend for orchestration
- Three Python microservices (STT, TTS, TTT) for specialized translation tasks

##### File structure
Top-level directories:
- frontend/ – Flutter app organized into core utilities, screens, services, widgets; platform folders for Android, iOS, Web, Linux, macOS, Windows; pubspec.yaml; tests
- backend/ – C++ server: main.cpp entrypoint; controllers (health, data, stt, tts, ttt); services; models; utils; CMakeLists.txt; Dockerfiles; config.json; test scripts
- servers/ – Python Flask microservices: stt_server, tts_server, ttt_server; each with app.py, controllers, services, models, Dockerfile, Jenkinsfile, tests
- scripts (servers/run_*.bat) to launch all or individual services

##### Extract architecture insights from the README
- Tech stack: Flutter/Dart, C++ (Pistache or similar REST engine), Python/Flask, Docker, CMake, Jenkins
- Features: audio translation, text translation, camera OCR translation, multi-language support, settings
- Backend orchestrates calls to microservices

##### Main components & interactions
a. Client Layer (Flutter Frontend)
– UI screens call translation endpoints: audio, text, camera
– Uses logic controllers and services for recording, OCR, API calls
b. Backend Layer (C++ REST API)
– Exposes REST endpoints: /health, /data, /stt, /tts, /ttt
– Internally structured as Controllers → Services → Models
– Reads config.json for service URLs, API keys
c. Microservices Layer (Python Flask)
– STT Service: speech-to-text
– TTS Service: text-to-speech (uses Azure voices config)
– TTT Service: text-to-text translation
d. Infrastructure & CI/CD
– Docker containers for backend and each microservice
– Docker-Compose to orchestrate local dev
– Jenkinsfiles for CI pipelines

##### Data flow relationships
- User interacts with Flutter UI → HTTP(S) request to C++ REST API
- C++ Controller routes request to appropriate Service
- C++ Service issues HTTP call to corresponding Python microservice
- Microservice processes input, returns JSON payload
- C++ Service may post-process, then returns unified response to Flutter

##### Architectural patterns & principles
- Separation of concerns: UI / orchestration / specialized processing
- Layered C++ backend (Controller-Service-Model)
- Microservices for independently scaling translation tasks
- Containerization for reproducible environments
- Cross-platform client via Flutter

1. Client (Flutter app on multiple platforms)
2. Backend (C++ REST API)
3. Microservices (STT, TTS, TTT)
4. Infrastructure (Docker, Jenkins, Docker-Compose)
- Flutter → C++ API
- C++ API → each Python microservice
- Microservice → C++ API → Flutter
- Client: blue
- Backend: green
- Microservices: orange
- Infra/CI: gray

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        FlutterApp["Flutter Frontend"]:::client
        UIScreens["UI Screens"]:::client
        UIWidgets["UI Widgets"]:::client
        LogicControllers["Logic Controllers"]:::client
        LogicServices["Logic Services"]:::client
        CoreUtils["Core Utilities & Constants"]:::client
        EntryPoint["main.dart"]:::client
        Platforms["Platform Folders"]:::client
        Android["Android"]:::client
        iOS["iOS"]:::client
        Web["Web"]:::client
        Linux["Linux"]:::client
        macOS["macOS"]:::client
        Windows["Windows"]:::client

        FlutterApp --> UIScreens
        FlutterApp --> UIWidgets
        FlutterApp --> LogicControllers
        FlutterApp --> LogicServices
        FlutterApp --> CoreUtils
        FlutterApp --> EntryPoint
        FlutterApp --> Platforms
        Platforms --> Android
        Platforms --> iOS
        Platforms --> Web
        Platforms --> Linux
        Platforms --> macOS
        Platforms --> Windows
    end

    %% Backend Layer
    subgraph "Backend Layer" 
        direction TB
        API["C++ REST API"]:::backend
        EntryCPP["main.cpp"]:::backend
        Controllers["Controllers"]:::backend
        HealthCtrl["Health Controller"]:::backend
        DataCtrl["Data Controller"]:::backend
        STTCtrl["STT Controller"]:::backend
        TTSCtrl["TTS Controller"]:::backend
        TTTCtrl["TTT Controller"]:::backend
        Services["Services"]:::backend
        DataSvc["Data Service"]:::backend
        STTSvc["STT Service"]:::backend
        TTSSvc["TTS Service"]:::backend
        TTTSvc["TTT Service"]:::backend
        Models["Models"]:::backend
        ServerSetup["Server Setup"]:::backend
        Utils["Utilities"]:::backend
        Config["config.json"]:::backend
        BuildCMake["CMakeLists.txt"]:::backend
        DockerFiles["Docker & Compose"]:::backend
        JenkinsBackend["Jenkinsfile"]:::backend

        API --> EntryCPP
        API --> Controllers
        Controllers --> HealthCtrl
        Controllers --> DataCtrl
        Controllers --> STTCtrl
        Controllers --> TTSCtrl
        Controllers --> TTTCtrl
        API --> Services
        Services --> DataSvc
        Services --> STTSvc
        Services --> TTSSvc
        Services --> TTTSvc
        API --> Models
        API --> ServerSetup
        API --> Utils
        API --> Config
        API --> BuildCMake
        API --> DockerFiles
        API --> JenkinsBackend
    end

    %% Microservices Layer
    subgraph "Microservices Layer" 
        direction TB
        STT["STT Service"]:::micro
        TTS["TTS Service"]:::micro
        TTT["TTT Service"]:::micro
    end

    %% Infrastructure & CI/CD
    subgraph "Infrastructure & CI/CD" 
        direction TB
        DockerCompose["Docker-Compose"]:::infra
        RunAll["run_all_docker.bat"]:::infra
        JenkinsInfra["Jenkins Pipelines"]:::infra
        Scripts["Service Launch Scripts"]:::infra
    end

    %% Data Flow
    FlutterApp -->|"HTTP/JSON"| API
    API -->|"HTTP/JSON"| STT
    API -->|"HTTP/JSON"| TTS
    API -->|"HTTP/JSON"| TTT
    STT -->|"response JSON"| API
    TTS -->|"response JSON"| API
    TTT -->|"response JSON"| API
    API -->|"HTTP/JSON"| FlutterApp

    %% Infra Connections
    DockerCompose --> API
    DockerCompose --> STT
    DockerCompose --> TTS
    DockerCompose --> TTT
    RunAll --> DockerCompose
    Scripts --> STT
    Scripts --> TTS
    Scripts --> TTT
    JenkinsInfra --> API
    JenkinsInfra --> STT
    JenkinsInfra --> TTS
    JenkinsInfra --> TTT

    %% Click Events
    click FlutterApp "https://github.com/bounsic-a-s/tongi/tree/main/frontend/"
    click UIScreens "https://github.com/bounsic-a-s/tongi/tree/main/frontend/lib/ui/screens/"
    click UIWidgets "https://github.com/bounsic-a-s/tongi/tree/main/frontend/lib/ui/widgets/"
    click LogicControllers "https://github.com/bounsic-a-s/tongi/tree/main/frontend/lib/logic/controllers/"
    click LogicServices "https://github.com/bounsic-a-s/tongi/tree/main/frontend/lib/logic/services/"
    click CoreUtils "https://github.com/bounsic-a-s/tongi/tree/main/frontend/lib/ui/core/"
    click CoreUtils "https://github.com/bounsic-a-s/tongi/tree/main/frontend/lib/logic/utils/"
    click EntryPoint "https://github.com/bounsic-a-s/tongi/blob/main/frontend/lib/main.dart"
    click Android "https://github.com/bounsic-a-s/tongi/tree/main/frontend/android/"
    click iOS "https://github.com/bounsic-a-s/tongi/tree/main/frontend/ios/"
    click Web "https://github.com/bounsic-a-s/tongi/tree/main/frontend/web/"
    click Linux "https://github.com/bounsic-a-s/tongi/tree/main/frontend/linux/"
    click macOS "https://github.com/bounsic-a-s/tongi/tree/main/frontend/macos/"
    click Windows "https://github.com/bounsic-a-s/tongi/tree/main/frontend/windows/"
    click API "https://github.com/bounsic-a-s/tongi/tree/main/backend/"
    click EntryCPP "https://github.com/bounsic-a-s/tongi/blob/main/backend/main.cpp"
    click HealthCtrl "https://github.com/bounsic-a-s/tongi/blob/main/backend/controllers/health/health_controller.cpp"
    click DataCtrl "https://github.com/bounsic-a-s/tongi/blob/main/backend/controllers/data/data_controller.cpp"
    click STTCtrl "https://github.com/bounsic-a-s/tongi/blob/main/backend/controllers/stt/stt_controller.cpp"
    click TTSCtrl "https://github.com/bounsic-a-s/tongi/blob/main/backend/controllers/tts/tts_controller.cpp"
    click TTTCtrl "https://github.com/bounsic-a-s/tongi/blob/main/backend/controllers/ttt/ttt_controller.cpp"
    click DataSvc "https://github.com/bounsic-a-s/tongi/blob/main/backend/services/data/data_service.cpp"
    click STTSvc "https://github.com/bounsic-a-s/tongi/blob/main/backend/services/stt/stt_service.cpp"
    click TTSSvc "https://github.com/bounsic-a-s/tongi/blob/main/backend/services/tts/tts_service.cpp"
    click TTTSvc "https://github.com/bounsic-a-s/tongi/blob/main/backend/services/ttt/ttt_service.cpp"
    click Models "https://github.com/bounsic-a-s/tongi/tree/main/backend/models/"
    click ServerSetup "https://github.com/bounsic-a-s/tongi/blob/main/backend/server/server.cpp"
    click Utils "https://github.com/bounsic-a-s/tongi/blob/main/backend/utils/json_utils.h"
    click Config "https://github.com/bounsic-a-s/tongi/blob/main/backend/config.json"
    click BuildCMake "https://github.com/bounsic-a-s/tongi/blob/main/backend/CMakeLists.txt"
    click DockerFiles "https://github.com/bounsic-a-s/tongi/blob/main/backend/docker-compose.yml"
    click JenkinsBackend "https://github.com/bounsic-a-s/tongi/tree/main/backend/Jenkinsfile"
    click STT "https://github.com/bounsic-a-s/tongi/blob/main/servers/stt_server/app.py"
    click TTS "https://github.com/bounsic-a-s/tongi/blob/main/servers/tts_server/app.py"
    click TTT "https://github.com/bounsic-a-s/tongi/blob/main/servers/ttt_server/app.py"
    click DockerCompose "https://github.com/bounsic-a-s/tongi/blob/main/backend/docker-compose.yml"
    click RunAll "https://github.com/bounsic-a-s/tongi/blob/main/servers/run_all.bat"
    click Scripts "https://github.com/bounsic-a-s/tongi/blob/main/servers/run_stt.bat"
    click JenkinsInfra "https://github.com/bounsic-a-s/tongi/tree/main/servers/stt_server/Jenkinsfile"

    %% Styles
    classDef client fill:#AED6F1,stroke:#21618C,stroke-width:1px
    classDef backend fill:#A9DFBF,stroke:#1D8348,stroke-width:1px
    classDef micro fill:#F5CBA7,stroke:#B9770E,stroke-width:1px
    classDef infra fill:#D5D8DC,stroke:#566573,stroke-width:1px
```
