# garopabus/garopabus-backend architecture

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

- Interactive diagram: https://gitdiagram.com/garopabus/garopabus-backend
- Repository: https://github.com/garopabus/garopabus-backend

## Overview

##### Project type and purpose
- This is a Django-based RESTful backend (no frontend code here) that powers the “GaropaBus” transport service. It exposes APIs for routes, schedules, notifications (including push subscriptions), and persists data in a relational database.

##### File structure
- Top level: Dockerfile, docker-compose.yml, GitHub Actions workflows for dev/prod, pyproject.toml for Python dependencies.
- Django project “garopabus” holds global settings, ASGI/WGI entry points, and URL router.
- Single Django app “transporte” implements domain logic:
- models.py – ORM definitions (routes, schedules, notifications)
- serializers.py – DRF serializers
- views.py – API viewsets/endpoints
- urls.py – app-level routing
- filters.py, utils.py, logging.py – cross-cutting concerns
- migrations/ – database evolution history
- manage.py for CLI commands.

##### README
- Standard Django setup in a Python virtual environment.
- Uses pyproject.toml to declare dependencies.

a. Main components
- Client(s): mobile app, web app, or third-party integrators
- API Gateway/Reverse Proxy: Nginx (in front of the app container)
- Application Server: Uvicorn (ASGI) or Gunicorn (WSGI) running the Django project
- Django MVT layers:
– URL Dispatcher
– View layer (transporte.views)
– Serializer layer (transporte.serializers)
– Model layer (transporte.models)
- Database: PostgreSQL (or your chosen RDBMS in docker-compose)
- External services: Push Notification Provider (FCM/Web Push), Email/SMS gateway if used
- Infrastructure: Docker containers, docker-compose orchestration, GitHub Actions CI/CD

b. Relationships and interactions
1. Client → HTTP request to Nginx
2. Nginx → forwards to Uvicorn/Gunicorn → Django’s ASGI/WGI
3. Django URL router → maps to transporte.viewsets or APIView
4. View → invokes serializers and business logic (utils, filters) → interacts with models
5. Models → ORM → Database reads/writes
6. For event-driven actions (e.g. push notifications), View or utils → calls external Push Service API
7. All logs emitted via transporte.logging → captured by Docker log driver or forwarded to external logging system

c. Architectural patterns and design principles
- Layered (MVT) architecture
- RESTful API design with Django REST Framework
- Twelve-factor app guidelines (environment via .env, declarative dependencies, stateless processes)
- Containerization (Docker), orchestration via docker-compose
- CI/CD pipelines (GitHub Actions) for dev & prod deployments

d. Key technologies/frameworks
- Python 3.x
- Django & Django REST Framework
- Uvicorn (ASGI) or Gunicorn (WSGI)
- PostgreSQL (configured in docker-compose)
- Docker & docker-compose
- GitHub Actions for CI/CD

##### Detail but keep it uncluttered
- Don’t “over-componentize” – separate only by logical/service boundaries (proxy vs. app vs. DB vs. external).
- Every essential layer: client → proxy → ASGI/WGI → Django MVT → database & external services → CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    Clients["Mobile/Web Clients\n(REST Consumers)"]:::external
    PushService["Push Notification Service\n(FCM/Web Push)"]:::external

    %% Infrastructure Proxy and App Server
    Nginx["Nginx (Reverse Proxy)"]:::infra
    UvicornGunicorn["Uvicorn/Gunicorn\n(ASGI/WSGI Server)"]:::app

    %% Application Container
    subgraph "Application Container" 
        direction TB
        manage["manage.py"]:::app
        subgraph "Django Project: garopabus"
            direction TB
            settings["settings.py"]:::app
            asgi["asgi.py"]:::app
            wsgi["wsgi.py"]:::app
            proj_urls["urls.py\n(Project-level)"]:::app
        end
        subgraph "Django App: transporte"
            direction TB
            apps_cfg["apps.py"]:::app
            admin_reg["admin.py"]:::app
            models["models.py"]:::app
            serializers["serializers.py"]:::app
            views["views.py"]:::app
            filters["filters.py"]:::app
            utils["utils.py"]:::app
            logging_mod["logging.py"]:::app
            migrations["migrations/"]:::app
        end
    end

    %% Data Store
    PostgreSQL["PostgreSQL Database"]:::db

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        direction TB
        DevWorkflow["Deploy-Development\n.github/workflows/deploy-development.yml"]:::pipeline
        ProdWorkflow["Deploy-Production\n.github/workflows/deploy-production.yml"]:::pipeline
        DockerRegistry["Docker Registry"]:::infra
    end

    %% Relationships
    Clients -->|"HTTP/HTTPS"| Nginx
    Nginx -->|"Proxy"| UvicornGunicorn
    UvicornGunicorn -->|"ASGI/WGI"| asgi
    UvicornGunicorn -->|"ASGI/WGI"| wsgi
    asgi -->|routes| proj_urls
    wsgi -->|routes| proj_urls
    proj_urls -->|include transporte.urls| subgraph_app_urls
    subgraph_app_urls["transporte/urls.py"]:::app
    subgraph_app_urls -->|dispatch| views

    views -->|use| serializers
    views -->|apply| filters
    views -->|call| utils
    serializers -->|serialize/validate| models
    utils -->|logic| models
    models -->|SQL| PostgreSQL
    views -->|emit logs| logging_mod
    utils -->|emit logs| logging_mod
    views -->|push events| PushService

    %% CI/CD Flow
    DevWorkflow -->|build/push| DockerRegistry
    ProdWorkflow -->|build/push| DockerRegistry
    DockerRegistry -->|deploy via docker-compose| ApplicationContainer

    %% Click Events
    click settings "https://github.com/garopabus/garopabus-backend/blob/main/garopabus/settings.py"
    click asgi "https://github.com/garopabus/garopabus-backend/blob/main/garopabus/asgi.py"
    click wsgi "https://github.com/garopabus/garopabus-backend/blob/main/garopabus/wsgi.py"
    click proj_urls "https://github.com/garopabus/garopabus-backend/blob/main/garopabus/urls.py"
    click subgraph_app_urls "https://github.com/garopabus/garopabus-backend/blob/main/transporte/urls.py"
    click views "https://github.com/garopabus/garopabus-backend/blob/main/transporte/views.py"
    click serializers "https://github.com/garopabus/garopabus-backend/blob/main/transporte/serializers.py"
    click models "https://github.com/garopabus/garopabus-backend/blob/main/transporte/models.py"
    click migrations "https://github.com/garopabus/garopabus-backend/tree/main/transporte/migrations/"
    click filters "https://github.com/garopabus/garopabus-backend/blob/main/transporte/filters.py"
    click utils "https://github.com/garopabus/garopabus-backend/blob/main/transporte/utils.py"
    click logging_mod "https://github.com/garopabus/garopabus-backend/blob/main/transporte/logging.py"
    click apps_cfg "https://github.com/garopabus/garopabus-backend/blob/main/transporte/apps.py"
    click admin_reg "https://github.com/garopabus/garopabus-backend/blob/main/transporte/admin.py"
    click manage "https://github.com/garopabus/garopabus-backend/blob/main/manage.py"
    click Dockerfile "https://github.com/garopabus/garopabus-backend/tree/main/Dockerfile"
    click DockerRegistry "https://github.com/garopabus/garopabus-backend/blob/main/docker-compose.yml"
    click DevWorkflow "https://github.com/garopabus/garopabus-backend/blob/main/.github/workflows/deploy-development.yml"
    click ProdWorkflow "https://github.com/garopabus/garopabus-backend/blob/main/.github/workflows/deploy-production.yml"
    click pyproject "https://github.com/garopabus/garopabus-backend/blob/main/pyproject.toml"

    %% Styles
    classDef external fill:#c8f7c5,stroke:#2d6a4f,color:#1b4332;
    classDef app fill:#caf0f8,stroke:#0077b6,color:#023e8a;
    classDef db fill:#ffd6a5,stroke:#fb8b24,color:#e85d04;
    classDef infra fill:#e0c3fc,stroke:#6a4c93,color:#3d087b;
    classDef pipeline fill:#ffcad4,stroke:#bb3655,color:#840032;
```
