save checkpoint

docs/modules/router/architecture.md

@@ -39,6 +39,67 @@ Each transport connection carries:
 
 ---
 
+## Front Door (Configurable Route Table)
+
+The Router Gateway serves as the **single HTTP entry point** for the entire StellaOps platform. In addition to binary transport routing for microservices, it handles:
+
+- **Static file serving** (Angular SPA dist)
+- **Reverse proxy** to HTTP-only backend services
+- **WebSocket proxy** to upstream WebSocket servers
+- **SPA fallback** (extensionless paths serve `index.html`)
+- **Custom error pages** (404/500 HTML fallback)
+
+### Route Table Model
+
+Routes are configured in `Gateway:Routes` as a `StellaOpsRoute[]` array, evaluated **first-match-wins**:
+
+```csharp
+public sealed class StellaOpsRoute
+{
+    public StellaOpsRouteType Type { get; set; }
+    public string Path { get; set; }
+    public bool IsRegex { get; set; }
+    public string? TranslatesTo { get; set; }
+    public Dictionary<string, string> Headers { get; set; }
+}
+```
+
+Route types:
+
+| Type | Behavior |
+|------|----------|
+| `ReverseProxy` | Strip path prefix, forward to `TranslatesTo` HTTP URL |
+| `StaticFiles` | Serve files from `TranslatesTo` directory, SPA fallback if `x-spa-fallback: true` header set |
+| `StaticFile` | Serve a single file at exact path match |
+| `WebSocket` | Bidirectional WebSocket proxy to `TranslatesTo` ws:// URL |
+| `Microservice` | Pass through to binary transport pipeline |
+| `NotFoundPage` | HTML file served on 404 (after all other middleware) |
+| `ServerErrorPage` | HTML file served on 5xx (after all other middleware) |
+
+### Pipeline Order
+
+System paths (`/health`, `/metrics`, `/openapi.*`) bypass the route table entirely. The dispatch middleware runs before the microservice pipeline:
+
+```
+HealthCheckMiddleware  →  (system paths: health, metrics)
+RouteDispatchMiddleware →  (static files, reverse proxy, websocket)
+MapRouterOpenApi       →  (OpenAPI endpoints)
+UseWhen(non-system)    →  (microservice pipeline: auth, routing, transport)
+ErrorPageFallbackMiddleware → (custom 404/500 pages)
+```
+
+### Docker Architecture
+
+```
+Browser → Router Gateway (port 80) → [microservices via binary transport]
+                                    → [HTTP backends via reverse proxy]
+                                    → [Angular SPA from /app/wwwroot volume]
+```
+
+The Angular SPA dist is provided by a `console-builder` init container that copies the built files to a shared `console-dist` volume mounted at `/app/wwwroot`.
+
+---
+
 ## Service Identity
 
 ### Instance Identity