# florentinodev/proyecto_tortolas architecture

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

- Interactive diagram: https://gitdiagram.com/florentinodev/proyecto_tortolas
- Repository: https://github.com/florentinodev/proyecto_tortolas

## Overview

##### Project type and purpose
- This is a machine‐learning pipeline for semantic segmentation of drone‐generated orthomosaics in mining operations.
- It uses YOLOv8 for detecting vehicles, pipes, and structures. It covers data preparation, labeling (Roboflow), training (CPU/GPU), and inference/serving (app.py), producing vector outputs for spatial analysis.

##### File structure
- Top‐level scripts and configs:
- app.py – inference server or API entrypoint
- YOLO.py – training/evaluation script invoking ultralytics YOLOv8
- utils.py – shared utilities (data loaders, post‐processing)
- requirements.txt & startup.sh – environment setup
- Dockerfile – containerization
- Data directories:
- dataset/ – raw/train/validation images + labels
- test_images/ & frontend/test_images/ – sample inputs for inference
- Experiment records:
- RUN/ & frontend/RUN/ – per‐model “args.yaml” + “results.csv” logs
- Config & docs:
- config/runtime.txt – pinned runtime dependencies
- docs/ – dataset README, Roboflow instructions, publishing profiles
- CI/CD:
- .github/workflows/* (azure‐deploy.yml, deploy.yml, main_tortolas-yolo.yml) for automated training/deployment pipelines.

##### README for additional insights
- Confirms end-to-end workflow: data prep → Roboflow labeling → YOLOv8 training → vector outputs.
- Mentions both CPU and GPU support.
- “deploy final funcionando” implies a deployed service (likely via app.py + Docker + Azure).

a. Main components:
1. Data Ingestion & Storage
– Raw drone orthomosaic images (dataset/train/images, dataset/valid/images)
– Label files (dataset/*/labels/*.txt)
2. Labeling Service
– Roboflow integration (docs/README.roboflow.txt)
3. Preprocessing & Utilities
– utils.py transforms, caching of labels (labels.cache)
4. Training & Experimentation
– YOLO.py script, ultralytics YOLOv8 framework
– RUN/ directories record hyperparameters (args.yaml) and metrics (results.csv)
– CI/CD (GitHub Actions, .github/workflows) spin up containers or VMs
5. Model Registry / Artifact Storage
– filesystem under RUN/ and frontend/RUN/ (could also point to Azure Blob or similar)
6. Inference & Serving
– app.py provides a REST or CLI API for segmentation
– startup.sh & Dockerfile wrap the service into a container
7. Deployment Infrastructure
– Docker container → Azure Web App / Kubernetes using azure-deploy.yml
8. Frontend / Client (optional)
– Static test harness under frontend/test_images or a minimal web UI to upload images

b. Relationships & data flow
- Raw images → Labeling Service → Preprocessing → Training Pipeline → Model Artifacts
- Model Artifacts → Inference Service (app.py) → Vector Output
- CI/CD orchestrates Training and Deployment steps automatically on push

c. Architectural patterns & design principles
- Pipeline pattern: clear stages (data → training → serve)
- Separation of concerns: distinct repos/directories for data, training, inference
- Containerization: reproducible environments (Dockerfile, startup.sh, requirements.txt)
- Experiment tracking: each RUN folder captures configs + results for reproducibility
- CI/CD: automated training and deploy pipelines via GitHub Actions

d. Key technologies & frameworks
- Python 3.x, ultralytics YOLOv8, Roboflow
- Flask or FastAPI (assumed in app.py)
- Docker, GitHub Actions, Azure Web App / Azure Container Instances
- YAML for configs (args.yaml, data.yaml, runtime.txt)
- CSV for metrics logging

## Diagram (Mermaid)

```mermaid
graph TB
    %% Data Ingestion & Storage Layer
    subgraph "Data Ingestion & Storage"
        direction TB
        A1["dataset/train/images"]:::data
        A2["dataset/train/labels"]:::data
        A3["dataset/valid/images"]:::data
        A4["dataset/valid/labels"]:::data
        A5["data.yaml"]:::data
    end

    %% Labeling Service
    subgraph "Labeling Service"
        direction TB
        B1["Roboflow Integration"]:::data
    end

    %% Preprocessing & Utilities
    subgraph "Preprocessing & Utilities"
        direction TB
        C1["utils.py"]:::compute
    end

    %% Training & Experimentation
    subgraph "Training & Experimentation"
        direction TB
        D1["YOLO.py"]:::compute
        D2["config/runtime.txt"]:::compute
        D3["requirements.txt"]:::compute
        D4[".github/workflows/main_tortolas-yolo.yml"]:::ci
    end

    %% Model Registry / Experiment Tracking
    subgraph "Model Registry / Experiment Tracking"
        direction TB
        E1["RUN/.../args.yaml"]:::data
        E2["RUN/.../results.csv"]:::data
        E3["frontend/RUN/.../args.yaml"]:::data
        E4["frontend/RUN/.../results.csv"]:::data
    end

    %% Inference & Serving
    subgraph "Inference & Serving"
        direction TB
        F1["app.py"]:::api
        F2["test_images/"]:::data
        F3["frontend/test_images/"]:::data
    end

    %% Frontend Client / Test Harness
    subgraph "Frontend Client / Test Harness"
        direction TB
        G1["assets"]:::api
    end

    %% Deployment Infrastructure & CI/CD
    subgraph "Deployment Infrastructure & CI/CD"
        direction TB
        H1["Dockerfile"]:::deploy
        H2["startup.sh"]:::deploy
        H3[".github/workflows/deploy.yml"]:::ci
        H4[".github/workflows/azure-deploy.yml"]:::ci
    end

    %% Connections
    A1 & A2 & A3 & A4 & A5 --> B1
    B1 --> C1
    C1 --> D1
    D1 --> D2
    D1 --> D3
    D1 --> D4
    D1 --> E1
    D1 --> E2
    D1 --> E3
    D1 --> E4
    E1 & E2 & E3 & E4 --> F1
    F1 --> F2
    F1 --> F3
    F3 --> G1
    H1 --> F1
    H2 --> F1
    H3 --> D1
    H3 --> H1
    H4 --> H1

    %% Click Events
    click A1 "https://github.com/florentinodev/proyecto_tortolas/tree/main/dataset/train/images"
    click A2 "https://github.com/florentinodev/proyecto_tortolas/tree/main/dataset/train/labels"
    click A3 "https://github.com/florentinodev/proyecto_tortolas/tree/main/dataset/valid/images"
    click A4 "https://github.com/florentinodev/proyecto_tortolas/tree/main/dataset/valid/labels"
    click A5 "https://github.com/florentinodev/proyecto_tortolas/blob/main/data.yaml"
    click B1 "https://github.com/florentinodev/proyecto_tortolas/blob/main/docs/README.roboflow.txt"
    click C1 "https://github.com/florentinodev/proyecto_tortolas/blob/main/utils.py"
    click D1 "https://github.com/florentinodev/proyecto_tortolas/blob/main/YOLO.py"
    click D2 "https://github.com/florentinodev/proyecto_tortolas/blob/main/config/runtime.txt"
    click D3 "https://github.com/florentinodev/proyecto_tortolas/blob/main/requirements.txt"
    click D4 "https://github.com/florentinodev/proyecto_tortolas/blob/main/.github/workflows/main_tortolas-yolo.yml"
    click E1 "https://github.com/florentinodev/proyecto_tortolas/blob/main/RUN/modelo_entrenado*/args.yaml"
    click E2 "https://github.com/florentinodev/proyecto_tortolas/blob/main/RUN/modelo_entrenado*/results.csv"
    click E3 "https://github.com/florentinodev/proyecto_tortolas/blob/main/frontend/RUN/modelo_*/*/args.yaml"
    click E4 "https://github.com/florentinodev/proyecto_tortolas/blob/main/frontend/RUN/modelo_*/*/results.csv"
    click F1 "https://github.com/florentinodev/proyecto_tortolas/blob/main/app.py"
    click F2 "https://github.com/florentinodev/proyecto_tortolas/tree/main/test_images/"
    click F3 "https://github.com/florentinodev/proyecto_tortolas/tree/main/frontend/test_images/"
    click H1 "https://github.com/florentinodev/proyecto_tortolas/tree/main/Dockerfile"
    click H2 "https://github.com/florentinodev/proyecto_tortolas/blob/main/startup.sh"
    click H3 "https://github.com/florentinodev/proyecto_tortolas/blob/main/.github/workflows/deploy.yml"
    click H4 "https://github.com/florentinodev/proyecto_tortolas/blob/main/.github/workflows/azure-deploy.yml"

    %% Styles
    classDef data fill:#cde5f7,stroke:#2f5d89,color:#000
    classDef compute fill:#d2f8d2,stroke:#3f773f,color:#000
    classDef api fill:#ffe5b4,stroke:#b38535,color:#000
    classDef deploy fill:#f4d2f8,stroke:#883f77,color:#000
    classDef ci fill:#e0ccff,stroke:#6b4599,color:#000
```
