JK
>CARGANDO // CARGANDO
INICIALIZANDO VISTA
Completadonestjspostgrestypescriptjesteslintdockergithubactionspostmanswagger
Backend de Microservicios
Arquitectura de microservicios con NestJS, PostgreSQL y Docker que soporta servicios de productos y pedidos a través de un API Gateway centralizado.
Problema y solución
Demuestra una arquitectura empresarial desacoplada entre el enrutamiento (API Gateway), la lógica de dominio (servicios independientes) y la persistencia de datos (PostgreSQL), permitiendo despliegues y escalado independientes.
Características
- Arquitectura de microservicios con servicios independientes de Producto y Pedido
- API Gateway para enrutamiento centralizado y seguridad
- Base de datos PostgreSQL con orquestación Docker
- Monorepo gestionado con TurboRepo
- Pipeline CI/CD con GitHub Actions y despliegues automáticos a Docker Hub
- Pruebas unitarias completas con Jest
Stack tecnológico
| Tecnología | Versión | Propósito | Por qué se eligió |
|---|---|---|---|
| TypeScript | ^5.7.3 | Primary language for all services | Type safety, NestJS ecosystem standard |
| NestJS | ^11.0.1 | Application framework | Modular architecture, dependency injection, TypeScript-first |
| TypeORM | ^0.3.27 | ORM for PostgreSQL access | Active Record/Repository pattern, NestJS integration |
| PostgreSQL | 15 | Primary database | JSONB support, ACID compliance, reliability |
| Docker | — | Containerization for all services | Consistent environments, reproducible deployments |
| Turborepo | ^2.5.8 | Monorepo task orchestration | Fast parallel builds, caching, npm workspaces integration |
| GitHub Actions | — | CI/CD pipeline execution | Free for public repos, tight Git integration |
| Jest | ^30.0.0 | Unit testing framework | NestJS default, snapshot support |
| Swagger | ^11.2.0 | API documentation | Auto-generates OpenAPI from decorators |
Arquitectura
Core System Components
- API Gateway for routing requests to internal services
- Products & Orders service as independent NestJS services
- Docker Compose orchestration
- PostgreSQL container
Infrastructure
- GitHub Actions CI (lint, test, build)
- Docker Hub CD image deployment
- Environment variable management
Estructura del proyecto
.github
workflows
apps
api-gateway
orders-service
products-service
libs
common
docker-compose.yml
Endpoints de API
API Gateway (puerto 3000)
| Método | Ruta | Propósito |
|---|---|---|
| GET | /products | List all products |
| GET | /products/:id | Get product by ID |
| POST | /products | Create product |
| PATCH | /products/:id | Update product |
| DELETE | /products/:id | Delete product |
| GET | /orders | List all orders |
| GET | /orders/:id | Get order by ID |
| POST | /orders | Create order |
Products Service (puerto 3001)
| Método | Ruta | Propósito |
|---|---|---|
| POST | /products | Create product |
| GET | /products | List all products |
| GET | /products/:id | Get product by ID |
| PATCH | /products/:id | Update product |
| DELETE | /products/:id | Delete product |
Orders Service (puerto 3002)
| Método | Ruta | Propósito |
|---|---|---|
| POST | /orders | Create order |
| GET | /orders | List all orders |
| GET | /orders/:id | Get order by ID |
Diseño de base de datos
product
| Columna | Tipo | Notas |
|---|---|---|
| idPK | SERIAL | Auto-generated primary key |
| code | VARCHAR | Product SKU/code |
| name | VARCHAR | Product display name |
| description | VARCHAR | Product description |
| price | DECIMAL | Product price |
| image | VARCHAR | Image URL |
No explicit indexes beyond primary key. No unique constraints on code.
order
| Columna | Tipo | Notas |
|---|---|---|
| idPK | SERIAL | Auto-generated primary key |
| customer | JSONB | Stores {name, phone} |
| products | JSONB | Array of {id, name, rate, qty} |
| totalAmount | DECIMAL | Total order amount |
Products stored as JSONB snapshot — intentional denormalization. No foreign keys to product table.
No foreign key relationships. Order.products is a JSONB snapshot — orders are self-contained records that do not reference the product table. Product price changes do not affect existing orders.
Decisiones de diseño clave
Shared PostgreSQL Database
Decisión: Both services connect to the same PostgreSQL instance and database (procura_db)
Motivo: Simplifies development and deployment — one database to manage
Beneficios: Simpler infrastructure, lower resource usage, easier local development
Compensaciones: Violates database-per-service principle, creates hidden coupling, makes independent scaling harder
JSONB for Order Products
Decisión: Order entity stores product data as JSONB rather than foreign key references
Motivo: Decouples order data from product lifecycle — orders are immutable snapshots
Beneficios: Orders are self-contained, product changes don't affect historical orders
Compensaciones: No referential integrity, data duplication, no automatic product validation on order creation
API Key Authentication
Decisión: Simple static API key in x-api-key header, compared against environment variable
Motivo: Simplest possible authentication for demonstration purposes
Beneficios: Minimal implementation, no token management, no state
Compensaciones: No user identity, no fine-grained permissions, key is static and shared
HTTP-based Inter-service Communication
Decisión: API Gateway communicates with downstream services via synchronous HTTP (Axios)
Motivo: Simplest approach for synchronous request-response pattern
Beneficios: Easy to understand, debug, and test; standard HTTP tooling
Compensaciones: Synchronous coupling, no retry/circuit breaker, no async processing
Multi-stage Docker Builds
Decisión: Each service uses a 3-stage Dockerfile (deps → builder → runner)
Motivo: Minimizes final image size and attack surface
Beneficios: Production images contain only runtime dependencies and compiled code
Compensaciones: Build time for each stage, no layer caching optimization for src changes
TypeORM synchronize: true
Decisión: Both services use synchronize: true in TypeORM config
Motivo: Auto-creates/updates database schema from entities during development
Beneficios: No migration files needed, schema stays in sync with code
Compensaciones: Dangerous in production — can cause data loss on schema changes
Pruebas
Jest ^30.0.0 with ts-jest ^29.2.5•34 pruebas unitarias
Qué se prueba
- API Gateway: root health check, all proxy operations (products + orders)
- Products Service: controller methods (create, findAll, findOne, update, remove)
- Products Service: service methods (create, findAll, findOne, update, remove)
- Orders Service: controller methods (create, findAll, findOne, id conversion)
- Orders Service: service methods (create, findAll, findOne)
Cobertura faltante
- Integration tests with real database
- API Gateway ↔ Service integration tests
- Middleware tests for API key validation
- Validation error scenario tests
- Error path tests (404, 500 scenarios)
Desafíos clave
- Coordinar múltiples servicios garantizando aislamiento de fallos
- Configuración de pipelines CI/CD para compilación de múltiples imágenes Docker
- Gestión limpia de variables de entorno dentro de contenedores
Aprendizajes clave
- Patrones de API Gateway para puntos de entrada unificados y proxy de peticiones
- Redes de contenedores y orquestación multi-servicio con Docker Compose
- Flujos automatizados de imágenes Docker mediante GitHub Actions