Microservices & Micro-Frontend Architecture Blueprint

apps/
├── main/              → Main portal (Next.js)
├── app/               → Public application (Next.js)
│   ├── landing        → Landing page
│   ├── store          → E-commerce frontend
│   └── warehouse      → Inventory management
├── app/mobile         → Mobile app (React Native/Expo)
├── api                → Backend API (Prisma + MongoDB)
└── docs               → Documentation (Next.js)
 
packages/
├── db                 → Prisma ORM & Database client
├── auth               → Authentication utilities
├── core               → Core business logic (validators, etc)
├── engines            → Business engines
├── permissions        → RBAC utilities
├── helpers            → Helper functions
├── hooks              → React hooks library
├── http-client        → Axios wrapper
├── i18n               → Internationalization
├── components/        → Reusable UI components (web)
├── icons/             → Icon library
├── ui/                → Design system
└── [mobile versions]

1. API Gateway Service
   ├── Port: 3000
   ├── Functions: Request routing, rate limiting, auth validation
   ├── Tech: Node.js + Express/Fastify
   └── Uses: JWT validation, service discovery

2. Auth Service (Port: 3001)
   ├── Domain: User authentication & authorization
   ├── Tables: Account, VerificationToken, PasswordResetToken, TwoFactorToken, TwoFactorConfirmation
   ├── APIs:
   │   POST   /auth/register
   │   POST   /auth/login
   │   POST   /auth/refresh-token
   │   GET    /auth/verify/:token
   │   POST   /auth/2fa
   │   DELETE /auth/logout
   ├── Dependencies: None (independent)
   └── Database: MongoDB (auth_db)
 
3. User Service (Port: 3002)
   ├── Domain: User profiles & preferences
   ├── Tables: User, UserProfile, UserSettings
   ├── APIs:
   │   GET    /users/:id
   │   PUT    /users/:id
   │   GET    /users/:id/profile
   │   PUT    /users/:id/profile
   │   DELETE /users/:id
   ├── Dependencies: Auth Service (token validation)
   └── Database: MongoDB (users_db)
 
4. Organization Service (Port: 3003)
   ├── Domain: Workspace/org management
   ├── Tables: Organization, OrganizationMember, InvitationToken
   ├── APIs:
   │   POST   /orgs
   │   GET    /orgs/:id
   │   PUT    /orgs/:id
   │   POST   /orgs/:id/members
   │   GET    /orgs/:id/members
   │   DELETE /orgs/:id/members/:memberId
   │   POST   /orgs/:id/invites
   ├── Dependencies: Auth Service, User Service
   └── Database: MongoDB (orgs_db)
 
5. Product Service (Port: 3004)
   ├── Domain: Product catalog & inventory
   ├── Tables: Product, Category, ProductImage, Inventory, ProductVariant
   ├── APIs:
   │   GET    /products
   │   POST   /products
   │   GET    /products/:id
   │   PUT    /products/:id
   │   DELETE /products/:id
   │   GET    /products/:id/inventory
   │   POST   /categories
   │   GET    /categories
   ├── Dependencies: Auth Service, Organization Service
   └── Database: MongoDB (products_db)
 
6. Order Service (Port: 3005)
   ├── Domain: Order processing
   ├── Tables: Order, OrderItem, OrderStatus, OrderHistory
   ├── APIs:
   │   POST   /orders
   │   GET    /orders/:id
   │   GET    /orders (user orders)
   │   PUT    /orders/:id/status
   │   GET    /orders/:id/history
   │   POST   /orders/:id/cancel
   ├── Dependencies: Auth Service, Product Service, User Service
   ├── Events: order-created, order-confirmed, order-shipped, order-delivered
   └── Database: MongoDB (orders_db)
 
7. Analytics Service (Port: 3006)
   ├── Domain: Analytics, metrics, reporting
   ├── Tables: Analytics, UserActivity, DashboardMetrics, AuditLog
   ├── APIs:
   │   GET    /analytics/dashboard
   │   GET    /analytics/products
   │   GET    /analytics/orders
   │   GET    /analytics/users
   │   POST   /analytics/events
   │   GET    /audit/logs
   ├── Dependencies: Event stream (Kafka/Redis)
   └── Database: MongoDB (analytics_db) + Time-series database (optional: InfluxDB)
 
8. Settings Service (Port: 3007)
   ├── Domain: Configuration & settings
   ├── Tables: Setting, FAQ, Subscription, FeatureFlag
   ├── APIs:
   │   GET    /settings/:org_id
   │   PUT    /settings/:org_id
   │   GET    /faq
   │   POST   /faq (admin)
   │   PUT    /faq/:id (admin)
   │   DELETE /faq/:id (admin)
   ├── Dependencies: Auth Service, Organization Service
   └── Database: MongoDB (settings_db)
 
9. Notification Service (Port: 3008)
   ├── Domain: Email, SMS, push notifications
   ├── APIs:
   │   POST   /notifications/email
   │   POST   /notifications/sms
   │   POST   /notifications/push
   │   GET    /notifications/:user_id
   ├── Dependencies: Event stream
   └── External: SendGrid, Twilio, Firebase Cloud Messaging

10. Event Service (Message Broker)
    ├── Technology: Redis (dev) / RabbitMQ or Kafka (prod)
    ├── Port: 6379 (Redis) or 5672 (RabbitMQ)
    ├── Purpose: Async communication, event streaming
 
11. Cache Service
    ├── Technology: Redis
    ├── Port: 6380
    ├── Purpose: Session caching, rate limiting
 
12. Search Service (Optional)
    ├── Technology: Elasticsearch/MeiliSearch
    ├── Port: 9200
    ├── Purpose: Full-text search for products

micro-frontends/
├── shell (Port: 3100)
│   ├── Layout & routing orchestration
│   ├── Header, Navigation, Footer
│   ├── Module loader & error boundary
│   └── Global state (theme, language)
│
├── auth-module (Port: 3101)
│   ├── Login, Register, 2FA
│   ├── Password reset
│   ├── OAuth integration
│   └── Shared with: All modules (auth boundary)
│
├── user-module (Port: 3102)
│   ├── User profile
│   ├── Settings
│   ├── Preferences
│   └── APIs: User Service
│
├── organization-module (Port: 3103)
│   ├── Organization dashboard
│   ├── Member management
│   ├── Invite management
│   └── APIs: Organization Service
│
├── product-module (Port: 3104)
│   ├── Product catalog
│   ├── Search & filter
│   ├── Product detail
│   ├── Category browser
│   └── APIs: Product Service
│
├── order-module (Port: 3105)
│   ├── Order creation
│   ├── Order history
│   ├── Order tracking
│   ├── Cart management
│   └── APIs: Order Service
│
├── analytics-module (Port: 3106)
│   ├── Dashboard & charts
│   ├── Reports
│   ├── Metrics display
│   └── APIs: Analytics Service
│
└── admin-module (Port: 3107)
    ├── Admin dashboard
    ├── FAQ management
    ├── Settings management
    ├── Subscription management
    └── APIs: Settings Service + others

auth_db (MongoDB)
├── Account
├── VerificationToken
├── PasswordResetToken
├── TwoFactorToken
├── TwoFactorConfirmation
 
users_db (MongoDB)
├── User (subset: id, email, name, role)
├── UserProfile
├── UserSettings
 
orgs_db (MongoDB)
├── Organization
├── OrganizationMember
├── InvitationToken
 
products_db (MongoDB)
├── Product
├── Category
├── ProductImage
├── Inventory
├── ProductVariant
 
orders_db (MongoDB)
├── Order
├── OrderItem
├── OrderStatus
├── OrderHistory
 
analytics_db (MongoDB) + Optional InfluxDB
├── Analytics
├── UserActivity
├── DashboardMetrics
├── AuditLog
 
settings_db (MongoDB)
├── Setting
├── FAQ
├── Subscription
├── FeatureFlag

API Gateway (Port 3000)
├── /api/auth        → Auth Service (3001)
├── /api/users       → User Service (3002)
├── /api/orgs        → Organization Service (3003)
├── /api/products    → Product Service (3004)
├── /api/orders      → Order Service (3005)
├── /api/analytics   → Analytics Service (3006)
├── /api/settings    → Settings Service (3007)
└── /api/notify      → Notification Service (3008)

version: '3.8'
 
services:
  # API Gateway
  api-gateway:
    build:
      context: ./services/api-gateway
      dockerfile: Dockerfile
    ports:
      - '3000:3000'
    environment:
      NODE_ENV: development
      AUTH_SERVICE_URL: http://auth:3001
      USER_SERVICE_URL: http://user:3002
      ORG_SERVICE_URL: http://org:3003
      PRODUCT_SERVICE_URL: http://product:3004
      ORDER_SERVICE_URL: http://order:3005
      ANALYTICS_SERVICE_URL: http://analytics:3006
      SETTINGS_SERVICE_URL: http://settings:3007
      NOTIFY_SERVICE_URL: http://notify:3008
    depends_on:
      - redis
    networks:
      - aori-network
 
  # Auth Service
  auth:
    build:
      context: ./services/auth
      dockerfile: Dockerfile
    ports:
      - '3001:3001'
    environment:
      NODE_ENV: development
      DATABASE_URL: mongodb://mongodb:27017/auth_db
      JWT_SECRET: ${JWT_SECRET:-your-secret-key}
      REDIS_URL: redis://redis:6379
    depends_on:
      - mongodb
      - redis
    networks:
      - aori-network
    volumes:
      - ./services/auth/src:/app/src
 
  # User Service
  user:
    build:
      context: ./services/user
      dockerfile: Dockerfile
    ports:
      - '3002:3002'
    environment:
      NODE_ENV: development
      DATABASE_URL: mongodb://mongodb:27017/users_db
      AUTH_SERVICE_URL: http://auth:3001
      REDIS_URL: redis://redis:6379
    depends_on:
      - mongodb
      - redis
      - auth
    networks:
      - aori-network
    volumes:
      - ./services/user/src:/app/src
 
  # Organization Service
  org:
    build:
      context: ./services/org
      dockerfile: Dockerfile
    ports:
      - '3003:3003'
    environment:
      NODE_ENV: development
      DATABASE_URL: mongodb://mongodb:27017/orgs_db
      AUTH_SERVICE_URL: http://auth:3001
      USER_SERVICE_URL: http://user:3002
      REDIS_URL: redis://redis:6379
    depends_on:
      - mongodb
      - redis
      - auth
      - user
    networks:
      - aori-network
    volumes:
      - ./services/org/src:/app/src
 
  # Product Service
  product:
    build:
      context: ./services/product
      dockerfile: Dockerfile
    ports:
      - '3004:3004'
    environment:
      NODE_ENV: development
      DATABASE_URL: mongodb://mongodb:27017/products_db
      AUTH_SERVICE_URL: http://auth:3001
      ORG_SERVICE_URL: http://org:3003
      REDIS_URL: redis://redis:6379
      EVENT_BUS_URL: redis://redis:6379/1
    depends_on:
      - mongodb
      - redis
    networks:
      - aori-network
    volumes:
      - ./services/product/src:/app/src
 
  # Order Service
  order:
    build:
      context: ./services/order
      dockerfile: Dockerfile
    ports:
      - '3005:3005'
    environment:
      NODE_ENV: development
      DATABASE_URL: mongodb://mongodb:27017/orders_db
      AUTH_SERVICE_URL: http://auth:3001
      USER_SERVICE_URL: http://user:3002
      PRODUCT_SERVICE_URL: http://product:3004
      REDIS_URL: redis://redis:6379
      EVENT_BUS_URL: redis://redis:6379/1
    depends_on:
      - mongodb
      - redis
      - auth
      - user
      - product
    networks:
      - aori-network
    volumes:
      - ./services/order/src:/app/src
 
  # Analytics Service
  analytics:
    build:
      context: ./services/analytics
      dockerfile: Dockerfile
    ports:
      - '3006:3006'
    environment:
      NODE_ENV: development
      DATABASE_URL: mongodb://mongodb:27017/analytics_db
      AUTH_SERVICE_URL: http://auth:3001
      REDIS_URL: redis://redis:6379
      EVENT_BUS_URL: redis://redis:6379/1
    depends_on:
      - mongodb
      - redis
      - auth
    networks:
      - aori-network
    volumes:
      - ./services/analytics/src:/app/src
 
  # Settings Service
  settings:
    build:
      context: ./services/settings
      dockerfile: Dockerfile
    ports:
      - '3007:3007'
    environment:
      NODE_ENV: development
      DATABASE_URL: mongodb://mongodb:27017/settings_db
      AUTH_SERVICE_URL: http://auth:3001
      REDIS_URL: redis://redis:6379
    depends_on:
      - mongodb
      - redis
      - auth
    networks:
      - aori-network
    volumes:
      - ./services/settings/src:/app/src
 
  # Notification Service
  notify:
    build:
      context: ./services/notify
      dockerfile: Dockerfile
    ports:
      - '3008:3008'
    environment:
      NODE_ENV: development
      DATABASE_URL: mongodb://mongodb:27017/notify_db
      SENDGRID_API_KEY: ${SENDGRID_API_KEY}
      TWILIO_ACCOUNT_SID: ${TWILIO_ACCOUNT_SID}
      TWILIO_AUTH_TOKEN: ${TWILIO_AUTH_TOKEN}
      REDIS_URL: redis://redis:6379
      EVENT_BUS_URL: redis://redis:6379/1
    depends_on:
      - redis
    networks:
      - aori-network
    volumes:
      - ./services/notify/src:/app/src
 
  # Micro-Frontend: Shell
  shell:
    build:
      context: ./micro-frontends/shell
      dockerfile: Dockerfile
    ports:
      - '3100:3000'
    environment:
      NODE_ENV: development
      API_GATEWAY_URL: http://localhost:3000
    depends_on:
      - api-gateway
    networks:
      - aori-network
    volumes:
      - ./micro-frontends/shell/src:/app/src
 
  # Micro-Frontend: Auth Module
  auth-module:
    build:
      context: ./micro-frontends/auth
      dockerfile: Dockerfile
    ports:
      - '3101:3000'
    environment:
      NODE_ENV: development
      API_GATEWAY_URL: http://localhost:3000
    networks:
      - aori-network
    volumes:
      - ./micro-frontends/auth/src:/app/src
 
  # Micro-Frontend: Product Module
  product-module:
    build:
      context: ./micro-frontends/product
      dockerfile: Dockerfile
    ports:
      - '3104:3000'
    environment:
      NODE_ENV: development
      API_GATEWAY_URL: http://localhost:3000
    networks:
      - aori-network
    volumes:
      - ./micro-frontends/product/src:/app/src
 
  # Micro-Frontend: Order Module
  order-module:
    build:
      context: ./micro-frontends/order
      dockerfile: Dockerfile
    ports:
      - '3105:3000'
    environment:
      NODE_ENV: development
      API_GATEWAY_URL: http://localhost:3000
    networks:
      - aori-network
    volumes:
      - ./micro-frontends/order/src:/app/src
 
  # Databases
  mongodb:
    image: mongo:7
    ports:
      - '27017:27017'
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD:-password}
    volumes:
      - mongodb_data:/data/db
    networks:
      - aori-network
    healthcheck:
      test: ['CMD', 'mongosh', '--eval', "db.adminCommand('ping')"]
      interval: 10s
      timeout: 5s
      retries: 5
 
  # Cache & Event Bus
  redis:
    image: redis:7-alpine
    ports:
      - '6379:6379'
    volumes:
      - redis_data:/data
    networks:
      - aori-network
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 5s
      retries: 5
 
volumes:
  mongodb_data:
  redis_data:
 
networks:
  aori-network:
    driver: bridge

FROM node:20-alpine
 
WORKDIR /app
 
# Install dependencies
COPY package*.json bun.lock* ./
RUN npm install -g bun && bun install --frozen-lockfile
 
# Copy source code
COPY src ./src
COPY tsconfig.json ./
COPY .env* ./
 
# Build if needed (optional for development)
# RUN bun run build
 
# Expose port
EXPOSE 3001
 
# Start service
CMD ["bun", "run", "src/index.ts"]

# API Gateway
API_GATEWAY_PORT=3000
 
# Services
AUTH_SERVICE_PORT=3001
USER_SERVICE_PORT=3002
ORG_SERVICE_PORT=3003
PRODUCT_SERVICE_PORT=3004
ORDER_SERVICE_PORT=3005
ANALYTICS_SERVICE_PORT=3006
SETTINGS_SERVICE_PORT=3007
NOTIFY_SERVICE_PORT=3008
 
# Database
DATABASE_URL=mongodb://root:password@mongodb:27017/
MONGODB_URI=mongodb://root:password@mongodb:27017/
 
# Cache & Events
REDIS_URL=redis://redis:6379
EVENT_BUS_URL=redis://redis:6379/1
 
# Security
JWT_SECRET=your-very-secure-secret-key-change-in-production
JWT_EXPIRE=7d
 
# Notifications
SENDGRID_API_KEY=your-sendgrid-key
TWILIO_ACCOUNT_SID=your-twilio-sid
TWILIO_AUTH_TOKEN=your-twilio-token
 
# Environment
NODE_ENV=development
LOG_LEVEL=debug

┌─────────────────────────────────────────────────────────────┐
│                    Docker Network: aori-network             │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Localhost Port Mapping (Developer Machine)           │  │
│  │                                                       │  │
│  │  3000  → API Gateway (routing)                        │  │
│  │  3001  → Auth Service                                 │  │
│  │  3002  → User Service                                 │  │
│  │  3003  → Organization Service                         │  │
│  │  3004  → Product Service                              │  │
│  │  3005  → Order Service                                │  │
│  │  3006  → Analytics Service                            │  │
│  │  3007  → Settings Service                             │  │
│  │  3008  → Notification Service                         │  │
│  │                                                       │  │
│  │  3100  → Shell (MFE)                                  │  │
│  │  3101  → Auth Module (MFE)                            │  │
│  │  3102  → User Module (MFE)                            │  │
│  │  3104  → Product Module (MFE)                         │  │
│  │  3105  → Order Module (MFE)                           │  │
│  │  3106  → Analytics Module (MFE)                       │  │
│  │  3107  → Admin Module (MFE)                           │  │
│  │                                                       │  │
│  │  27017 → MongoDB                                      │  │
│  │  6379  → Redis                                        │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────┐
│                  Kubernetes Cluster                       │
│                                                           │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  Ingress Controller (nginx-ingress)                 │  │
│  │  ├─ /api/*         → API Gateway Service            │  │
│  │  ├─ /shell/*       → Shell MFE                      │  │
│  │  └─ /auth/*        → Auth Module MFE                │  │
│  └─────────────────────────────────────────────────────┘  │
│                      ▼                                    │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  Service Mesh (Istio) - Optional                    │  │
│  │  ├─ Traffic management                              │  │
│  │  ├─ Security policies                               │  │
│  │  └─ Observability                                   │  │
│  └─────────────────────────────────────────────────────┘  │
│                      ▼                                    │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  Services (Deployments with auto-scaling)           │  │
│  │  ├─ auth-service (replicas: 2-5)                    │  │
│  │  ├─ user-service (replicas: 2-5)                    │  │
│  │  ├─ product-service (replicas: 2-5)                 │  │
│  │  ├─ order-service (replicas: 3-10)                  │  │
│  │  ├─ api-gateway (replicas: 2-5)                     │  │
│  │  └─ ...other services                               │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  StatefulSets & PersistentVolumes                   │  │
│  │  ├─ MongoDB (replicas: 3 - ReplicaSet)              │  │
│  │  ├─ Redis (cache & event bus)                       │  │
│  │  └─ Elasticsearch (optional search)                 │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  Monitoring & Observability                         │  │
│  │  ├─ Prometheus (metrics)                            │  │
│  │  ├─ Grafana (dashboards)                            │  │
│  │  ├─ ELK Stack (logging)                             │  │
│  │  └─ Jaeger (distributed tracing)                    │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  CI/CD Integration                                  │  │
│  │  ├─ GitHub Actions / GitLab CI                      │  │
│  │  ├─ Automated testing on each push                  │  │
│  │  ├─ Docker image building & registry                │  │
│  │  ├─ ArgoCD for GitOps deployment                    │  │
│  │  └─ Automated rollback on failure                   │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘

name: CI/CD Pipeline
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: oven-sh/setup-bun@v1
 
      - name: Install dependencies
        run: bun install --frozen-lockfile
 
      - name: Lint
        run: bun run lint
 
      - name: Type check
        run: bun run type-check
 
      - name: Unit tests
        run: bun run test
 
      - name: Build services
        run: bun run build
 
  build-and-push:
    needs: test
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service: [api-gateway, auth, user, org, product, order, analytics, settings, notify]
 
    steps:
      - uses: actions/checkout@v3
 
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2
 
      - name: Login to Docker Hub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
 
      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          context: ./services/${{ matrix.service }}
          push: true
          tags: |
            ${{ secrets.DOCKER_REGISTRY }}/aori-${{ matrix.service }}:${{ github.sha }}
            ${{ secrets.DOCKER_REGISTRY }}/aori-${{ matrix.service }}:latest
 
  deploy:
    needs: build-and-push
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Kubernetes
        run: |
          kubectl set image deployment/auth-service \
            auth-service=${{ secrets.DOCKER_REGISTRY }}/aori-auth:${{ github.sha }} \
            --record
          # Repeat for other services...

Service A → [Circuit Breaker] → Service B
 
States: CLOSED (normal) → OPEN (failing) → HALF_OPEN (testing recovery)

aori-apps/
├── services/                          # Microservices
│   ├── api-gateway/
│   │   ├── src/
│   │   ├── Dockerfile
│   │   └── package.json
│   ├── auth/
│   ├── user/
│   ├── org/
│   ├── product/
│   ├── order/
│   ├── analytics/
│   ├── settings/
│   └── notify/
│
├── micro-frontends/                   # Micro-Frontend Apps
│   ├── shell/                         # Main orchestrator
│   ├── auth-module/
│   ├── user-module/
│   ├── org-module/
│   ├── product-module/
│   ├── order-module/
│   ├── analytics-module/
│   └── admin-module/
│
├── shared/                            # Shared packages
│   ├── http-client/                   # HTTP client library
│   ├── validators/                    # Shared validators
│   ├── constants/                     # Shared constants
│   ├── types/                         # Shared TypeScript types
│   └── utils/                         # Shared utilities
│
├── infrastructure/                    # Infrastructure as Code
│   ├── docker-compose.yml
│   ├── kubernetes/
│   │   ├── namespaces.yaml
│   │   ├── deployments/
│   │   ├── services/
│   │   ├── ingress.yaml
│   │   └── config-maps.yaml
│   ├── terraform/
│   └── github/
│
├── docs/                              # Documentation
│   ├── architecture/
│   ├── deployment/
│   ├── development/
│   └── api-reference/
│
├── tools/                             # Development tools
│   ├── scripts/
│   └── cli/
│
├── .github/workflows/                 # CI/CD
│   └── ci-cd.yml
│
├── docker-compose.yml
├── .env.example
├── package.json                       # Root workspace config
└── README.md