Architecture Decision Records
The following ADRs document the decisions that shape what external developers see. Each ADR records the context that led to the decision and the decision itself. Consequences and detailed rationale live in internal documentation.
ADR-001: Two-API Split (Core API vs Intelligence Service)
Context. BCMLogic Next combines deterministic, audit-bound business operations with non-deterministic, latency-tolerant AI operations. Exposing both through a single API forces a lowest-common-denominator contract: weaker SLAs for transactional calls, awkward streaming semantics, unclear audit boundaries, and generation requests that look like normal writes but are not.
Decision. Two APIs behind a single gateway: Core API for transactional and audit-bound operations, Intelligence Service for AI-driven operations. They share authentication, tenancy, error envelope, and pagination conventions. The split is visible only in the URL prefix — /v1/core/* versus /v1/ai/*.
See The Two-API Model.
ADR-002: Intelligence Service is Stateless with Respect to Business State
Context. AI orchestration needs to read business data (risks, vendors, processes) to generate meaningful output. The naive solution is to give Intelligence Service direct database access. This creates two systems with claims on the same schema, conflicting migrations, and a duplicated audit trail.
Decision. Intelligence Service does not touch the business database. It reads operational data exclusively through Core API (internal tool calls) and consumes events through a message broker. Core API remains the single source of truth. From the developer portal perspective, this is invisible — but it guarantees that the audit trail in Core API is complete.
ADR-003: Anthropic Claude as the Primary LLM
Context. Selecting a foundation model is a strategic decision affecting cost, latency, capability ceiling, and data residency. The platform needs strong long-context reasoning for regulatory text (DORA articles, ISO standards) and reliable tool use for structured generation.
Decision. Anthropic Claude is the primary LLM. The specific access path — direct API, Microsoft Azure, or AWS Bedrock — is determined by the tenant's data residency requirements and is abstracted behind the Intelligence Service interface. Clients see only the Intelligence Service contract; the model version appears in response meta.model for traceability and reproducibility.
ADR-004: Citations Are Part of the Contract
Context. AI-generated outputs used in regulated workflows (BIA reports, risk assessments, vendor analyses) must be traceable to their sources. DORA Article 28 and EU AI Act provisions push consumers of AI output to demonstrate provenance. Treating citations as a UI feature, or as an optional add-on, makes downstream compliance harder.
Decision. Every generation response includes a citations block with source identifiers, versions, and excerpts. Citations are part of the API contract — they are versioned, validated, and never empty for content drawn from sources. Clients building user-facing experiences are expected to render them.
See Intelligence Service → Citations.
ADR-005: Cursor Pagination, No Offsets
Context. Offset/limit pagination is intuitive but degrades on large collections and produces inconsistent results under concurrent writes. Cursor pagination is opaque but stable.
Decision. All list endpoints use cursor-based pagination. Cursors are opaque, server-generated tokens. Offset/limit is not exposed.
See Cross-cutting Concerns → Pagination.
ADR-006: Hard Multi-Tenant Isolation
Context. BCMLogic Next serves regulated enterprises that store sensitive GRC data. Soft tenant isolation — a tenant_id column with application-level filtering — is fragile under refactoring. Hard isolation is more expensive but defensible.
Decision. Tenancy is resolved at the gateway from the bearer token's tenant_id claim. Tenant identifiers do not appear in URLs or request bodies. Per-tenant isolation is enforced at every layer: storage, vector store, message broker, LLM context, and audit trail. Cross-tenant queries are impossible through the public API by design.
See Data Model and Tenancy → Tenancy.
ADR-007: Idempotency Keys for All Mutations
Context. Network retries, client crashes, and gateway timeouts make exactly-once semantics impossible at the transport layer. Without idempotency, retries cause duplicate records.
Decision. All POST and PUT operations on Core API require an Idempotency-Key header. Keys are scoped to tenant and request path, cached for 24 hours. Intelligence Service generation endpoints accept the header optionally to enable safe retry of expensive operations.
See Cross-cutting Concerns → Idempotency.
ADR-008: Tenant Documents and Regulatory KB Are Separate Indices
Context. Intelligence Service draws on two corpora: tenant-uploaded documents and BCMLogic's curated regulatory knowledge base. Mixing them in one vector index requires tagging, filtering, and per-query access control checks — and risks accidental cross-tenant leakage of embeddings.
Decision. Tenant documents live in a tenant-scoped index (one namespace per tenant). The regulatory knowledge base lives in a shared, read-only, versioned index. A single generation request can draw from both, but they are physically separated. The context parameter on each request makes the source selection explicit and auditable.