# junioraguilar/oxiom architecture

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

- Interactive diagram: https://gitdiagram.com/junioraguilar/oxiom
- Repository: https://github.com/junioraguilar/oxiom

## Overview

##### Project type and purpose
- This is a full-stack web application for training, testing, and uploading YOLOv8 object-detection models.
- The backend is a Flask API that orchestrates model training/inference, and the frontend is a React (Vite) single-page application that provides the UI.

##### File structure
- Top-level: Docker-related files (`Dockerfile`, `docker-compose.yml`, `nginx.conf`) and environment definitions (`environment.yml`).
- `backend/`: Flask application (`app.py`), model definitions (`models.py`), training utilities, local SQLite DB (`models_db.sqlite`), and Python dependency list (`requirements.txt`).
- `frontend/`: React + TypeScript code under `src/`, HTML entrypoint, configuration (`vite.config.ts`, `tsconfig.json`), UI components, pages, API wrapper (`src/api/axios.ts`), and theming.
- Ignored (in README): `models/`, `uploads/`, and `train_data/` for persisted model files, user uploads, and raw training data.

##### README for additional insights
- Describes a Docker-Compose setup spinning up two services: a Flask + YOLOv8 backend (GPU-enabled) and a React dev server.
- Workflow: user uploads or selects a dataset → backend trains YOLO model → backend stores trained model → user tests the model on images → results displayed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Client["User Browser"]:::ui
        ReactApp["React App"]:::ui
    end

    %% Reverse Proxy
    subgraph "Ingress"
        direction TB
        NGINX["NGINX Reverse Proxy"]:::ext
    end

    %% Services
    subgraph "Docker Compose"
        direction TB
        subgraph "Frontend Service"
            direction TB
            FEContainer["React + Vite Container<br/>(port 5173)"]:::api
        end
        subgraph "Backend Service"
            direction TB
            BEContainer["Flask + YOLOv8 Container<br/>(port 5000 GPU-enabled)"]:::api
            TrainingUtils["Training & Inference Utilities"]:::api
            BEApp["Flask App"]:::api
        end
    end

    %% Data Persistence
    subgraph "Data Persistence"
        direction TB
        SQLiteDB["SQLite Database"]:::data
        ModelsVol["models/ Volume"]:::data
        UploadsVol["uploads/ Volume"]:::data
        TrainDataVol["train_data/ Volume"]:::data
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PyTorch["PyTorch/CUDA"]:::ext
    end

    %% Connections
    Client -->|"HTTP" |NGINX
    NGINX -->|"/(static)"|FEContainer
    NGINX -->|"/api/*"|BEContainer
    FEContainer -->|"/trainModel (POST JSON+files)"|BEContainer
    FEContainer -->|"/infer (POST image)"|BEContainer
    BEContainer -->|"calls"|TrainingUtils
    BEContainer -->|"reads/writes"|SQLiteDB
    BEContainer -->|"stores files"|ModelsVol
    BEContainer -->|"stores files"|UploadsVol
    BEContainer -->|"reads data"|TrainDataVol
    TrainingUtils -->|"uses"|PyTorch
    BEContainer -->|"/trainModel response (JSON)"|FEContainer
    BEContainer -->|"/infer response (JSON)"|FEContainer

    %% Click Events - UI Layer
    click ReactApp "https://github.com/junioraguilar/oxiom/tree/main/frontend/src"
    click Client "https://github.com/junioraguilar/oxiom/blob/main/frontend/index.html"
    click ReactApp "https://github.com/junioraguilar/oxiom/blob/main/frontend/src/main.tsx"
    click ReactApp "https://github.com/junioraguilar/oxiom/tree/main/frontend/src/components"
    click ReactApp "https://github.com/junioraguilar/oxiom/tree/main/frontend/src/pages"
    click ReactApp "https://github.com/junioraguilar/oxiom/blob/main/frontend/src/theme.ts"
    click ReactApp "https://github.com/junioraguilar/oxiom/blob/main/frontend/src/index.css"
    click ReactApp "https://github.com/junioraguilar/oxiom/blob/main/frontend/src/api/axios.ts"

    %% Click Events - Frontend Configs
    click FEContainer "https://github.com/junioraguilar/oxiom/blob/main/frontend/package.json"
    click FEContainer "https://github.com/junioraguilar/oxiom/blob/main/frontend/vite.config.ts"
    click FEContainer "https://github.com/junioraguilar/oxiom/blob/main/frontend/tsconfig.json"
    click FEContainer "https://github.com/junioraguilar/oxiom/blob/main/frontend/tsconfig.node.json"
    click FEContainer "https://github.com/junioraguilar/oxiom/blob/main/frontend/src/declarations.d.ts"

    %% Click Events - Ingress
    click NGINX "https://github.com/junioraguilar/oxiom/blob/main/nginx.conf"

    %% Click Events - Backend Service
    click BEApp "https://github.com/junioraguilar/oxiom/blob/main/backend/app.py"
    click BEContainer "https://github.com/junioraguilar/oxiom/blob/main/backend/models.py"
    click TrainingUtils "https://github.com/junioraguilar/oxiom/blob/main/backend/training_utils.py"
    click SQLiteDB "https://github.com/junioraguilar/oxiom/blob/main/backend/models_db.sqlite"
    click BEContainer "https://github.com/junioraguilar/oxiom/blob/main/backend/requirements.txt"
    click BEContainer "https://github.com/junioraguilar/oxiom/blob/main/backend/setup_db.bat"

    %% Click Events - Containerization
    click DockerCompose "https://github.com/junioraguilar/oxiom/blob/main/docker-compose.yml"
    click Dockerfile "https://github.com/junioraguilar/oxiom/tree/main/Dockerfile"
    click Dockerfile "https://github.com/junioraguilar/oxiom/blob/main/.dockerignore"

    %% Click Events - Environment
    click PyTorch "https://github.com/junioraguilar/oxiom/blob/main/environment.yml"
    click PyTorch "https://github.com/junioraguilar/oxiom/blob/main/data.yaml.example"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#02477E,color:#02477E;
    classDef api fill:#DFFFD0,stroke:#3C8A2E,color:#3C8A2E;
    classDef data fill:#FFE8B0,stroke:#B36B00,color:#B36B00;
    classDef ext fill:#E0E0E0,stroke:#888888,color:#555555;
```
