Services — index

On this page
The per-service catalog (endpoints, tables, events, state machines) lives in Antora, the canonical docs site. This file is only a thin per-service index, so agents know what exists and where to read the authoritative detail — it is not a catalog itself. Add or maintain detail in the Antora pages, not here. For anything not answered below, start at docs/modules/ROOT/index.adoc.

Ports + databases are in .claude/CLAUDE.md § Service Ports.

Service Port / DB Endpoints Tables State machines

craig-rules

8001 / craig_rules

api/craig-rules.adoc

data-model-rules.adoc

—

craig-cases

8002 / craig_cases

api/craig-cases.adoc

data-model-cases.adoc

state-machines.adoc

craig-placement

8003 / craig_placement

api/craig-placement.adoc

data-model-placement.adoc

state-machines.adoc

craig-exchange

8004 / craig_exchange

api/craig-exchange.adoc

data-model-exchange.adoc

state-machines.adoc

craig-financial

8005 / craig_financial

api/craig-financial.adoc

data-model-financial.adoc

state-machines.adoc

craig-reporting

8006 / craig_reporting

api/craig-reporting.adoc

data-model-reporting.adoc

state-machines.adoc

craig-security

8007 / craig_security

api/craig-security.adoc

data-model-security.adoc

state-machines.adoc

craig-intake

8008 / — (stateless edge, ADR-017)

api/craig-intake.adoc

none — adrs/adr-017-stateless-intake.adoc

state-machines.adoc

craig-intake-keyring

8010 / — (flat-file registry, ADR-042 §D8)

craig-intake-keyring.adoc

none — flat-file JSON

key lifecycle in craig-intake-keyring.adoc

craig-composition

8009 / craig_composition

api/craig-composition.adoc

adrs/adr-035-composition-layer-engine.adoc (composition_overrides §5)

—

craig-web

8080 / — (BFF, ADR-004)

adrs/adr-004-bff-pattern.adoc

none (stateless)

—

craig-cli

binary craig

cli.adoc

—

—

All paths are under docs/modules/ROOT/pages/. Events (each service’s published/subscribed routing keys) are documented in adrs/adr-003-rabbitmq-topology.adoc; the security service subscribes to everything as the wildcard # audit subscriber. Shared/library crates are indexed separately, in shared-crates.adoc.

Cross-cutting conventions (agent guidance — detail in Antora)

  • Sort & search: every paginated list endpoint accepts search (ILIKE), sort_by (whitelisted via validated_sort_column() — sort columns are format!()-injected only AFTER whitelist validation, never from raw input), and sort_dir (asc/desc, default DESC). See implementation-guide.adoc § Pagination.

  • Pagination: PageRequest/PageResponse<T> — default page=1, per_page=25, max 500 (implementation-guide.adoc § Pagination).

  • Worker supervision & readiness (#1186, ADR-061): every background worker registers on the process Supervisor, per a per-service manifest. A worker marked Critical dying triggers a fail-fast nonzero exit; one that’s knob-disabled shows up as a visible Disabled instead. /readyz gates on workers, the DB, and the MQ link (both the parent connection and the publisher channel, since #1235), returning a discriminating not ready: <checks> body when something’s down; /healthz carries the typed checks.workers block. Detail: deployment-guide.adoc § Health Checks + shared-crates.adoc § craig-api.

  • Role hierarchy: caseworker_or_above = caseworker/supervisor/admin; supervisor_or_above = supervisor/admin; helper require_role(claims, role). See idp-integration.adoc.

  • Service init / orchestrator shape: bootstrap → deps → spawn_workers → build_router → ApiServer::serve (~50–80 LOC main); see developer-guide.adoc § Service Initialization + architecture.adoc.

  • Healthz: every service exposes public GET /healthz (not counted in the api/ endpoint catalogs, which list #[utoipa::path] business endpoints only).

  • OpenAPI: #[derive(OpenApi)] ApiDoc + SecurityAddon Bearer scheme; Swagger UI at /swagger-ui (implementation-guide.adoc § OpenAPI).

  • Outbox/inbox durability: transactional outbox + idempotent inbox + DLQ per adrs/adr-022-event-durability-and-idempotency.adoc.

craig-test-lib gotchas (testing convention)

The craig-test-lib API surface is in shared-crates.adoc; these are the easy-to-miss specifics:

  • No CaseBuilder/InvestigationBuilder — use serde_json::json!({"admin_unit": "Fulton", "assigned_worker": "jane.doe"}).

  • Builder constructors: PlacementBuilder::new(case_id, child_id), IcpcRequestBuilder::new(case_id, child_id), AgreementBuilder::new(partner_id).

  • ExchangePartnerBuilder (not PartnerBuilder), .partner_name() (not .name()).

  • list_case_plans(case_id) returns a plain array (NOT {"data": […]}); other list endpoints return paginated PageResponse.

  • List signatures take &[(&str, &str)] query pairs: search_persons, list_referrals, list_cases.

  • Agreement transitions: draft → active → expired|terminated (no draft → approved).

  • Safety-assessment via CLI may 500 if the required rule set isn’t loaded — tests tolerate this.

  • Global-property tests race under nextest concurrency — sequence them in ONE test.

Edit this page · latest