docs

docs/backend-platform/architecture.md

@@ -0,0 +1,103 @@
+# Backend Platform Architecture
+
+## 1. System Overview
+This platform is a domain-based multi-tenant SaaS marketplace.
+
+- Frontend (Angular) is configuration-driven.
+- Backend (Node.js) is tenant-aware and resolves tenant by request domain.
+- UI composition is delivered by `GET /bootstrap` from the backend CONFIG DOMAIN.
+- Business operations are delivered by existing BUSINESS DOMAIN APIs (`/auth`, `/items`, `/categories`, `/orders`, `/cart`, `/payments`).
+
+Core architectural rule:
+- No projectName-based behavior.
+- No environment-based business branching.
+- Runtime behavior is tenant-driven by domain + tenant configuration.
+
+## 2. Tenant Resolution by Domain
+Tenant identity is resolved from the incoming host:
+- `shop-a.example.com` -> tenant A
+- `shop-b.example.com` -> tenant B
+
+Resolution output is attached to request context and used by:
+- Config domain (`/bootstrap`, `/pages/:slug`)
+- Business APIs (data isolation and policy checks)
+
+## 3. CONFIG DOMAIN vs BUSINESS DOMAIN
+
+### CONFIG DOMAIN
+Purpose: return public runtime configuration for frontend composition.
+Includes:
+- tenant metadata (public)
+- theme
+- layout mode
+- widget registry metadata
+- page/section/widget structure
+- footer/static pages metadata
+- supported locales/currencies
+- endpoint mapping (public)
+
+### BUSINESS DOMAIN
+Purpose: transactional and catalog operations.
+Includes:
+- authentication/session
+- products/items
+- categories
+- cart
+- orders
+- payments
+
+Boundary rule:
+- BUSINESS APIs do not return UI layout/theme/widget composition.
+- CONFIG APIs do not return transactional business state.
+
+## 4. Bootstrap API Role
+`GET /bootstrap` initializes frontend runtime.
+
+Backend responsibilities:
+1. Resolve tenant from domain.
+2. Load tenant config aggregate.
+3. Return versioned, public bootstrap payload.
+4. Never leak secrets in bootstrap.
+
+Frontend responsibilities:
+1. Load bootstrap at startup.
+2. Render based on config only.
+3. Use business APIs only for domain data/actions.
+
+## 5. Existing API Domains (Unchanged)
+- `/auth`
+- `/items`
+- `/categories`
+- `/orders`
+- `/cart`
+- `/payments`
+
+These APIs remain authoritative for business workflows and must not be rewritten for UI composition.
+
+## 6. Data Flow Diagram (Text)
+```text
+Browser Request
+  -> Edge/Ingress (Host preserved)
+  -> Node.js API Gateway
+      -> Tenant Resolver Middleware (host -> tenant)
+      -> Request Context Enrichment (tenantId, locale, policy)
+      -> Route Dispatch
+          -> /bootstrap (CONFIG DOMAIN) -> Config Services -> Response JSON
+          -> /items|/orders|... (BUSINESS DOMAIN) -> Business Services -> Response JSON
+  <- Tenant-scoped response
+```
+
+## 7. Request Lifecycle (Browser -> Backend -> Tenant -> Response)
+1. Browser sends request with `Host` header.
+2. Backend middleware resolves tenant by domain.
+3. Backend validates tenant status (active, allowed, mapped).
+4. Tenant context is attached to request (`req.ctx.tenant`).
+5. Route handler executes with tenant-scoped repositories/services.
+6. Response is returned with tenant-scoped data.
+
+## 8. Scalability Notes (10–100+ Tenants)
+- Keep tenant config in low-latency cache with invalidation.
+- Use stateless API instances; tenant context is per request.
+- Enforce strict tenant filters at repository/query layer.
+- Monitor by tenant dimensions (latency, errors, saturation).
+- Apply rate limits and abuse controls per tenant/domain.