# mminh007/machine-translation architecture

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

- Interactive diagram: https://gitdiagram.com/mminh007/machine-translation
- Repository: https://github.com/mminh007/machine-translation

## Overview

##### Project type and purpose
- This is a full-stack, real-time translation application.
- Frontend: Streamlit UI (Python) for capturing text/audio and displaying results.
- Backend: FastAPI service that exposes translation endpoints.
- Core functionality: on-the-fly translation (Vietnamese ↔ English) using Facebook’s MBart model, plus audio capture/recognition (Google SpeechRecognition API).
- Exposed publicly via ngrok tunnels for both API and UI.

##### File structure
- app.py (root)
– Orchestrates startup: launches backend (FastAPI), frontend (Streamlit), and ngrok tunnels.
- backend/
– main.py: FastAPI app, endpoint definitions (text and audio translation).
– schema/base.py: Pydantic models for request/response payloads.
– utils/model.py: loads the MBart model, performs inference.
- frontend/
– main.py: Streamlit script—defines UI controls (text inputs, microphone capture), calls backend endpoints.
- requirements.txt: lists dependencies (FastAPI, Streamlit, transformers, pyngrok, SpeechRecognition, etc.)

##### README for additional insights
- Two servers run concurrently: FastAPI (port 8000) and Streamlit (port 8501).
- Ngrok configured via a .env token—creates public URLs for both.
- Features: text translation API, audio recording in browser → backend OCR/recognition → translation.

##### Detail
- Startup orchestration: app.py → spawns both services and ngrok tunnels.
- Environment variables (.env → NGROK_TOKEN) feeding into PyNgrok initialization.
- Call out key ports: 8501 (frontend), 8000 (backend).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    subgraph "Client"
        Browser["Client Browser"]:::client
    end

    %% Local Host
    subgraph "Local Host"
        Orchestration["app.py"]:::orch
        subgraph "Ngrok Tunnels"
            NG_FE["Ngrok Tunnel\nFront-end"]:::ngrok
            NG_BE["Ngrok Tunnel\nBack-end"]:::ngrok
        end
        subgraph "Streamlit UI Service\n(port 8501)"
            FE["Streamlit Frontend"]:::frontend
        end
        subgraph "FastAPI Translation Service\n(port 8000)"
            BE["FastAPI Backend"]:::backend
            Schemas["Pydantic Schemas"]:::schema
            Model["Translation Engine\n(MBart)"]:::model
        end
        Docs["Project Docs\n(requirements.txt, README.md)"]:::docs
    end

    %% External
    subgraph "External Services"
        SpeechAPI["Google SpeechRecognition API"]:::external
    end

    %% Connections
    Browser -->|"HTTPS"| NG_FE
    NG_FE --> FE
    FE -->|"HTTP POST /translate_text"| BE
    FE -->|"HTTP POST /translate_audio"| BE
    BE -->|"uses schemas"| Schemas
    BE -->|"model.infer()"| Model
    BE -->|"calls SpeechRecognition"| SpeechAPI
    SpeechAPI -->|"transcribed text"| BE

    Orchestration --> FE
    Orchestration --> BE
    Orchestration --> NG_FE
    Orchestration --> NG_BE
    Orchestration --> Docs

    %% Click Events
    click Orchestration "https://github.com/mminh007/machine-translation/blob/main/app.py"
    click FE "https://github.com/mminh007/machine-translation/blob/main/frontend/main.py"
    click BE "https://github.com/mminh007/machine-translation/blob/main/backend/main.py"
    click Schemas "https://github.com/mminh007/machine-translation/blob/main/backend/schema/base.py"
    click Model "https://github.com/mminh007/machine-translation/blob/main/backend/utils/model.py"
    click Docs "https://github.com/mminh007/machine-translation/blob/main/requirements.txt"
    click Docs "https://github.com/mminh007/machine-translation/blob/main/README.md"

    %% Styles
    classDef client fill:#E3F2FD,stroke:#2196F3,color:#0D47A1,stroke-width:1px
    classDef frontend fill:#E8F5E9,stroke:#43A047,color:#1B5E20,stroke-width:1px
    classDef backend fill:#FFF3E0,stroke:#FB8C00,color:#E65100,stroke-width:1px
    classDef model fill:#F3E5F5,stroke:#8E24AA,color:#4A148C,stroke-width:1px
    classDef schema fill:#E1F5FE,stroke:#039BE5,color:#01579B,stroke-width:1px
    classDef external fill:#FFEBEE,stroke:#E53935,color:#B71C1C,stroke-width:1px
    classDef ngrok fill:#EDE7F6,stroke:#5E35B1,color:#311B92,stroke-width:1px
    classDef orch fill:#FFFDE7,stroke:#FBC02D,color:#F57F17,stroke-width:1px
    classDef docs fill:#ECEFF1,stroke:#546E7A,color:#37474F,stroke-width:1px
```
