@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/architecture/overview.mdx

@@ -0,0 +1,776 @@
+---
+title: Architecture Overview
+description: Comprehensive overview of the Blue Alba Platform architecture - gateway, microservices, micro-frontends, and technology stack
+sidebar:
+  order: 0
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem, Code } from '@astrojs/starlight/components';
+import { Zoom } from 'starlight-image-zoom/components';
+import MermaidDiagram from '~/components/MermaidDiagram.astro';
+import ExcalidrawDiagram from '~/components/ExcalidrawDiagram.astro';
+import highestLevelLayers from '~/assets/architecture/highest-level-layers.excalidraw';
+import mediumLevelLayers from '~/assets/architecture/medium-level-layers.excalidraw';
+
+The Blue Alba Platform is a sophisticated, enterprise-grade application platform built on modern architectural patterns. It can be logically understood as a set of layers where lower levels provide the foundation and architecture resolving cross-cutting concerns, while upper layers focus on enabling business functionality and use cases.
+
+<Aside type="tip">
+  All diagrams on this page support zoom and pan. Use the zoom controls or hold Ctrl/Cmd and scroll to zoom. Click and drag to pan around larger diagrams. Click the code icon to view or copy the raw Mermaid source.
+</Aside>
+
+## Architectural View
+
+This is the highest-level overview of the Platform.
+
+<ExcalidrawDiagram diagram={highestLevelLayers} title="Platform Layers - Highest Level" height="400px" />
+
+These layers contain different elements that can be zoomed in.
+
+<ExcalidrawDiagram diagram={mediumLevelLayers} title="Platform Layers - Medium Level" height="600px" />
+
+Applications are business-related logical units that might contain one or more microservices (APIs, cron jobs, batch processing, etc.) as well as micro-frontend UI elements.
+
+This document provides a comprehensive overview of the system architecture, design principles, and technology choices.
+
+## Architectural Vision
+
+The Blue Alba Platform is designed to be:
+
+- **Modular**: Composed of independent, deployable services and UIs
+- **Scalable**: Horizontally scalable microservices and micro-frontends
+- **Secure**: Multi-layered security with authentication, authorization, and tenant isolation
+- **Extensible**: Plugin-based architecture for custom applications and services
+- **Multi-Tenant**: Complete data and configuration isolation per tenant
+- **Developer-Friendly**: Rich tooling, clear conventions, and comprehensive SDKs
+
+---
+
+## Platform Topology
+
+The platform is organized as a set of layers: an optional reverse proxy terminates SSL, the gateway handles authentication, authorization, and routing, UI micro-frontends and backend microservices sit behind it, and shared infrastructure (PostgreSQL) is accessed by both the gateway and services. A one-time bootstrap process provisions the catalog and initial configuration via the gateway API.
+
+Client services never communicate directly with each other — all inter-service calls are routed through the gateway using an API Key. Platform internal services (Bootstrap, Rooms, etc.) use the `SERVICE_ACCESS_SECRET` instead, which is reserved for platform-owned components.
+
+<MermaidDiagram
+  title="Platform Topology"
+  height="600px"
+  code={`---
+config:
+  layout: elk
+  theme: neutral
+---
+flowchart LR
+ subgraph MFE["Microfrontends"]
+        Shell(["SHELL UI"])
+        Admin["ADMIN UI"]
+        DocUI["DOCUMENTATION UI"]
+        ClientUI["Client UIs"]
+  end
+ subgraph PLATFORM["Platform services"]
+        Rooms(["Rooms Service"])
+  end
+ subgraph CLIENT_SVCS["Client services"]
+        Bootstrap(["Bootstrap Service"])
+        CSvc1["Client service 1"]
+        CSvc2["Client service 2"]
+  end
+ subgraph CLUSTER["Cluster — Catalog"]
+        GW["Gateway"]
+        MFE
+        PLATFORM
+        CLIENT_SVCS
+  end
+    Admin -- Mount at --> Shell
+    DocUI -- Mount at --> Shell
+    ClientUI -- Mount at --> Shell
+    GW -- "Server side rendering\\nIndex.html" --> Shell
+    GW -- routing --> Rooms & CSvc1 & CSvc2
+    Bootstrap -- SERVICE_ACCESS_SECRET --> GW
+    Browser["BROWSER"] -- JWT Cookie --> GW
+    APIClient["API Client"] -- API Key --> GW
+    ClientSvcA["Client Service A"] -- "API Key\\n(inter-service call)" --> GW`}
+/>
+
+---
+
+## High-Level Architecture
+
+<MermaidDiagram
+  title="Blue Alba Platform - High-Level Architecture"
+  height="600px"
+  code={`flowchart LR
+ subgraph CLIENT["CLIENT LAYER"]
+        Browser["Browser"]
+        API["API Client"]
+  end
+ subgraph GATEWAY["GATEWAY LAYER"]
+        PAE["Gateway Service<br>• HTTP/2 & WebSocket Support<br>• Authentication & Authorization<br>• Request Routing & Proxying<br>• Tenant Context Resolution<br>• Platform Context Management<br>• Catalog Integration"]
+  end
+ subgraph UI["UI LAYER"]
+        Shell["Shell UI"]
+        Admin["Admin UI"]
+        Custom["Custom UIs"]
+  end
+ subgraph SERVICES["SERVICE LAYER"]
+        Scheduler["Scheduler Service<br>"]
+        CustomSvc["Custom Services<br>"]
+  end
+ subgraph FUNCTIONS["FUNCTIONS"]
+        Lambda1["Lambda Fn 1"]
+        Lambda2["Lambda Fn 2"]
+  end
+ subgraph INFRA["INFRASTRUCTURE LAYER"]
+        Postgres[("PostgreSQL")]
+  end
+    Browser --> PAE
+    API --> PAE
+    PAE --> UI & SERVICES & FUNCTIONS
+    UI --> INFRA
+    SERVICES --> INFRA`}
+/>
+
+---
+
+## System Components
+
+### 1. Gateway Layer
+
+The **PAE NestJS Gateway Service** is the central nervous system of the platform.
+
+<CardGrid>
+  <Card title="Authentication" icon="approve-check">
+    - Multi-IDP support (Okta, EntraId, OneLogin, Github, Cognito)
+    - JWT-based sessions with HTTP-only cookies
+    - API key authentication
+    - Service-to-service authentication
+    - User impersonation
+  </Card>
+
+  <Card title="Authorization" icon="shield">
+    - RBAC enforcement at gateway level
+    - Operation-based access control
+    - Resource-level permissions
+    - Tenant-scoped authorization
+  </Card>
+
+  <Card title="Routing & Proxying" icon="random">
+    - Dynamic route resolution via catalog
+    - Request proxying to microservices
+    - Lambda function integration
+    - WebSocket proxying
+    - HTTP/2 multiplexing
+  </Card>
+
+  <Card title="Context Management" icon="seti:json">
+    - Tenant context resolution
+    - User context propagation
+    - Application context tracking
+    - Request tracing and correlation
+  </Card>
+</CardGrid>
+
+### 2. Micro-Frontend Layer
+
+UI applications are built as **React-based micro-frontends** using single-spa.
+
+**Shell UI**: The orchestrator that:
+- Loads and mounts micro-frontends dynamically
+- Provides shared navigation and layout
+- Manages authentication state
+- Coordinates tenant selection
+- Handles global error boundaries
+
+**Feature UIs**: Independent micro-frontends that:
+- Implement specific application features
+- Register with the catalog
+- Share common UI components via `pae-ui-react-core`
+- Use `pae-ui-react-sdk` for build configuration
+
+### 3. Microservices Layer
+
+Backend services are built with **NestJS** or **Express**.
+
+**Service Characteristics**:
+- Domain-driven design
+- RESTful APIs with OpenAPI documentation
+- Event-driven communication via Kafka
+- PostgreSQL for persistence
+- Knex or TypeORM for database access
+- Register with catalog on startup
+- Receive platform context via headers
+
+### 4. Shared Libraries
+
+The platform provides shared libraries for consistency:
+
+<CardGrid>
+  <Card title="pae-core-lib" icon="seti:npm">
+    Core domain entities, authorization logic, catalog types, and utilities used by both frontend and backend
+  </Card>
+
+  <Card title="pae-service-nestjs-sdk" icon="seti:npm">
+    NestJS utilities: decorators, guards, interceptors, and platform integration helpers
+  </Card>
+
+  <Card title="pae-ui-react-sdk" icon="seti:npm">
+    React micro-frontend SDK with Webpack configuration, development server, and build tools
+  </Card>
+
+  <Card title="pae-ui-react-core" icon="seti:npm">
+    Shared React components, hooks, utilities, and authorization components
+  </Card>
+</CardGrid>
+
+---
+
+## Request Flow
+
+### Gateway Guard Chain and Request Lifecycle
+
+Every inbound request passes through a sequential chain of NestJS guards before being proxied. Each guard either enriches the request context and passes control forward, or short-circuits the chain with an appropriate HTTP error.
+
+<MermaidDiagram
+  title="Gateway Guard Chain and Request Lifecycle"
+  height="700px"
+  code={`sequenceDiagram
+    participant B as Browser
+    participant N as nginx
+    participant CG as CatalogGuard
+    participant AG as AuthGuard
+    participant IG as ImpersonationGuard
+    participant TG as TenantGuard
+    participant TRG as TenantRouteGuard
+    participant AZG as AuthorizationGuard
+    participant PS as ProxyService
+    participant SVC as Backend Service
+
+    B->>N: HTTPS Request
+    N->>CG: HTTP (SSL terminated)
+    CG-->>CG: Resolve target module from catalog
+    CG->>AG: targetModule resolved (or 404)
+    AG-->>AG: Validate JWT cookie / API key
+    AG->>IG: AuthUser set (or 401)
+    IG-->>IG: Check impersonation headers
+    IG->>TG: Effective user identity
+    TG-->>TG: Resolve tenant from subdomain/header
+    TG->>TRG: Tenant context (or 403)
+    TRG-->>TRG: Validate tenant has access to route
+    TRG->>AZG: OK (or 403)
+    AZG-->>AZG: Check user RBAC operations
+    AZG->>PS: Authorized (or 403)
+    PS->>SVC: HTTP + x-forwarded-user, x-forwarded-tenant, x-forwarded-user-operations headers
+    SVC-->>PS: Response (business logic)
+    PS-->>B: Response`}
+/>
+
+### Typical Request Lifecycle
+
+```
+1. Client Request
+   ↓
+2. Gateway: SSL Termination (HTTPS → HTTP/2)
+   ↓
+3. Gateway: Authentication (JWT validation, cookie extraction)
+   ↓
+4. Gateway: Tenant Resolution (subdomain, URL pattern, cookie)
+   ↓
+5. Gateway: Platform Context Setup (tenant, user, application)
+   ↓
+6. Gateway: Route Resolution (catalog lookup)
+   ↓
+7. Gateway: Authorization Check (RBAC, operations, rules)
+   ↓
+8. Gateway: Add Forward Headers (user, tenant, context)
+   ↓
+9. Gateway: Proxy Request to Service
+   ↓
+10. Service: Receive Context via Headers
+   ↓
+11. Service: Process Business Logic
+   ↓
+12. Service: Return Response
+   ↓
+13. Gateway: Forward Response to Client
+   ↓
+14. Client: Render UI
+```
+
+### Example: User Views Orders
+
+<Tabs>
+  <TabItem label="1. Initial Request">
+    ```http
+    GET https://acme.platform.com/orders HTTP/2
+    Cookie: auth_token=eyJhbGciOiJIUzI1NiIs...
+    Host: acme.platform.com
+    ```
+
+    User navigates to orders page in their browser.
+  </TabItem>
+
+  <TabItem label="2. Gateway Processing">
+    ```typescript
+    // Gateway extracts and validates JWT
+    const user = jwtService.verify(cookieToken);
+    // { username: 'john@acme.com', tenantId: 'acme', ... }
+
+    // Resolves tenant from subdomain
+    const tenant = await tenantResolver.resolve('acme.platform.com');
+    // { id: 'acme', name: 'ACME Corp', ... }
+
+    // Looks up route in catalog
+    const targetModule = catalog.resolve('/orders');
+    // { name: 'orders-service', url: 'http://orders:4001', ... }
+
+    // Checks authorization
+    const authorized = await authz.authorize(user, targetModule, 'GET', '/orders');
+    // true (user has 'orders.read' operation)
+    ```
+  </TabItem>
+
+  <TabItem label="3. Service Request">
+    ```http
+    GET http://orders-service:4001/orders HTTP/1.1
+    x-forwarded-user-id: john@acme.com
+    x-forwarded-user-name: John Doe
+    x-forwarded-tenant: eyJ0ZW5hbnRJZCI6ImFjbWUifQ==
+    x-forwarded-user-operations: orders.read,orders.write
+    ```
+
+    Gateway forwards request with platform context headers.
+  </TabItem>
+
+  <TabItem label="4. Service Response">
+    ```json
+    {
+      "orders": [
+        {
+          "id": "ord-123",
+          "tenantId": "acme",
+          "customerId": "cust-456",
+          "total": 99.99,
+          "status": "PENDING"
+        }
+      ]
+    }
+    ```
+
+    Service returns orders filtered by tenant.
+  </TabItem>
+</Tabs>
+
+---
+
+## Service Communication Patterns
+
+The platform supports two distinct communication patterns depending on the caller and use case.
+
+<Tabs>
+  <TabItem label="HTTP via Gateway">
+    All external client traffic flows through the gateway. The catalog resolves the target service using longest-prefix matching on the request path, and the gateway enriches the forwarded request with platform context headers.
+
+    <MermaidDiagram
+      title="HTTP Request via Gateway"
+      height="450px"
+      code={`sequenceDiagram
+    participant Client
+    participant Gateway
+    participant Catalog
+    participant Service
+
+    Client->>Gateway: GET /api/orders/123
+    Gateway->>Catalog: resolveTargetModule("/api/orders/123")
+    Note over Catalog: Longest prefix match<br/>against module baseUrls
+    Catalog-->>Gateway: orders-service @ http://orders:4001
+    Gateway->>Service: GET /123\\n+ x-forwarded-user\\n+ x-forwarded-tenant\\n+ x-forwarded-user-operations
+    Service-->>Gateway: Response data
+    Gateway-->>Client: Response data`}
+    />
+  </TabItem>
+
+  <TabItem label="Service-to-Service">
+    Internal services authenticate with the gateway using the shared `SERVICE_ACCESS_SECRET`. The gateway detects this credential, creates a service account identity, and forwards the request with appropriate context headers.
+
+    <MermaidDiagram
+      title="Service-to-Service Authentication"
+      height="450px"
+      code={`sequenceDiagram
+    participant SvcA as Service A
+    participant Gateway
+    participant SvcB as Service B
+
+    SvcA->>Gateway: GET /api/service-b/data\\nAuthorization: Bearer SERVICE_ACCESS_SECRET
+    Note over Gateway: AuthGuard detects SERVICE_ACCESS_SECRET\\nCreates service account identity
+    Gateway->>SvcB: GET /api/service-b/data\\n+ x-forwarded-user: service-a
+    SvcB-->>Gateway: Response
+    Gateway-->>SvcA: Response`}
+    />
+  </TabItem>
+</Tabs>
+
+---
+
+## Micro-Frontend Loading
+
+The shell and feature UIs are loaded dynamically using single-spa and ES Module import maps. The gateway's orchestrator service generates the bootstrap HTML that wires together all registered UI modules at runtime, so new micro-frontends can be added to the catalog without rebuilding the shell.
+
+<MermaidDiagram
+  title="Micro-Frontend Bootstrap and Runtime Loading"
+  height="700px"
+  code={`sequenceDiagram
+    participant B as Browser
+    participant GW as Gateway
+    participant Orch as OrchestratorService
+    participant Cat as Catalog
+    participant Shell as Shell UI
+    participant MFE as Feature UI (MFE)
+
+    B->>GW: GET / (initial page load)
+    GW->>Orch: Generate HTML for shell route
+    Orch->>Cat: Get all UI modules (type=app/tool/utility)
+    Cat-->>Orch: [shell-ui, admin-ui, crm-ui, ...]
+    Orch-->>GW: HTML with:\\n- ES Module import maps\\n- single-spa bootstrap script\\n- window.__PAE_GLOBAL_STATE__
+    GW-->>B: HTML document
+
+    Note over B: Browser parses import maps,\\nloads single-spa runtime
+
+    B->>GW: GET /shell-ui/pae-shell-ui.js
+    GW->>Shell: Proxy to Shell UI server :9004
+    Shell-->>B: Shell bundle (React + single-spa lifecycle)
+
+    Note over B: Shell mounts, renders layout\\nUser navigates to /crm
+
+    B->>GW: GET /crm-ui/mycompany-crm-ui.js
+    GW->>MFE: Proxy to CRM UI server
+    MFE-->>B: CRM bundle
+
+    Note over B: single-spa mounts CRM app\\ninto #pae-shell-ui-content`}
+/>
+
+---
+
+## Security Architecture
+
+### Authentication Flow (OAuth 2.0 / PKCE)
+
+The platform uses the Authorization Code flow with PKCE for browser-based authentication. The gateway acts as the OAuth client, exchanging codes for tokens with the identity provider and issuing a signed platform JWT stored in an HTTP-only cookie. No OAuth tokens are ever sent to the browser.
+
+<MermaidDiagram
+  title="OAuth 2.0 PKCE Authentication Flow"
+  height="650px"
+  code={`sequenceDiagram
+    participant B as Browser
+    participant GW as Gateway
+    participant IDP as Identity Provider\\n(Okta / EntraId / etc.)
+    participant DB as PostgreSQL
+
+    B->>GW: GET /auth/login?provider=okta
+    GW->>GW: Generate PKCE code_verifier + code_challenge\\nGenerate state token (CSRF protection)
+    GW-->>B: 302 Redirect to IDP /authorize
+    B->>IDP: GET /authorize?client_id=...&code_challenge=...&state=...
+    IDP-->>B: Login page
+    B->>IDP: Credentials + MFA
+    IDP-->>B: 302 to /auth/callback?code=XXX&state=YYY
+    B->>GW: GET /auth/callback?code=XXX&state=YYY
+    GW->>GW: Validate state token
+    GW->>IDP: POST /token (code + code_verifier + client_secret)
+    IDP-->>GW: { access_token, id_token, refresh_token }
+    GW->>IDP: GET /userinfo (Bearer access_token)
+    IDP-->>GW: { sub, email, name, groups }
+    GW->>DB: Upsert user record + sync group memberships
+    GW->>GW: Sign platform JWT with configured secret
+    GW-->>B: Set-Cookie: auth_token=JWT (httpOnly, secure, sameSite=Lax)
+    GW-->>B: 302 Redirect to /`}
+/>
+
+### Authorization Flow
+
+```
+1. Request arrives at gateway
+2. Gateway extracts user from JWT
+3. Gateway checks for user's allowed resources
+4. Gateway resolves target module from catalog
+5. Gateway checks if user has required operations
+6. Gateway evaluates rules
+7. If authorized, request proxied to service
+8. Service receives user context via headers
+9. Service performs additional authorization if needed
+```
+
+---
+
+## Catalog and Bootstrap Lifecycle
+
+The catalog drives all routing and authorization decisions at runtime. It is populated during the bootstrap phase by a one-time service that registers modules, roles, and operations via the gateway REST API. At runtime the catalog is served from an in-memory cache that is invalidated whenever a catalog entry is updated through the API.
+
+<MermaidDiagram
+  title="Catalog Bootstrap and Runtime Cache Lifecycle"
+  height="650px"
+  code={`flowchart TD
+    subgraph BOOTSTRAP["Bootstrap Phase (run-once at startup)"]
+        BS["Bootstrap Service"]
+        JSON["Module definitions\\nRoles and Operations\\nInitial users"]
+        BS -->|reads| JSON
+        BS -->|"POST /catalog\\n(SERVICE_ACCESS_SECRET)"| GW_API["Gateway REST API"]
+        GW_API -->|INSERT| DB_CAT[("catalog table\\nPostgreSQL")]
+    end
+
+    subgraph RUNTIME["Runtime Phase"]
+        REQ["Incoming Request\\nGET /api/orders/123"]
+        CAT_SVC["CatalogService"]
+        CACHE["In-Memory Cache"]
+        DB_RT[("PostgreSQL")]
+        RESOLVE["resolveTargetModule()\\nLongest prefix match"]
+        TARGET["orders-service\\nhttp://orders:4001"]
+
+        REQ --> CAT_SVC
+        CAT_SVC -->|cache hit| CACHE
+        CACHE -.->|cache miss| DB_RT
+        DB_RT -.->|populate cache| CACHE
+        CAT_SVC --> RESOLVE --> TARGET
+    end
+
+    subgraph INVALIDATION["Cache Invalidation"]
+        API_UPDATE["PUT /catalog/:id"]
+        EE["EventEmitter2\\ncatalog:changed"]
+        FLUSH["Flush in-memory cache"]
+
+        API_UPDATE --> EE --> FLUSH
+    end
+
+    DB_CAT -.->|loaded on startup| CACHE`}
+/>
+
+---
+
+## Multi-Tenancy
+
+Each request is scoped to a specific tenant resolved from the incoming hostname or headers. The gateway propagates tenant identity to downstream services via base64-encoded forwarded headers. Services built with the platform SDK extract these headers automatically to enforce row-level tenant isolation in database queries.
+
+<MermaidDiagram
+  title="Multi-Tenant Request Isolation"
+  height="400px"
+  code={`flowchart LR
+    subgraph REQUEST["Incoming Request"]
+        R["GET /api/orders\\nHost: acme.platform.com\\nCookie: auth_token=JWT{tenantId:'acme'}"]
+    end
+    subgraph GATEWAY["Gateway Processing"]
+        TR["Tenant Resolver\\nsubdomain to 'acme'"]
+        CTX["Platform Context\\ntenant: acme\\nuser: john@acme.com"]
+        HDR["Forwarded Headers\\nx-forwarded-tenant: base64(acme)\\nx-forwarded-user: john@acme.com\\nx-forwarded-user-operations: orders.read"]
+    end
+    subgraph SERVICE["Backend Service"]
+        MW["SDK Auth Middleware\\nreads x-forwarded-* headers\\nbuilds req.user + req.tenant"]
+        QUERY["DB Query\\nWHERE tenant_id = 'acme'"]
+        RESULT["Tenant-isolated\\nresults"]
+    end
+    R --> TR --> CTX --> HDR --> MW --> QUERY --> RESULT`}
+/>
+
+---
+
+## Technology Stack
+
+### Backend Technologies
+
+<CardGrid stagger>
+  <Card title="NestJS 10.x" icon="seti:nestjs">
+    Enterprise framework for scalable Node.js applications with dependency injection, decorators, and modular architecture
+  </Card>
+
+  <Card title="Fastify 4.x" icon="rocket">
+    High-performance HTTP server with HTTP/2, WebSocket support, and built-in schema validation
+  </Card>
+
+  <Card title="Express 4.x" icon="seti:javascript">
+    Minimal and flexible web framework for lightweight microservices
+  </Card>
+
+  <Card title="TypeScript 5.8" icon="seti:typescript">
+    Strongly-typed JavaScript with advanced type system for better developer experience
+  </Card>
+
+  <Card title="PostgreSQL 15+" icon="seti:db">
+    Robust relational database with JSONB support for flexible schemas
+  </Card>
+
+  <Card title="Knex.js" icon="seti:db">
+    SQL query builder with migrations and transaction support
+  </Card>
+
+  <Card title="Passport.js" icon="approve-check">
+    Flexible authentication middleware with strategies for OAuth, JWT, API keys
+  </Card>
+
+  <Card title="Apache Kafka" icon="seti:config">
+    Distributed event streaming for asynchronous communication between services
+  </Card>
+</CardGrid>
+
+### Frontend Technologies
+
+<CardGrid stagger>
+  <Card title="React 18" icon="seti:react">
+    Modern UI library with concurrent rendering and automatic batching
+  </Card>
+
+  <Card title="single-spa" icon="puzzle">
+    Micro-frontend framework for composing multiple applications into one
+  </Card>
+
+  <Card title="Webpack 5" icon="seti:webpack">
+    Module bundler with code splitting and federation for micro-frontends
+  </Card>
+
+  <Card title="React Query" icon="seti:graphql">
+    Powerful data fetching and state management for server state
+  </Card>
+
+  <Card title="React Router 6" icon="random">
+    Declarative routing for React applications
+  </Card>
+</CardGrid>
+
+### Infrastructure
+
+<CardGrid>
+  <Card title="Docker" icon="seti:docker">
+    Containerization for consistent deployment across environments
+  </Card>
+
+  <Card title="Turborepo" icon="seti:config">
+    Monorepo build system with intelligent caching and parallel execution
+  </Card>
+
+  <Card title="Node.js 20+" icon="seti:nodejs">
+    JavaScript runtime with ES modules and modern JavaScript features
+  </Card>
+
+  <Card title="npm Workspaces" icon="seti:npm">
+    Monorepo package management with shared dependencies
+  </Card>
+</CardGrid>
+
+---
+
+## Design Principles
+
+### 1. Separation of Concerns
+
+Each component has a clear responsibility:
+- **Gateway**: Authentication, authorization, routing
+- **Services**: Business logic and data persistence
+- **UIs**: User interaction and presentation
+- **Libraries**: Shared utilities and components
+
+### 2. Single Responsibility
+
+Services and modules focus on specific domains:
+- Habits Service → Habit tracking
+- Scheduler Service → Scheduling
+- Admin UI → Platform administration
+
+### 3. API Gateway Pattern
+
+All external traffic flows through the gateway:
+- Centralized authentication and authorization
+- Consistent error handling and logging
+- Rate limiting and throttling
+- Request tracing and monitoring
+
+### 4. Micro-Frontend Architecture
+
+UIs are independently deployable:
+- Teams can work autonomously
+- Deploy features without full application rebuild
+- Technology diversity (if needed)
+- Incremental upgrades
+
+### 5. Security in Depth
+
+Multiple layers of security:
+- SSL/TLS encryption
+- JWT authentication
+- Operation-based authorization
+- Tenant isolation
+
+---
+
+## Monitoring and Observability
+
+<CardGrid>
+  <Card title="Logging" icon="seti:text">
+    Structured JSON logs with correlation IDs for request tracing
+  </Card>
+
+  <Card title="Metrics" icon="seti:graphql">
+    OpenTelemetry integration for distributed tracing
+  </Card>
+
+  <Card title="Health Checks" icon="approve-check">
+    All services expose health endpoints
+  </Card>
+
+  <Card title="Audit Trail" icon="seti:lock">
+    All mutations logged with user and timestamp
+  </Card>
+</CardGrid>
+
+---
+
+## Deployment Architecture
+
+The platform can be deployed in various configurations:
+
+<Tabs>
+  <TabItem label="Development">
+    ```
+    Local Development:
+    - Docker Compose for all services
+    - Hot reload for services and UIs
+    - Local PostgreSQL and Kafka
+    - Self-signed SSL certificates
+    ```
+  </TabItem>
+
+  <TabItem label="Staging">
+    ```
+    Staging Environment:
+    - Kubernetes cluster (EKS, GKE, AKS)
+    - Managed PostgreSQL (RDS, Cloud SQL)
+    - Managed Kafka (MSK, Confluent Cloud)
+    - SSL certificates from Let's Encrypt
+    - Single replica per service
+    ```
+  </TabItem>
+
+  <TabItem label="Production">
+    ```
+    Production Environment:
+    - Multi-region Kubernetes
+    - PostgreSQL with read replicas
+    - Kafka cluster with replication
+    - CDN for static assets (CloudFront, Cloudflare)
+    - Auto-scaling based on metrics
+    - Multiple replicas per service
+    - Backup and disaster recovery
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## Next Steps
+
+Explore the detailed architecture documentation:
+
+- **[Gateway Architecture](/_/docs/architecture/gateway-architecture/)** - Deep dive into the gateway service, guard chain, and proxy configuration
+- **[Authentication System](/_/docs/architecture/authentication-system/)** - Authentication flows and IDP integration
+- **[Authorization System](/_/docs/architecture/authorization-system/)** - RBAC model and permission checking
+- **[Multi-Tenancy](/_/docs/architecture/multi-tenancy/)** - Tenant isolation and context management
+- **[API Explorer](/_/docs/architecture/api-explorer/)** - Interactive API documentation and testing
+- **[Bootstrap](/_/docs/architecture/bootstrap/)** - Platform bootstrap process and configuration
+- **[Scheduler Service](/_/docs/architecture/scheduler/)** - Job scheduling and recurring task management
+- **[Shell UI](/_/docs/architecture/shell/)** - Platform shell architecture and customization
+- **[UI Extension Points](/_/docs/architecture/ui-extension-points/)** - UI extension mechanism and patterns
+- **[User States](/_/docs/architecture/user-states/)** - User-specific state storage and preferences