Microservices - Quick Reference Guide

API Gateway       3000
Auth Service      3001
User Service      3002
Organization Svc  3003
Product Service   3004
Order Service     3005
Analytics Service 3006
Settings Service  3007
Notification Svc  3008
 
Shell MFE         3100
Auth Module       3101
User Module       3102
Organization Mod  3103
Product Module    3104
Order Module      3105
Analytics Module  3106
Admin Module      3107
 
MongoDB           27017
Redis             6379

✓ = Depends On (calls this service)
- = Independent

POST   /register           # Register new user
POST   /login              # User login
POST   /refresh            # Refresh token
GET    /verify             # Verify token
POST   /2fa                # Two-factor auth
DELETE /logout             # User logout
POST   /password-reset     # Request password reset
GET    /health             # Service health

GET    /:id                # Get user profile
PUT    /:id                # Update profile
GET    /:id/profile        # Get detailed profile
PUT    /:id/profile        # Update detailed profile
DELETE /:id                # Delete user
GET    /:id/settings       # Get user settings
PUT    /:id/settings       # Update settings
GET    /health             # Service health

POST   /                   # Create organization
GET    /:id                # Get org details
PUT    /:id                # Update org
DELETE /:id                # Delete org
POST   /:id/members        # Add member
GET    /:id/members        # List members
DELETE /:id/members/:mid   # Remove member
POST   /:id/invites        # Send invite
GET    /:id/invites        # List invites
GET    /health             # Service health

GET    /                   # List products
POST   /                   # Create product
GET    /:id                # Get product
PUT    /:id                # Update product
DELETE /:id                # Delete product
GET    /:id/inventory      # Get inventory
PUT    /:id/inventory      # Update inventory
POST   /categories         # Create category
GET    /categories         # List categories
GET    /search?q=...       # Search products
GET    /health             # Service health

POST   /                   # Create order
GET    /                   # List user orders
GET    /:id                # Get order details
PUT    /:id/status         # Update order status
DELETE /:id                # Cancel order
GET    /:id/history        # Get order history
POST   /:id/payment        # Process payment
POST   /:id/invoice        # Generate invoice
GET    /health             # Service health

GET    /dashboard          # Dashboard metrics
GET    /dashboard/:org     # Org-specific dashboard
GET    /products           # Product analytics
GET    /orders             # Order analytics
GET    /users              # User analytics
POST   /events             # Track event
GET    /audit/logs         # Audit logs
GET    /reports/:type      # Generate report
GET    /health             # Service health

GET    /                   # Get all settings
GET    /:key               # Get specific setting
PUT    /:key               # Update setting
POST   /faq                # Create FAQ
GET    /faq                # List FAQs
PUT    /faq/:id            # Update FAQ
DELETE /faq/:id            # Delete FAQ
GET    /subscription       # Subscription info
GET    /features           # Feature flags
GET    /health             # Service health

# Start all services
docker-compose up -d
 
# View logs
docker-compose logs -f auth  # Single service
docker-compose logs -f       # All services
 
# Stop all
docker-compose down
 
# Rebuild images
docker-compose build
 
# Restart service
docker-compose restart product
 
# Execute command in container
docker-compose exec auth npm test
 
# Remove volumes (full reset)
docker-compose down -v

# 1. Install dependencies
bun install
 
# 2. Start Docker services
docker-compose up -d
 
# 3. Run all services in dev mode
bun dev
 
# 4. In another terminal, start MFE shell
cd micro-frontends/shell && bun dev
 
# Access applications:
# - Frontend: http://localhost:3100
# - API Gateway: http://localhost:3000

# Unit tests (single service)
cd services/auth && bun test
 
# Integration tests (cross-service)
bun run test:integration
 
# End-to-end tests
bun run test:e2e
 
# All tests
bun test

# Run migrations
bun run db:migrate
 
# Generate Prisma types
bun run prisma:generate
 
# Seed database
bun run prisma:seed
 
# Open Prisma Studio
bun run prisma studio

# Request rate
rate(http_requests_total[5m])
 
# Error rate
rate(http_requests_total{status=~"5.."}[5m])
 
# Response time (p95)
histogram_quantile(0.95, http_request_duration_seconds_bucket)
 
# Service availability
up{job="auth-service"}
 
# Database query time
histogram_quantile(0.99, db_query_duration_seconds_bucket)

# Find errors
level:ERROR service:auth
 
# Trace user journey
userId:12345 timestamp:[now-1h TO now]
 
# Database slow queries
duration:>1000 type:database
 
# API timeouts
error:timeout service:order

API Response:        <200ms (p99)
Service Startup:     <30s
Database Query:      <50ms (p99)
Cache Hit Rate:      >80%
Error Rate:          <0.1%
CPU Usage:           60-70% (healthy)
Memory Usage:        70-80% (healthy)
Disk I/O Wait:       <5%
Network Latency:     <50ms between services

# API Gateway
API_GATEWAY_PORT=3000
API_GATEWAY_LOG_LEVEL=info
CORS_ORIGIN=http://localhost:3100
 
# Auth Service
AUTH_SERVICE_PORT=3001
DATABASE_URL=mongodb://auth:auth_db
JWT_SECRET=your-secret-key
JWT_EXPIRE=7d
BCRYPT_ROUNDS=10
 
# User Service
USER_SERVICE_PORT=3002
DATABASE_URL=mongodb://users:users_db
AUTH_SERVICE_URL=http://auth:3001
 
# Product Service
PRODUCT_SERVICE_PORT=3004
DATABASE_URL=mongodb://products:products_db
REDIS_URL=redis://redis:6379
 
# Order Service
ORDER_SERVICE_PORT=3005
DATABASE_URL=mongodb://orders:orders_db
PRODUCT_SERVICE_URL=http://product:3004
EVENT_BUS_URL=redis://redis:6379/1
 
# Database & Cache
MONGODB_URI=mongodb://root:password@mongodb:27017/
REDIS_URL=redis://redis:6379
 
# Notifications (External)
SENDGRID_API_KEY=your-key
TWILIO_ACCOUNT_SID=your-sid
TWILIO_AUTH_TOKEN=your-token
 
# Logging & Monitoring
LOG_LEVEL=info
METRICS_ENABLED=true
TRACING_ENABLED=true

aori-apps/
├── services/                    # Microservices
│   ├── api-gateway/
│   ├── auth/
│   ├── user/
│   ├── product/
│   ├── order/
│   └── ... others
│
├── micro-frontends/            # MFE Modules
│   ├── shell/
│   ├── auth/
│   ├── product/
│   └── ... others
│
├── shared/                     # Shared packages
│   ├── http-client/
│   ├── validators/
│   └── types/
│
├── infrastructure/             # DevOps
│   ├── docker-compose.yml
│   ├── kubernetes/
│   └── terraform/
│
└── docs/                       # Documentation
    ├── architecture/
    ├── deployment/
    └── api-reference/

Frontend → API Gateway → Service → Response
Response Time: <200ms expected
Status Codes: 200, 201, 400, 401, 404, 500

Service → Event Bus (Redis) → Subscriber Services
Flow: Fire & forget, eventual consistency
Message Format: JSON with event type

Service A → HTTP call with auth header → Service B
Circuit Breaker: Enabled (fail fast)
Retry: Exponential backoff (max 3 times)
Cache: Redis for frequent calls

1. Create feature branch from main
2. Implement feature with tests
3. Open Pull Request with descriptions
4. Code review (2 approvals required)
5. Merge to main (auto-triggered)
6. CI/CD builds Docker images
7. Deploy to staging (auto-tested)
8. Manual approval for production
9. Canary deployment (5%)
10. Progressive rollout (25%, 50%, 100%)
11. Monitor for 1+ hours
12. Tag release on GitHub

# Development
bun dev              # Start dev environment
bun build           # Build all packages
bun lint            # Run eslint
bun type-check      # Run tsc
 
# Docker
docker-compose up -d        # Start services
docker-compose logs -f      # View logs
docker-compose down         # Stop services
 
# Database
bun run db:migrate          # Run migrations
bun run prisma:seed         # Seed data
bun run prisma studio       # Open GUI
 
# Testing
bun test            # Run all tests
bun test:watch      # Watch mode
bun test:coverage   # Coverage report
 
# Deployment
kubectl apply -f infrastructure/kubernetes/
kubectl logs -f deployment/auth-service
kubectl rollout undo deployment/auth-service

Response Time (p99):       <200ms  ✓ Good, ✗ Bad >500ms
Error Rate:                <0.1%   ✓ Good, ✗ Bad >1%
Service Uptime:            >99.9%  ✓ Good, ✗ Bad <99%
Deployment Time:           <5m     ✓ Good, ✗ Bad >15m
Mean Time To Recovery:     <15m    ✓ Good, ✗ Bad >1h
Test Coverage:             >80%    ✓ Good, ✗ Bad <60%
CPU Utilization:           60-70%  ✓ Good, ✗ Bad >85%
Memory Utilization:        70-80%  ✓ Good, ✗ Bad >90%