Technical enablement · 02
Components & services catalogue
A reference for every deployable component of {{product.name}}: what it is responsible for, how to call it, what it depends on and how to operate it. Every entry follows the same four-part structure so readers can compare components consistently. Filter by category or search, and click an entry to expand it.
⚠
Entries below are examples. They show the structure and level of detail to aim for and describe a generic product, not {{product.name}}. Replace each example with a real component (or delete it), keep the four-part layout, and add the repository path and owner in the tag. Remove this callout when the catalogue is real.
How to document a component
| Section | Answer these questions |
|---|---|
| Responsibility | What single job does it do? What does it explicitly not do? |
| Interfaces | Endpoints, events, queues or skills it exposes. Link to the API spec rather than copying it. |
| Dependencies | Upstream callers and downstream services, data stores and third parties. What happens when each is down? |
| Operations | Repository path, runtime, scaling, health check, configuration keys, dashboards and owner. |
Experience & API
What users and API clients touch. [Replace: intro sentence.]
Responsibility
Browser UI for end users and administrators. Renders data from the API; holds no business rules and no secrets.
Interfaces
Consumes the public REST API through the gateway. Authenticates via the identity provider (OIDC).
Dependencies
API gateway; identity provider; CDN or static hosting.
Operations
Static build deployed from CI. Health: synthetic page-load check. Config: runtime
config file, no build-time secrets. Owner: [Replace: team].Responsibility
Single entry point: TLS termination, token validation, tenant resolution, rate limiting and path routing to services.
Interfaces
/api/v1/* routed to backend services; /health for probes. Passes a correlation id and tenant id downstream.Dependencies
Identity provider (key discovery); every routed service.
Operations
Stateless; scale horizontally on request rate. Alert on 5xx ratio and latency p95. Owner: [Replace: team].
Responsibility
Versioned, documented interface for client systems and automation. Enforces the same authorisation as the UI.
Interfaces
REST/JSON with an OpenAPI description at [Replace: URL]. Errors follow one envelope; list endpoints are paginated.
Dependencies
Core services behind the gateway; API key or OAuth2 client store.
Operations
Breaking changes only in a new major version with a published deprecation window. Owner: [Replace: team].
Core services
The business logic. [Replace: intro sentence and a link to the service-interaction diagram in Architecture.]
Responsibility
Implements the product's primary workflows and owns their domain rules. Coordinates the other services.
Interfaces
REST endpoints under
/api/v1/[Replace: resource]; emits domain events [Replace: event.name].Dependencies
Transactional store; queue; workflow engine; third-party service A.
Operations
Container, 2+ replicas. Health:
/health/ready. Key config: [REPLACE_ENV_VAR]. Owner: [Replace: team].Responsibility
Runs multi-step, long-lived processes and retries failed steps. Persists state so a restart resumes where it stopped.
Interfaces
Start and query workflows over the internal API; step handlers register through the shared library.
Dependencies
Core service; queue; state store.
Operations
Alert on stuck workflows (no progress for [Replace: duration]). Runbook: Operations: runbooks.
Responsibility
Single place that calls model providers: prompt templates, guardrails, caching, retries and token accounting.
Interfaces
Internal
POST /generate and POST /embed; provider selected by configuration.Dependencies
Model provider(s) (see Integrations); secrets store; cost ledger.
Operations
Per-tenant token budgets and alerts; provider failover [Replace: yes/no]. Owner: [Replace: team].
Responsibility
Delivers email, chat and webhook notifications with templating, throttling and delivery tracking.
Interfaces
Consumes
notification.requested events; exposes delivery status API.Dependencies
Queue; email or chat provider; template store.
Operations
Dead-letter queue monitored; replay procedure in the runbook. Owner: [Replace: team].
Data & intelligence
Pipelines, stores and analytics. [Replace: intro sentence.]
Responsibility
Pulls data from client and third-party sources, validates and normalises it, and lands it in the raw tier.
Interfaces
Scheduled jobs and a push endpoint; emits
ingestion.completed.Dependencies
Source systems; object storage; scheduler.
Operations
Alert on freshness (data older than [Replace: threshold]) and on rejection rate. Owner: [Replace: team].
Responsibility
Transforms raw data into curated, query-ready tables (raw, cleaned, aggregated) used by dashboards and reports.
Interfaces
SQL views and a read-only query API; no direct writes by consumers.
Dependencies
Ingestion pipeline; warehouse or lakehouse.
Operations
Runs on schedule; lineage documented at [Replace: link]. Data classification: [Replace].
Responsibility
Maintains the search or vector index over product content for fast lookup and retrieval-augmented features.
Interfaces
Internal
POST /search; reindex via admin job.Dependencies
Transactional store (source of truth); embedding provider.
Operations
Index is rebuildable from source; rebuild time [Replace: duration].
Platform & shared
Cross-cutting building blocks used by every component. [Replace: intro sentence.]
Responsibility
Authenticates users and services, maps them to tenants and roles, and exposes the tenant context to every request.
Interfaces
OIDC login; token introspection; admin API for tenants and roles.
Dependencies
Corporate identity provider; transactional store.
Operations
Tenant-onboarding steps in Operations: tenancy. Owner: [Replace: team].
Responsibility
Collects logs, metrics and traces and provides dashboards and alerting.
Interfaces
OpenTelemetry exporters in every service; dashboards at [Replace: URL].
Dependencies
All components; alert routing to the on-call channel.
Operations
ⓘ
Capabilities that users see are documented in the feature reference; how components are deployed is in deployment models.