# xtreme1-io/xtreme1 architecture

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

- Interactive diagram: https://gitdiagram.com/xtreme1-io/xtreme1
- Repository: https://github.com/xtreme1-io/xtreme1

## Overview

##### Project type and purpose
- This is a full-stack, open-source platform (“Xtreme1”) for multimodal ML data annotation, curation, and ontology management.
- Backend: Java Spring Boot, hexagonal (ports/adapters) architecture.
- Frontend: a Vite-based monorepo with several Vue applications (main dashboard, image-tool, pc-tool, text-tool).
- Infrastructure as code under “.ops” (Dockerfiles, Kubernetes manifests via Kustomize).

##### File structure
- Top-level directories:
- backend/ (Spring Boot service with adapter/api, usecase, port, entity layers)
- frontend/ (multiple Vue apps: main, image-tool, pc-tool, text-tool)
- .ops/ (Dockerfiles + k8s/base, dev, test overlays)
- deploy/ (docker-compose, nginx, MySQL migration scripts)
- Patterns:
- Backend follows hexagonal layering: adapter → usecase → port → entity
- CI/CD in .github & .ops, containerization in Docker and Kubernetes

##### README for additional insights
- Services: MySQL, Redis, MinIO, plus application containers (backend, frontend).
- Built-in “model” services deployed via Docker profiles (requires GPU + CUDA).
- Docker Compose orchestrates pull vs. build, volumes, networks.

##### Detail guidance
- MySQL, Redis, MinIO around backend to show direct connections.
- External model inference containers alongside backend, show HTTP calls from adapter/api/job or rpc callers.
- UI apps under “Frontend” and show they all call the same backend API endpoint (or different endpoints if segregated).
- Keep labels concise but specific (e.g., “AuthController (JWT Filter)”, “DatasetUseCase”, “MinIO Object Store (S3 API)”).

## Diagram (Mermaid)

```mermaid
graph TB
    %% UI Layer
    subgraph "UI Layer"
        Browser["User Browser"]:::ui
        Main["Main Dashboard"]:::ui
        Image["Image Annotation Tool"]:::ui
        PC["Point-Cloud Annotation Tool"]:::ui
        Text["Text Annotation Tool"]:::ui
    end

    %% API Gateway
    subgraph "API Gateway / Load Balancer"
        Nginx["Nginx (Ingress / Proxy)"]:::service
    end

    %% Backend Service
    subgraph "Backend Service"
        subgraph "Hexagonal Core"
            Domain["Domain / UseCases"]:::hex
            Entity["Entities"]:::hex
        end
        subgraph "Adapters"
            Controller["REST Controllers"]:::hex
            Job["Job Consumers / Schedulers"]:::hex
        end
        subgraph "Ports"
            DAO["MySQL DAO"]:::hex
            RedisPort["Redis Adapter"]:::hex
            MinIOPort["MinIO Adapter"]:::hex
            RPC["External Model RPC"]:::hex
        end
    end

    %% Data Stores
    subgraph "Data Stores"
        MySQL["MySQL"]:::data
        Redis["Redis"]:::data
        MinIO["MinIO (S3)"]:::data
    end

    %% External Services
    subgraph "External Services"
        Models["Model Inference Services"]:::external
    end

    %% DevOps / Infrastructure
    subgraph "DevOps"
        CI["CI/CD Pipeline"]:::ops
        DockerOps["Docker Build & Push Scripts"]:::ops
        K8sBE["K8s Backend Overlays"]:::ops
        K8sFE["K8s Frontend Overlays"]:::ops
        Compose["Docker Compose"]:::ops
        Migration["MySQL Migration Scripts"]:::ops
        CNginx["Nginx Config"]:::ops
    end

    %% Connections
    Browser -->|"HTTP"| Main
    Browser -->|"HTTP"| Image
    Browser -->|"HTTP"| PC
    Browser -->|"HTTP"| Text

    Main -->|"REST API"| Nginx
    Image -->|"REST API"| Nginx
    PC -->|"REST API"| Nginx
    Text -->|"REST API"| Nginx

    Nginx -->|"HTTP"| Controller
    Controller -->|"invoke"| Domain
    Job -->|"schedule"| Domain

    Domain -->|"use DAO"| DAO
    Domain -->|"use Redis"| RedisPort
    Domain -->|"use MinIO"| MinIOPort
    Domain -->|"call RPC"| RPC

    DAO -->|"SQL"| MySQL
    RedisPort -->|"TCP"| Redis
    MinIOPort -->|"S3 API"| MinIO
    RPC -->|"HTTP"| Models

    CI --> DockerOps
    DockerOps --> Compose
    Compose --> Nginx
    Compose --> MySQL
    Compose --> Redis
    Compose --> MinIO

    CI --> K8sBE
    CI --> K8sFE

    Compose -->|"migrations"| Migration
    Compose -->|"load balancer config"| CNginx

    %% Click Events
    click Main "https://github.com/xtreme1-io/xtreme1/tree/main/frontend/main"
    click Image "https://github.com/xtreme1-io/xtreme1/tree/main/frontend/image-tool"
    click PC "https://github.com/xtreme1-io/xtreme1/tree/main/frontend/pc-tool"
    click Text "https://github.com/xtreme1-io/xtreme1/tree/main/frontend/text-tool"
    click Controller "https://github.com/xtreme1-io/xtreme1/tree/main/backend/src/main/java/ai/basic/x1/adapter/api/controller"
    click Domain "https://github.com/xtreme1-io/xtreme1/tree/main/backend/src/main/java/ai/basic/x1/usecase"
    click DAO "https://github.com/xtreme1-io/xtreme1/tree/main/backend/src/main/java/ai/basic/x1/adapter/port/dao"
    click RedisPort "https://github.com/xtreme1-io/xtreme1/tree/main/backend/src/main/java/ai/basic/x1/adapter/port/dao/redis"
    click RedisPort "https://github.com/xtreme1-io/xtreme1/blob/main/backend/src/main/java/ai/basic/x1/adapter/api/config/RedisConfig.java"
    click MinIOPort "https://github.com/xtreme1-io/xtreme1/tree/main/backend/src/main/java/ai/basic/x1/adapter/port/minio"
    click MinIOPort "https://github.com/xtreme1-io/xtreme1/blob/main/backend/src/main/java/ai/basic/x1/adapter/api/config/MinioConfig.java"
    click RPC "https://github.com/xtreme1-io/xtreme1/tree/main/backend/src/main/java/ai/basic/x1/adapter/port/rpc"
    click Job "https://github.com/xtreme1-io/xtreme1/tree/main/backend/src/main/java/ai/basic/x1/adapter/api/job"
    click Entity "https://github.com/xtreme1-io/xtreme1/tree/main/backend/src/main/java/ai/basic/x1/entity"
    click DockerOps "https://github.com/xtreme1-io/xtreme1/blob/main/.ops/backend.Dockerfile"
    click DockerOps "https://github.com/xtreme1-io/xtreme1/blob/main/.ops/build_and_push_images_to_docker_hub.sh"
    click K8sBE "https://github.com/xtreme1-io/xtreme1/tree/main/.ops/deploy/backend/base"
    click K8sBE "https://github.com/xtreme1-io/xtreme1/tree/main/.ops/deploy/backend/dev"
    click K8sBE "https://github.com/xtreme1-io/xtreme1/tree/main/.ops/deploy/backend/test"
    click K8sFE "https://github.com/xtreme1-io/xtreme1/tree/main/.ops/deploy/frontend/base"
    click K8sFE "https://github.com/xtreme1-io/xtreme1/tree/main/.ops/deploy/frontend/dev"
    click K8sFE "https://github.com/xtreme1-io/xtreme1/tree/main/.ops/deploy/frontend/test"
    click Compose "https://github.com/xtreme1-io/xtreme1/blob/main/docker-compose.yml"
    click Migration "https://github.com/xtreme1-io/xtreme1/tree/main/deploy/mysql/migration"
    click CNginx "https://github.com/xtreme1-io/xtreme1/blob/main/deploy/nginx/conf.d/default.conf"
    click CI "https://github.com/xtreme1-io/xtreme1/blob/main/.github/workflows/main.yml"

    %% Styles
    classDef ui fill:#9f6,stroke:#060,stroke-width:1px
    classDef service fill:#6cf,stroke:#036,stroke-width:1px
    classDef data fill:#fc6,stroke:#963,stroke-width:1px
    classDef hex fill:#6ff,stroke:#039,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#c9c,stroke:#639,stroke-width:1px,stroke-dasharray: 2 2
    classDef ops fill:#ddd,stroke:#888,stroke-width:1px,stroke-dasharray: 2 2
```
