docs

docs/backend-platform/deployment.md

@@ -0,0 +1,66 @@
+# Backend Platform Deployment
+
+## 1. Local Development Setup
+Recommended local flow:
+1. Start backend API (Node.js) with local tenant mappings.
+2. Start frontend Angular app with proxy to backend.
+3. Use local domains/hosts file entries for tenant simulation.
+
+Example hosts mapping:
+- `alpha.local` -> localhost
+- `beta.local` -> localhost
+
+## 2. Environment Variables (Backend)
+Infrastructure-focused variables only:
+- `PORT`
+- `NODE_ENV`
+- `DB_URL`
+- `REDIS_URL`
+- `TENANT_CACHE_TTL_SECONDS`
+- `TRUST_PROXY`
+- `ALLOWED_HOSTS`
+- `LOG_LEVEL`
+
+Guideline:
+- do not use environment variables for tenant business behavior branching.
+- tenant behavior comes from tenant config data resolved by domain.
+
+## 3. Frontend Proxy Setup
+Frontend proxy should route API calls to Node backend:
+- `/bootstrap`
+- `/pages/*`
+- `/items`, `/categories`, `/cart`, `/orders`, `/payments`, `/auth`
+
+Proxy keeps browser-side calls same-origin in local development.
+
+## 4. Production Deployment Flow
+1. Deploy stateless Node API instances.
+2. Configure ingress/load balancer to preserve host headers.
+3. Route all tenant domains to same backend/frontend runtime.
+4. Resolve tenant by domain per request.
+5. Serve tenant-specific bootstrap + tenant-scoped business responses.
+
+## 5. Multi-Tenant Domain Mapping Strategy
+Maintain authoritative mapping table:
+- host -> tenantId
+- tenant status
+- locale/currency defaults
+
+Operational controls:
+- admin tooling for host assignment
+- cache invalidation on mapping updates
+- audit logs for domain changes
+
+## 6. Scaling Considerations (10–100+ Tenants)
+- horizontal scale backend instances
+- distributed cache for tenant + config hot paths
+- query/index optimization with tenant-partitioning strategy
+- per-tenant rate limiting and quotas
+- observability dimensions: tenantId, host, endpoint, latency, error-rate
+
+## 7. Reliability Checklist
+- health/readiness probes
+- circuit breakers for downstream services
+- timeout + retry policy by endpoint class
+- graceful degradation for config fetch failures
+- rollback strategy for bad config releases