104 lines
3.3 KiB
Markdown
104 lines
3.3 KiB
Markdown
# 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.
|