OrcaBus runs the pipelines and workflows, OrcaHouse holds the data, and OrcaSonar finds the knowledge and
documentation behind them. Release 1 answers questions about UMCCR's documentation for the chat panel on
docs.umccr.org and for OrcaUI, through one API at https://sonar.<stage>.umccr.org/api/v1.
Claude writes each answer from passages that a Bedrock managed knowledge base retrieves, with numbered citations that
link to the pages. Everything stays in Australia under OrcaSonar's own KMS key, and questions are kept 30 days and
never logged (data and privacy).
docs.umccr.org chat panel, OrcaUI ──HTTPS──▶ AWS WAF ─▶ API Gateway REST API ─▶ Lambda authorizer (Cognito ID token)
│
├─ POST /chat (streamed) ─▶ chat Lambda ─▶ budget (DynamoDB)
│ ─▶ knowledge base: Retrieve
│ ─▶ Claude on Bedrock, with the guardrail
│ ─▶ 30-day records (S3)
├─ /search, /documents/{id}, /feedback, /chat/history ─▶ query Lambda
├─ /audit/* (audit group only) ─▶ audit Lambda ─▶ audit log (DynamoDB)
└─ /health, /schema/* ─▶ API Gateway itself: no token, no Lambda
docs site pipeline ─▶ ingest bucket docs/<slug>/ ─▶ (every 15 minutes, if changed) ingestion job ─▶ knowledge base
| Piece | Where |
|---|---|
| API, WAF, authorizer, functions, ingestion schedule, alarms, budget | OrcaSonarStatelessStack (infrastructure/stage/stateless-stack.ts) |
| Sonar KMS key, ingest and records buckets, table, knowledge base, guardrail | OrcaSonarStatefulStack (infrastructure/stage/stateful-stack.ts) |
| The API and functions: Hono on Node.js 24 | app/ |
| Two pipelines, one per stack: beta, then prod after approval | infrastructure/toolchain/ |
Every route but /health and the API docs needs a Cognito ID token from an allowed app client. The contract is
app/schema/openapi.yaml, browsable on each stage at /schema/swagger-ui/, as on
sonar.dev.umccr.org.
| Page | For |
|---|---|
| project.md | purpose, callers, scope, status, open items, vocabulary |
| design.md | decisions and their reasons, diagrams, costs |
| architecture.md | what is deployed, the request flow, budget, privacy |
| api.md | requests, the event stream, errors and limits |
| tech.md | the stack, the layout, conventions for changing it |
| deploy.md | deploying, manual steps per account, troubleshooting |
| runbook.md | alarms, the budget, the model, the guardrail, the index |
| Interface | Value |
|---|---|
| Ingest bucket | in SSM as /orcasonar/ingest-bucket-name, which the docs publish steps read |
| Writer | the docs platform's role/docs/docs-publisher, in the same account, under docs/ only; its own policy grants the access |
| Documents | docs/<slug>/<path>.md, each with <path>.md.metadata.json: doc_id, site, title, url, commit, updated |
| API URL | https://sonar.<stage>.umccr.org/api/v1, also in SSM as /orcasonar/api-url |
| CORS | docs.dev.umccr.org in beta; docs.umccr.org and docs.prod.umccr.org in prod |
Node.js 24, pnpm through Corepack, and pre-commit:
corepack enable
make install # the pnpm workspace, app included, and the pre-commit git hook
make check-all # dependency audit, formatting, lint and type checks, both packages
make test-all # jest with cdk-nag for the infrastructure, vitest for the app
make dev # the API on http://127.0.0.1:8787/api/v1, in memory, with no AWS accessmake dev answers from sample passages with a scripted answer, so the chat panel can be developed against it:
curl -N -H 'Accept: text/event-stream' -H 'Content-Type: application/json' \
-d '{"query":"How do I add a site?"}' http://127.0.0.1:8787/api/v1/chatdocs/tech.md lists every command.
docs/ is published at https://docs.umccr.org/orcasonar/ for UMCCR staff, and its pages are in the knowledge base
the chat panel answers from. docs.umccr.org's own pipeline publishes each push to main that changes docs/ or
mkdocs.yml; a failed build leaves the site as it was. project.md is the front page, and a link
from docs/ to a file outside it opens the file on GitHub. To preview, install the docs toolkit
(onboarding) and run umccr-docs serve.