# traukit0/trueq architecture

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

- Interactive diagram: https://gitdiagram.com/traukit0/trueq
- Repository: https://github.com/traukit0/trueq

## Overview

##### Project type and purpose
- TrueQ is a full-stack CRUD web application (MVP) for social exchanges of goods and services.
- Frontend: React/Vite single-page application served by Nginx.
- Backend: Flask REST API with SQLAlchemy (ORM) and Alembic (migrations).
- Data persists in a MySQL container; Adminer provides a DB GUI.

##### Main components
a. User Browser (client)
b. Nginx + React container (“frontend”)
c. Flask API container (“backend”)
- Routes layer (item_routes.py)
- Services layer (item_service.py)
- Models layer (SQLAlchemy models: Item)
- Alembic migrations (versions/*)
d. MySQL database container (db_data volume)
e. Adminer container (DB administration)
f. Docker Compose orchestration (network + volumes)

##### Relationships and data flow
- Browser → (HTTP/HTTPS) → Nginx serves index.html & JS bundle
- React app → (XHR/fetch to /api) → Flask API endpoints
- Flask API → SQLAlchemy → MySQL reads/writes
- Alembic (at build or manually) → applies migrations to MySQL
- Adminer ↔ MySQL for visual DB management

##### Architectural patterns and principles
- Client-Server separation: loose coupling via REST API
- Layered backend: Controllers (routes) → Business Logic (services) → Data Access (models)
- Containerization: each service isolated in its own Docker image
- Infrastructure-as-code: docker-compose.yml defines multi-container topology
- Configuration via environment variables (.env in compose)

##### Technologies & modules call-outs
- Backend: Flask, Flask-CORS, SQLAlchemy, Alembic
- DB: MySQL 8, Adminer
- Deployment: Docker, Docker Compose, Nginx

## Diagram (Mermaid)

```mermaid
flowchart TD
    UserBrowser["User Browser"]:::client

    subgraph "trueq_net"
        Frontend["Frontend\nReact + Nginx"]:::frontend
        subgraph "Frontend Files"
            FE_Docker["Dockerfile"]:::frontend
            FE_Nginx["nginx.conf"]:::frontend
            FE_Index["index.html"]:::frontend
            FE_SRC["src/"]:::frontend
        end

        Backend["Backend\nFlask API"]:::backend
        subgraph "Backend Files"
            BE_Docker["Dockerfile"]:::backend
            BE_Config["config.py"]:::backend
            BE_Routes["item_routes.py"]:::backend
            BE_Service["item_service.py"]:::backend
            BE_Model["item.py"]:::backend
        end
        subgraph "Alembic Migrations"
            AlembicINI["alembic.ini"]:::backend
            AlembicEnv["env.py"]:::backend
            AlembicVers["versions/"]:::backend
            Mig1["1bbf6a8844a2_se_agrega_a_la_bd_el_item_valor.py"]:::backend
            Mig2["a204ba9f4331_create_items_table.py"]:::backend
        end

        MySQL["MySQL DB"]:::db
        Adminer["Adminer"]:::tool
    end

    Alembic["Alembic\n(Migrations)"]:::tool

    UserBrowser -->|"HTTP/HTTPS 80/443"| Frontend
    Frontend -->|"REST /api 5000"| Backend
    Backend -->|"SQLAlchemy 3306"| MySQL
    Alembic -->|"Migrations 3306"| MySQL
    Adminer <-->|"8080/3306"| MySQL

    click FE_Docker "https://github.com/traukit0/trueq/tree/main/frontend/Dockerfile"
    click FE_Nginx "https://github.com/traukit0/trueq/blob/main/frontend/nginx.conf"
    click FE_Index "https://github.com/traukit0/trueq/blob/main/frontend/index.html"
    click FE_SRC "https://github.com/traukit0/trueq/tree/main/frontend/src/"
    click Frontend "https://github.com/traukit0/trueq/tree/main/frontend/"
    click BE_Docker "https://github.com/traukit0/trueq/tree/main/backend/Dockerfile"
    click BE_Config "https://github.com/traukit0/trueq/blob/main/backend/app/config.py"
    click BE_Routes "https://github.com/traukit0/trueq/blob/main/backend/app/routes/item_routes.py"
    click BE_Service "https://github.com/traukit0/trueq/blob/main/backend/app/services/item_service.py"
    click BE_Model "https://github.com/traukit0/trueq/blob/main/backend/app/models/item.py"
    click AlembicINI "https://github.com/traukit0/trueq/blob/main/backend/alembic.ini"
    click AlembicEnv "https://github.com/traukit0/trueq/blob/main/backend/alembic/env.py"
    click AlembicVers "https://github.com/traukit0/trueq/tree/main/backend/alembic/versions/"
    click Mig1 "https://github.com/traukit0/trueq/blob/main/backend/alembic/versions/1bbf6a8844a2_se_agrega_a_la_bd_el_item_valor.py"
    click Mig2 "https://github.com/traukit0/trueq/blob/main/backend/alembic/versions/a204ba9f4331_create_items_table.py"
    click Adminer "https://github.com/traukit0/trueq/blob/main/docker-compose.yml"
    click MySQL "https://github.com/traukit0/trueq/blob/main/docker-compose.yml"
    click Backend "https://github.com/traukit0/trueq/tree/main/backend/"
    click dockerCompose "https://github.com/traukit0/trueq/blob/main/docker-compose.yml"

    classDef client fill:#FFF2CC,stroke:#C1A000
    classDef frontend fill:#FFE0B2,stroke:#E65100
    classDef backend fill:#BBDEFB,stroke:#1976D2
    classDef db fill:#C8E6C9,stroke:#2E7D32,shape:cylinder
    classDef tool fill:#E0E0E0,stroke:#424242
```
