# bertonez/tracking-de-pedidos architecture

> Architecture diagram of the GitHub repository bertonez/tracking-de-pedidos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bertonez/tracking-de-pedidos
- Repository: https://github.com/bertonez/tracking-de-pedidos

## Overview

1. **Visión general**
   - Es una API en Go para tracking de pedidos/logística.
   - La arquitectura está separada por capas: HTTP, aplicación/negocio, persistencia y soporte de infraestructura.
   - El sistema usa **PostgreSQL + PostGIS** para datos persistentes y geoespaciales, y **Redis** para tracking de alta frecuencia.

2. **Punto de entrada y arranque**
   - `cmd/api/main.go` es el bootstrap de la aplicación.
   - Desde ahí se inicializan conexiones, middleware, rutas y el servidor Gin.
   - `docker-compose.yaml` y `dockerfile` empaquetan toda la solución para correrla containerizada.

3. **Capa HTTP**
   - `internal/handler/*` contiene los controladores HTTP para `user`, `product` y `order`.
   - `internal/routes/*` registra los endpoints y los conecta con handlers y middleware.
   - Esta capa solo traduce requests/responses; no debería contener lógica de negocio pesada.

4. **Autenticación y autorización**
   - `internal/auth/jwt.go` implementa autenticación basada en JWT.
   - `internal/middleware/middleware.go` y `role_middleware.go` aplican protección de rutas y RBAC.
   - El README indica dos roles principales: **customer** y **driver**.
   - Además hay una regla de negocio importante: un cliente solo puede ver/trackear sus propios pedidos.

5. **Capa de negocio**
   - `internal/service/*` concentra la lógica de aplicación:
     - usuarios,
     - productos,
     - pedidos,
     - ubicación/tracking.
   - `location_service.go` y `geocoding.go` sugieren lógica especializada de geolocalización, probablemente como apoyo a tracking o enriquecimiento de ubicaciones.
   - Aquí viven las reglas de negocio que coordinan múltiples repositorios o validaciones.

6. **Dominio**
   - `internal/domain/*` modela las entidades centrales: `user`, `driver`, `product`, `order`.
   - Esta capa representa el núcleo del negocio y sirve como modelo común entre servicios, repositorios y DTOs.
   - La presencia de `driver.go` indica que el modelo distingue claramente entre cliente y repartidor/conductor.

7. **Persistencia**
   - `internal/repository/*` encapsula el acceso a datos:
     - repositorios de usuarios, productos, pedidos y ubicación.
   - `internal/db/postgres.go` gestiona la conexión a PostgreSQL.
   - `internal/db/redis.go` gestiona la conexión a Redis.
   - `init.sql` sugiere inicialización de esquema/datos base al levantar la base.

8. **Flujo de tracking en tiempo real**
   - El tracking de alta frecuencia probablemente entra por servicios/repositorios de ubicación.
   - **Redis** se usa para escrituras/consultas rápidas de geolocalización, lo que evita cargar Postgres en cada actualización.
   - **PostgreSQL + PostGIS** queda para persistencia fuerte y consultas geoespaciales más estructuradas.
   - En otras palabras: Redis para “estado vivo”, Postgres/PostGIS para “histórico y datos fuente”.

9. **DTOs y mapeo**
   - `internal/dto/*` define los contratos de entrada/salida de la API.
   - `internal/utils/*_mapper.go` convierte entre DTOs y entidades de dominio.
   - Esto mantiene desacoplados los modelos internos de negocio respecto de la forma exacta de la API.

10. **Documentación y contrato de API**
   - `docs/swagger.yaml`, `docs/swagger.json` y `docs/docs.go` muestran que la API está documentada con **Swagger/OpenAPI**.
   - El README apunta a `/swagger/index.html`, así que la documentación forma parte operativa del servicio.

11. **Infraestructura y despliegue**
   - El proyecto está pensado para correr completamente con Docker.
   - `docker-compose.yaml` probablemente coordina API, PostgreSQL y Redis como servicios separados.
   - Esto refuerza una arquitectura de backend desacoplado por dependencias externas.

12. **Boundaries importantes para el diagrama**
   - **HTTP boundary**: handlers/routes/middleware.
   - **Application boundary**: services.
   - **Domain boundary**: entities de negocio.
   - **Data boundary**: repositories + db connections.
   - **External state boundary**: PostgreSQL/PostGIS y Redis.
   - **Security boundary**: JWT + roles + validación de ownership.

13. **Resumen de responsabilidades**
   - La API recibe requests de usuarios o drivers.
   - Valida autenticación/autorización.
   - Ejecuta reglas de negocio en services.
   - Persiste o consulta en PostgreSQL/PostGIS y Redis según el tipo de dato.
   - Expone todo vía REST documentado con Swagger.

Main entry points: [`internal/service/order_service.go`](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/service/order_service.go) (Order service), [`cmd/api/main.go`](https://github.com/bertonez/tracking-de-pedidos/blob/main/cmd/api/main.go) (API main), [`internal/db/postgres.go`](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/db/postgres.go) (PostgreSQL), [`internal/utils/order_mapper.go`](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/utils/order_mapper.go) (Mappers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry"]
  node_cmd_api_main["API main<br/>bootstrap<br/>[main.go]"]
end

subgraph group_http["HTTP API"]
  node_user_routes["User routes<br/>route reg<br/>[user_routes.go]"]
  node_product_routes["Product routes<br/>route reg<br/>[product_routes.go]"]
  node_order_routes["Order routes<br/>route reg<br/>[order_routes.go]"]
  node_user_handler["User handler<br/>HTTP handler<br/>[user_handler.go]"]
  node_product_handler["Product handler<br/>HTTP handler<br/>[product_handler.go]"]
  node_order_handler["Order handler<br/>HTTP handler<br/>[order_handler.go]"]
  node_dto_models["DTOs<br/>api contracts<br/>[user_dto.go]"]
end

subgraph group_app["Application"]
  node_user_service["User service<br/>app service<br/>[user_service.go]"]
  node_product_service["Product service<br/>app service<br/>[product_service.go]"]
  node_order_service["Order service<br/>app service<br/>[order_service.go]"]
  node_location_service["Location service<br/>geo service"]
  node_geocoding["Geocoding<br/>geo logic<br/>[geocoding.go]"]
  node_mappers["Mappers<br/>transform<br/>[order_mapper.go]"]
end

subgraph group_domain["Domain"]
  node_user_domain["User<br/>entity<br/>[user.go]"]
  node_driver_domain["Driver<br/>entity<br/>[driver.go]"]
  node_product_domain["Product<br/>entity<br/>[product.go]"]
  node_order_domain["Order<br/>entity<br/>[order.go]"]
end

subgraph group_data["Data"]
  node_user_repo["User repo<br/>[user_repository.go]"]
  node_product_repo["Product repo"]
  node_order_repo["Order repo"]
  node_location_repo["Location repo"]
  node_init_sql["Init SQL<br/>schema init<br/>[init.sql]"]
end

subgraph group_security["Security"]
  node_middleware["Middleware<br/>auth guard<br/>[middleware.go]"]
  node_role_middleware["Role guard<br/>rbac<br/>[role_middleware.go]"]
  node_jwt_auth["JWT auth<br/>token auth<br/>[jwt.go]"]
end

subgraph group_external["External Systems"]
  node_postgres_db[("PostgreSQL<br/>sql/postgis<br/>[postgres.go]")]
  node_redis_db[("Redis<br/>cache/state<br/>[redis.go]")]
end

subgraph group_docs["Docs"]
  node_swagger_docs["Swagger<br/>openapi<br/>[swagger.yaml]"]
end

subgraph group_deploy["Deploy"]
  node_compose["Compose<br/>runtime config"]
  node_dockerfile["Dockerfile<br/>image build"]
end

node_cmd_api_main -->|"mounts"| node_user_routes
node_cmd_api_main -->|"mounts"| node_product_routes
node_cmd_api_main -->|"mounts"| node_order_routes
node_cmd_api_main -->|"connects"| node_postgres_db
node_cmd_api_main -->|"connects"| node_redis_db
node_user_routes -->|"uses"| node_middleware
node_product_routes -->|"uses"| node_middleware
node_order_routes -->|"uses"| node_middleware
node_order_routes -->|"uses"| node_role_middleware
node_middleware -->|"delegates"| node_jwt_auth
node_user_routes -->|"maps to"| node_user_handler
node_product_routes -->|"maps to"| node_product_handler
node_order_routes -->|"maps to"| node_order_handler
node_user_handler -->|"calls"| node_user_service
node_product_handler -->|"calls"| node_product_service
node_order_handler -->|"calls"| node_order_service
node_order_service -->|"uses"| node_location_service
node_location_service -->|"uses"| node_geocoding
node_user_service -->|"persists via"| node_user_repo
node_product_service -->|"persists via"| node_product_repo
node_order_service -->|"persists via"| node_order_repo
node_order_service -->|"persists via"| node_location_repo
node_location_service -->|"reads/writes"| node_location_repo
node_user_repo -->|"uses"| node_postgres_db
node_product_repo -->|"uses"| node_postgres_db
node_order_repo -->|"uses"| node_postgres_db
node_location_repo -->|"uses"| node_redis_db
node_location_repo -->|"uses"| node_postgres_db
node_user_handler -->|"serializes"| node_dto_models
node_product_handler -->|"serializes"| node_dto_models
node_order_handler -->|"serializes"| node_dto_models
node_mappers -->|"converts"| node_dto_models
node_mappers -->|"converts"| node_user_domain
node_mappers -->|"converts"| node_product_domain
node_mappers -->|"converts"| node_order_domain
node_user_service -->|"operates on"| node_user_domain
node_product_service -->|"operates on"| node_product_domain
node_order_service -->|"operates on"| node_order_domain
node_order_service -->|"checks"| node_driver_domain
node_swagger_docs -.->|"documents"| node_cmd_api_main
node_compose -.->|"builds with"| node_dockerfile
node_compose -.->|"orchestrates"| node_postgres_db
node_compose -.->|"orchestrates"| node_redis_db
node_init_sql -.->|"initializes"| node_postgres_db

click node_cmd_api_main "https://github.com/bertonez/tracking-de-pedidos/blob/main/cmd/api/main.go"
click node_user_routes "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/routes/user_routes.go"
click node_product_routes "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/routes/product_routes.go"
click node_order_routes "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/routes/order_routes.go"
click node_user_handler "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/handler/user_handler.go"
click node_product_handler "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/handler/product_handler.go"
click node_order_handler "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/handler/order_handler.go"
click node_middleware "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/middleware/middleware.go"
click node_role_middleware "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/middleware/role_middleware.go"
click node_jwt_auth "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/auth/jwt.go"
click node_user_service "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/service/user_service.go"
click node_product_service "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/service/product_service.go"
click node_order_service "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/service/order_service.go"
click node_location_service "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/service/location_service.go"
click node_geocoding "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/service/geocoding.go"
click node_user_domain "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/domain/user.go"
click node_driver_domain "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/domain/driver.go"
click node_product_domain "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/domain/product.go"
click node_order_domain "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/domain/order.go"
click node_user_repo "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/repository/user_repository.go"
click node_product_repo "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/repository/product_repository.go"
click node_order_repo "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/repository/order_repository.go"
click node_location_repo "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/repository/location_repository.go"
click node_postgres_db "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/db/postgres.go"
click node_redis_db "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/db/redis.go"
click node_dto_models "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/dto/user_dto.go"
click node_mappers "https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/utils/order_mapper.go"
click node_swagger_docs "https://github.com/bertonez/tracking-de-pedidos/blob/main/docs/swagger.yaml"
click node_compose "https://github.com/bertonez/tracking-de-pedidos/blob/main/docker-compose.yaml"
click node_dockerfile "https://github.com/bertonez/tracking-de-pedidos/tree/main/dockerfile"
click node_init_sql "https://github.com/bertonez/tracking-de-pedidos/blob/main/init.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_api_main,node_postgres_db,node_redis_db toneBlue
class node_user_routes,node_product_routes,node_order_routes,node_user_handler,node_product_handler,node_order_handler,node_dto_models,node_swagger_docs toneAmber
class node_user_service,node_product_service,node_order_service,node_location_service,node_geocoding,node_mappers,node_compose,node_dockerfile toneMint
class node_user_domain,node_driver_domain,node_product_domain,node_order_domain toneRose
class node_user_repo,node_product_repo,node_order_repo,node_location_repo,node_init_sql toneIndigo
class node_middleware,node_role_middleware,node_jwt_auth toneTeal
```

## Components

### Entry

Application bootstrap and process startup

- [API main](https://github.com/bertonez/tracking-de-pedidos/blob/main/cmd/api/main.go): bootstrap · Starts the HTTP server and wires dependencies · `cmd/api/main.go`

### HTTP API

Request handling, routing, and transport concerns

- [User routes](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/routes/user_routes.go): route reg · Registers user endpoints and middleware · `internal/routes/user_routes.go`
- [Product routes](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/routes/product_routes.go): route reg · Registers product endpoints and middleware · `internal/routes/product_routes.go`
- [Order routes](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/routes/order_routes.go): route reg · Registers order endpoints and middleware · `internal/routes/order_routes.go`
- [User handler](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/handler/user_handler.go): HTTP handler · Translates user requests and responses · `internal/handler/user_handler.go`
- [Product handler](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/handler/product_handler.go): HTTP handler · Translates product requests and responses · `internal/handler/product_handler.go`
- [Order handler](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/handler/order_handler.go): HTTP handler · Translates order requests and responses · `internal/handler/order_handler.go`
- [DTOs](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/dto/user_dto.go): api contracts · Request and response shapes for the API · `internal/dto/user_dto.go`

### Application

Business logic and orchestration

- [User service](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/service/user_service.go): app service · Coordinates user-related business logic · `internal/service/user_service.go`
- [Product service](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/service/product_service.go): app service · Coordinates product-related business logic · `internal/service/product_service.go`
- [Order service](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/service/order_service.go): app service · Coordinates order lifecycle and ownership rules · `internal/service/order_service.go`
- [Location service](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/service/location_service.go): geo service · Handles tracking and location operations · `internal/service/location_service.go`
- [Geocoding](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/service/geocoding.go): geo logic · Supports location enrichment and lookup logic · `internal/service/geocoding.go`
- [Mappers](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/utils/order_mapper.go): transform · Converts between domain models and DTOs · `internal/utils/order_mapper.go`

### Domain

Core business entities

- [User](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/domain/user.go): entity · Core user model · `internal/domain/user.go`
- [Driver](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/domain/driver.go): entity · Core driver model · `internal/domain/driver.go`
- [Product](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/domain/product.go): entity · Core product model · `internal/domain/product.go`
- [Order](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/domain/order.go): entity · Core order model · `internal/domain/order.go`

### Data

Persistence adapters and data access

- [User repo](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/repository/user_repository.go): repository · Persists and loads users · `internal/repository/user_repository.go`
- [Product repo](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/repository/product_repository.go): repository · Persists and loads products · `internal/repository/product_repository.go`
- [Order repo](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/repository/order_repository.go): repository · Persists and loads orders · `internal/repository/order_repository.go`
- [Location repo](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/repository/location_repository.go): repository · Reads and writes tracking state · `internal/repository/location_repository.go`
- [Init SQL](https://github.com/bertonez/tracking-de-pedidos/blob/main/init.sql): schema init · Initial database bootstrap script · `init.sql`

### Security

Authentication and authorization

- [Middleware](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/middleware/middleware.go): auth guard · Applies request protection and shared HTTP concerns · `internal/middleware/middleware.go`
- [Role guard](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/middleware/role_middleware.go): rbac · Enforces customer and driver access rules · `internal/middleware/role_middleware.go`
- [JWT auth](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/auth/jwt.go): token auth · Validates and issues JWT-based identity · `internal/auth/jwt.go`

### External Systems

Datastores and runtime dependencies

- [PostgreSQL](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/db/postgres.go): sql/postgis · Primary durable store for business data and geospatial queries · `internal/db/postgres.go`
- [Redis](https://github.com/bertonez/tracking-de-pedidos/blob/main/internal/db/redis.go): cache/state · High-frequency tracking state and fast lookups · `internal/db/redis.go`

### Docs

API contract documentation

- [Swagger](https://github.com/bertonez/tracking-de-pedidos/blob/main/docs/swagger.yaml): openapi · Generated API documentation and contract · `docs/swagger.yaml`

### Deploy

Containerization and startup assets

- [Compose](https://github.com/bertonez/tracking-de-pedidos/blob/main/docker-compose.yaml): runtime config · Defines the containerized service stack · `docker-compose.yaml`
- [Dockerfile](https://github.com/bertonez/tracking-de-pedidos/tree/main/dockerfile): image build · Builds the API container image · `dockerfile`

## Connections

- API main → User routes: mounts · Bootstraps route registration
- API main → Product routes: mounts · Bootstraps route registration
- API main → Order routes: mounts · Bootstraps route registration
- API main → PostgreSQL: connects · Initializes persistent storage connection
- API main → Redis: connects · Initializes cache/state connection
- User routes → Middleware: uses · Applies shared request protections
- Product routes → Middleware: uses · Applies shared request protections
- Order routes → Middleware: uses · Applies shared request protections
- Order routes → Role guard: uses · Applies role-based access control
- Middleware → JWT auth: delegates · Validates bearer tokens
- User routes → User handler: maps to · Connects endpoints to HTTP handlers
- Product routes → Product handler: maps to · Connects endpoints to HTTP handlers
- Order routes → Order handler: maps to · Connects endpoints to HTTP handlers
- User handler → User service: calls · Hands off application logic
- Product handler → Product service: calls · Hands off application logic
- Order handler → Order service: calls · Hands off application logic
- Order service → Location service: uses · Coordinates tracking and location behavior
- Location service → Geocoding: uses · Supports geospatial enrichment
- User service → User repo: persists via · Reads and writes user data
- Product service → Product repo: persists via · Reads and writes product data
- Order service → Order repo: persists via · Reads and writes order data
- Order service → Location repo: persists via · Stores and retrieves tracking data
- Location service → Location repo: reads/writes · Manages fast tracking state
- User repo → PostgreSQL: uses · Stores durable user records
- Product repo → PostgreSQL: uses · Stores durable product records
- Order repo → PostgreSQL: uses · Stores durable order records
- Location repo → Redis: uses · Uses Redis for high-frequency tracking
- Location repo → PostgreSQL: uses · Falls back to durable geospatial storage
- User handler → DTOs: serializes · Uses request and response DTOs
- Product handler → DTOs: serializes · Uses request and response DTOs
- Order handler → DTOs: serializes · Uses request and response DTOs
- Mappers → DTOs: converts · Maps between contracts and domain objects
- Mappers → User: converts · Maps domain user data
- Mappers → Product: converts · Maps domain product data
- Mappers → Order: converts · Maps domain order data
- User service → User: operates on · Business logic around users
- Product service → Product: operates on · Business logic around products
- Order service → Order: operates on · Business logic around orders
- Order service → Driver: checks · Uses driver model for fulfillment and access rules
- Swagger → API main: documents · Describes the exposed API
- Compose → Dockerfile: builds with · Container stack includes the API image
- Compose → PostgreSQL: orchestrates · Runs PostgreSQL alongside the API
- Compose → Redis: orchestrates · Runs Redis alongside the API
- Init SQL → PostgreSQL: initializes · Seeds or prepares the database schema
