Service Topology

This document describes the current active service layout for capetownmarket-faas.

The live topology is a small set of FastAPI/Uvicorn services plus the portal web frontend:

automation-core
documentation-core
capetown-faas-core
database-abstraction-core
apps/portal-web

Active Services

`automation-core`

Host/port: 127.0.0.1:50001 in the current local and deploy scripts.
Role: control-plane and orchestration service.
Responsibilities: readiness checks, service startup coordination, queue/control endpoints, and operational status.

`documentation-core`

Host/port: 127.0.0.1:50101.
Role: official TypeDoc-backed documentation server.
Responsibilities: build and serve the generated documentation site, expose health and ready status, publish TypeDoc build status, and expose raw markdown/page lookup helpers for operators and automation.

`capetown-faas-core`

Host/port: 127.0.0.1:50102.
Role: primary business/runtime API service.
Responsibilities: /health, /ready, /ingest, /companies, /operations, /work-items, /system/deployment, /contracts, and print-job APIs.

`database-abstraction-core`

Host/port: 127.0.0.1:50103.
Role: database-backed business abstraction and statistics service.
Responsibilities: health/ready checks, statistics query APIs, and database-facing adapters.
Production ingress: internal only. Production nginx must not publish /dbcore; local browser development reaches this service only through the Vite dev proxy.

`apps/portal-web`

Browser port: 5173.
Role: user-facing portal and workspace shell.
Responsibilities: landing cards, login/session handoff, alpha3 workspace runtime, inspector/debug UI, and browser smoke entrypoints.

Current Dependency Shape

The current service relationships are:

portal-web talks to capetown-faas-core for runtime and deployment state.
portal-web can talk to database-abstraction-core for database-backed workflow and statistics access in local development through the Vite /dbcore proxy.
In production, browser-visible APIs must go through the published capetown-faas-core routes. database-abstraction-core remains loopback/internal and is validated directly only by server-side deployment checks.
capetown-faas-core coordinates business/system flows and exposes the queue-style APIs used by the portal.
automation-core manages orchestration and readiness around the rest of the system.
documentation-core serves the official documentation site and related page-data endpoints for the platform.

Topology Notes

The live topology is still configured with hard-coded local ports in several scripts and service entrypoints, so this document should be treated as the current topology snapshot, not a generic deployment manifest.

The active workspace lane is alpha3-only, which means the portal shell and browser routes are now centered on the alpha3 host/runtime rather than the old alpha0/alpha1/alpha2 stack.

Health And Readiness

The active services all expose health and readiness endpoints, and the deploy scripts use those endpoints as part of rollout validation.

Current service health surfaces include:

/health
/ready

For documentation-core, rollout validation also checks GET /typedoc-status and GET / so the generated docs site itself is confirmed, not just the Python process.

The business core also exposes operational routes such as:

/ingest
/companies
/operations
/work-items
/system/deployment
/contracts

Rebuild Notes

This doc replaces the older scattered service maps and contract writeups as the current topology reference.

It should stay focused on:

current services
current ports
current responsibilities
current runtime dependencies

If the topology changes, update this document first, then update the deploy and local-dev docs to match.