How bertonez/tracking-de-pedidos works
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: order_service.go Order service · main.go API main · postgres.go PostgreSQL · order_mapper.go Mappers
Components 31
Entry
Application bootstrap and process startup
- API main · Starts the HTTP server and wires dependencies
cmd/api/main.go
HTTP API
Request handling, routing, and transport concerns
- User routes · Registers user endpoints and middleware
internal/routes/user_routes.go - Product routes · Registers product endpoints and middleware
internal/routes/product_routes.go - Order routes · Registers order endpoints and middleware
internal/routes/order_routes.go - User handler · Translates user requests and responses
internal/handler/user_handler.go - Product handler · Translates product requests and responses
internal/handler/product_handler.go - Order handler · Translates order requests and responses
internal/handler/order_handler.go - DTOs · Request and response shapes for the API
internal/dto/user_dto.go
Application
Business logic and orchestration
- User service · Coordinates user-related business logic
internal/service/user_service.go - Product service · Coordinates product-related business logic
internal/service/product_service.go - Order service · Coordinates order lifecycle and ownership rules
internal/service/order_service.go - Location service · Handles tracking and location operations
internal/service/location_service.go - Geocoding · Supports location enrichment and lookup logic
internal/service/geocoding.go - Mappers · Converts between domain models and DTOs
internal/utils/order_mapper.go
Domain
Core business entities
Data
Persistence adapters and data access
- User repo · Persists and loads users
internal/repository/user_repository.go - Product repo · Persists and loads products
internal/repository/product_repository.go - Order repo · Persists and loads orders
internal/repository/order_repository.go - Location repo · Reads and writes tracking state
internal/repository/location_repository.go - Init SQL · Initial database bootstrap script
init.sql
Security
Authentication and authorization
- Middleware · Applies request protection and shared HTTP concerns
internal/middleware/middleware.go - Role guard · Enforces customer and driver access rules
internal/middleware/role_middleware.go - JWT auth · Validates and issues JWT-based identity
internal/auth/jwt.go
External Systems
Datastores and runtime dependencies
- PostgreSQL · Primary durable store for business data and geospatial queries
internal/db/postgres.go - Redis · High-frequency tracking state and fast lookups
internal/db/redis.go
Deploy
Containerization and startup assets
- Compose · Defines the containerized service stack
docker-compose.yaml - Dockerfile · Builds the API container image
dockerfile
Connections 44
- 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