# 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.