# xxnuo/mtranserver architecture

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

- Interactive diagram: https://gitdiagram.com/xxnuo/mtranserver
- Repository: https://github.com/xxnuo/mtranserver

## Overview

##### Project type and purpose
- This is a full-stack, offline‐first translation server written in Go, with a companion React/TypeScript Web UI.
- It exposes a CLI, a REST API (with both generic translate endpoints and plugin-compatible endpoints), and an optional Web UI. It downloads and manages local translation models, serves translation requests at ~50 ms, and requires no GPU.

##### File structure
- Top-level code:
- cmd/mtranserver/main.go: entrypoint for the CLI/HTTP server
- bin/: command-line helpers (hash/update generators)
- internal/: core Go packages
– config: app configuration and environment
– logger: logging initialization
– server: HTTP server setup and routing
– handlers: HTTP handler functions for /translate, /languages, plugin APIs, health/version
– middleware: auth, CORS, request logging
– manager: worker pool, model-loading daemon, client API
– downloader: fetching models from remote sources
– services: translation engine wrapper, language detection
– models: domain models (records, cached data)
– utils: common utilities (file, port, version)
- data/: sample data, JSON record store
- ui/: React/TypeScript Web UI (Vite)
- docs/: static documentation site
- Dockerfile, compose.yml, GitHub workflows: CI/CD and containerization

##### README for additional insights
- The server supports:
- Core translation API (/translate, /translate/batch)
- System health/version (/health, /version)
- Plugin compatibility endpoints (/imme, /kiss, /deepl, /google/*, /hcfy)
- Configurable via flags or env vars (model directory, UI toggle, offline mode, API token)
- Models are auto-downloaded on first use by internal/downloader and cached in MT_MODEL_DIR.
- UI is served (either statically or via embedded files) when “–ui” is enabled.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        Ext_ModelRepo["Model Repository Hosts\n(Mozilla, Bergamot)"]:::external
        Ext_PluginClients["Plugin Clients"]:::external
        Ext_DockerRegistry["Docker Registry"]:::external
        CI["CI/CD (GitHub Actions)"]:::external
    end

    %% Clients
    subgraph "Clients"
        CLI["CLI (mtranserver binary)"]:::frontend
        RestClients["REST API Clients\n(curl, services)"]:::frontend
        Browser["Web UI (Browser)"]:::frontend
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["Web UI (React/TS)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        APISvr["API Server\n(HTTP Listener)"]:::backend
        AuthM["Auth Middleware"]:::backend
        CorsM["CORS Middleware"]:::backend
        LogM["Logging Middleware"]:::backend
        Router["Router & Route Definitions"]:::backend

        subgraph "Handlers"
            SysH["System Handlers\n(/health, /version)"]:::backend
            TransH["Translate Handlers\n(/translate, /batch)"]:::backend
            subgraph "Plugin Handlers"
                ImmeH["/imme"]:::backend
                KissH["/kiss"]:::backend
                DeepH["/deepl"]:::backend
                GoogleH["/google/*"]:::backend
                HcfyH["/hcfy"]:::backend
            end
        end

        subgraph "Services"
            Detector["Language Detector"]:::backend
            Engine["Translation Engine"]:::backend
        end

        subgraph "Manager"
            Pool["Worker Pool & Daemon"]:::backend
        end

        Downl["Downloader"]:::backend
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Config["Configuration"]:::backend
        LoggerInit["Logger Initialization"]:::backend
        Models["Domain Models & Record Store"]:::storage
        Utils["Utility Functions"]:::backend
    end

    %% Storage
    subgraph "Storage"
        ModelStore["Model Store (FS)"]:::storage
        RecordsJSON["data/records.json"]:::storage
    end

    %% Flows
    CLI --> APISvr
    RestClients --> APISvr
    Browser --> UI
    UI --> APISvr

    APISvr --> AuthM --> CorsM --> LogM --> Router
    Router --> SysH
    Router --> TransH
    Router --> ImmeH
    Router --> KissH
    Router --> DeepH
    Router --> GoogleH
    Router --> HcfyH

    TransH --> Detector --> Pool --> Engine --> Pool
    Pool -->|model missing| Downl --> ModelStore --> Engine
    Engine --> TransH
    SysH --> Router

    Ext_ModelRepo --> Downl
    Ext_PluginClients --> ImmeH
    Ext_PluginClients --> KissH
    Ext_PluginClients --> DeepH
    Ext_PluginClients --> GoogleH
    Ext_PluginClients --> HcfyH
    CI --> Dockerfile
    CI --> composeYML

    %% Click Events
    click CLI "https://github.com/xxnuo/mtranserver/blob/main/cmd/mtranserver/main.go"
    click Config "https://github.com/xxnuo/mtranserver/blob/main/internal/config/config.go"
    click LoggerInit "https://github.com/xxnuo/mtranserver/blob/main/internal/logger/logger.go"
    click APISvr "https://github.com/xxnuo/mtranserver/blob/main/internal/server/server.go"
    click Router "https://github.com/xxnuo/mtranserver/blob/main/internal/routes/routes.go"
    click AuthM "https://github.com/xxnuo/mtranserver/blob/main/internal/middleware/auth.go"
    click CorsM "https://github.com/xxnuo/mtranserver/blob/main/internal/middleware/cors.go"
    click LogM "https://github.com/xxnuo/mtranserver/blob/main/internal/middleware/logger.go"
    click SysH "https://github.com/xxnuo/mtranserver/blob/main/internal/handlers/system.go"
    click TransH "https://github.com/xxnuo/mtranserver/blob/main/internal/handlers/translate.go"
    click Detector "https://github.com/xxnuo/mtranserver/blob/main/internal/services/detector.go"
    click Engine "https://github.com/xxnuo/mtranserver/blob/main/internal/services/engine.go"
    click Pool "https://github.com/xxnuo/mtranserver/blob/main/internal/manager/manager.go"
    click Downl "https://github.com/xxnuo/mtranserver/blob/main/internal/downloader/downloader.go"
    click Models "https://github.com/xxnuo/mtranserver/blob/main/internal/models/records.go"
    click Utils "https://github.com/xxnuo/mtranserver/blob/main/internal/utils/file.go"
    click RecordsJSON "https://github.com/xxnuo/mtranserver/blob/main/data/records.json"
    click UI "https://github.com/xxnuo/mtranserver/blob/main/ui/index.html"
    click Dockerfile "https://github.com/xxnuo/mtranserver/tree/main/Dockerfile"
    click composeYML "https://github.com/xxnuo/mtranserver/blob/main/compose.yml"
    click ImmeH "https://github.com/xxnuo/mtranserver/blob/main/internal/handlers/imme.go"
    click KissH "https://github.com/xxnuo/mtranserver/blob/main/internal/handlers/kiss.go"
    click DeepH "https://github.com/xxnuo/mtranserver/blob/main/internal/handlers/deepl.go"
    click GoogleH "https://github.com/xxnuo/mtranserver/blob/main/internal/handlers/google.go"
    click HcfyH "https://github.com/xxnuo/mtranserver/blob/main/internal/handlers/hcfy.go"

    %% Styles
    classDef backend fill:#E0F2FF,stroke:#0366d6,color:#0366d6;
    classDef storage fill:#ECF9EC,stroke:#2F8F2F,color:#2F8F2F;
    classDef frontend fill:#FFF5E6,stroke:#E69500,color:#E69500;
    classDef external fill:#F0F0F0,stroke:#AAA,color:#555;
```
