JK
>LOADING // LOADING
INITIALIZING VIEW
Completednestjspostgrestypescriptjesteslintdockergithubactionspostmanswagger
Microservice Backend
Microservices backend built with NestJS, PostgreSQL, and Docker supporting product and order services via an API Gateway with CI/CD pipelines using GitHub Actions.
Problem & Solution
Demonstrates a production-like microservices architecture with proper separation of concerns between routing (API Gateway), domain logic (Products/Orders services), and data persistence (PostgreSQL). Each service can be built, tested, and deployed independently — suitable for small-to-medium e-commerce backends where product catalog and order management are core domains.
Features
- Microservices architecture with Product & Order services
- API Gateway for centralized routing
- PostgreSQL database with Docker orchestration
- TurboRepo-based monorepo structure
- GitHub Actions CI/CD with automated Docker Hub deployments
- Jest unit testing
Tech Stack
| Technology | Version | Purpose | Why Chosen |
|---|---|---|---|
| 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 |
Architecture
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
Project Structure
.github
workflows
apps
api-gateway
orders-service
products-service
libs
common
docker-compose.yml
API Endpoints
API Gateway (port 3000)
| Method | Route | Purpose |
|---|---|---|
| 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 (port 3001)
| Method | Route | Purpose |
|---|---|---|
| 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 (port 3002)
| Method | Route | Purpose |
|---|---|---|
| POST | /orders | Create order |
| GET | /orders | List all orders |
| GET | /orders/:id | Get order by ID |
Database Design
product
| Column | Type | Notes |
|---|---|---|
| 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
| Column | Type | Notes |
|---|---|---|
| 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.
Key Design Decisions
Shared PostgreSQL Database
Decision: Both services connect to the same PostgreSQL instance and database (procura_db)
Why: Simplifies development and deployment — one database to manage
Benefits: Simpler infrastructure, lower resource usage, easier local development
Trade-offs: Violates database-per-service principle, creates hidden coupling, makes independent scaling harder
JSONB for Order Products
Decision: Order entity stores product data as JSONB rather than foreign key references
Why: Decouples order data from product lifecycle — orders are immutable snapshots
Benefits: Orders are self-contained, product changes don't affect historical orders
Trade-offs: No referential integrity, data duplication, no automatic product validation on order creation
API Key Authentication
Decision: Simple static API key in x-api-key header, compared against environment variable
Why: Simplest possible authentication for demonstration purposes
Benefits: Minimal implementation, no token management, no state
Trade-offs: No user identity, no fine-grained permissions, key is static and shared
HTTP-based Inter-service Communication
Decision: API Gateway communicates with downstream services via synchronous HTTP (Axios)
Why: Simplest approach for synchronous request-response pattern
Benefits: Easy to understand, debug, and test; standard HTTP tooling
Trade-offs: Synchronous coupling, no retry/circuit breaker, no async processing
Multi-stage Docker Builds
Decision: Each service uses a 3-stage Dockerfile (deps → builder → runner)
Why: Minimizes final image size and attack surface
Benefits: Production images contain only runtime dependencies and compiled code
Trade-offs: Build time for each stage, no layer caching optimization for src changes
TypeORM synchronize: true
Decision: Both services use synchronize: true in TypeORM config
Why: Auto-creates/updates database schema from entities during development
Benefits: No migration files needed, schema stays in sync with code
Trade-offs: Dangerous in production — can cause data loss on schema changes
Testing
Jest ^30.0.0 with ts-jest ^29.2.5•34 unit tests
What's Tested
- 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)
Missing Coverage
- 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)
Key Challenges
- Coordinating multiple services while ensuring fault isolation
- Setting up CI/CD pipelines for multi-image Docker builds
- Managing environment variables cleanly inside Docker
Key Learnings
- Effective use of API Gateway pattern
- Advanced Docker container orchestration with dependencies
- Dependency isolation using monorepo tooling (TurboRepo)