Documentation Core

This service is the internal documentation host for the platform. It now builds and serves a TypeDoc site that combines repo-relevant TypeScript reference material with the active markdown documentation tree.

Responsibilities

• Build a TypeDoc site that combines generated API reference with the active markdown docs tree.
• Provide discoverable docs for operators, automation, and contributors.
• Host service-operations metadata (health, status, startup expectations).
• Keep docs available even in local development and test environments.

Documentation scope

• This repo's architecture, operational, and service standards.
• Service READMEs and API contracts.
• Onboarding and runbook documentation.
• TypeScript reference material for the documentation runtime itself.

Development

cd services/documentation-core
uv sync
npm install
Copy

Start this service only through the automation stack:

uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py up --start-stack
Copy

If you need to run it directly for local debugging, start it with src on the app path:

cd services/documentation-core
uv run python -m uvicorn documentation_core.main:app --app-dir src --host 127.0.0.1 --port 50101
Copy

Build the TypeDoc site on demand without starting the service:

npm run docs:build
Copy

For the managed deploy path, the remote rollout script now installs the repo-root Node tooling, builds the TypeDoc site with npm run docs:build, and then restarts documentation-core. A healthy process is not enough for rollout success anymore: deployment also waits for GET /ready, GET /typedoc-status, and GET / to succeed.

Health check:

• GET /health — includes ready and site_ready
• GET /ready

Content endpoints:

• GET / — generated TypeDoc documentation site
• GET /typedoc-status — TypeDoc build metadata and latest error state
• POST /typedoc-refresh — rebuild the TypeDoc site synchronously
• GET /pages — available documentation files
• GET /raw/{page} — returns markdown source