regulator-portal-service — Sync Contract
Version: 1.0 Status: Draft Owner: Regulator-facing + Legal Last Updated: 2026-04-21 Companion: DOMAIN_MODEL · API_CONTRACTS · EVENT_SCHEMAS · ADR-0004 §14 Multi-region
This document defines what other services depend on from regulator-portal-service and what it depends on from them. It is a leaf consumer in the platform data graph: read-only against upstream, write-only to its own schema, and produces events for downstream analytics + SIEM.
1. Consumers of regulator-portal-service
| Consumer | Interface | Dependency type | SLA expectation |
|---|---|---|---|
| ATRA regulator users (browser + API) | HTTPS REST :3082 (mTLS national PKI) | Synchronous, user-facing | P95 ≤ 500 ms; 99.5% availability |
| External auditors | HTTPS REST :3083 (mTLS auditor PKI) | Synchronous, read-only | P95 ≤ 500 ms; 99.0% availability |
| ATRA SIEM (Splunk / Logstash / QRadar) | Outbound push (HEC, HTTP, syslog-TLS) | Asynchronous, at-least-once | Lag ≤ 60 s; disk-WAL ≤ 24 h on outage |
admin-dashboard (EP-ADMDASH-10) | HTTPS REST :3084 (Kong JWT) | Synchronous management surface | P95 ≤ 500 ms; 99.5% availability |
analytics-service | NATS regulator.* consumer | Asynchronous archive | Lag ≤ 60 s |
notification-service | NATS regulator.complaint.received.v1, regulator.report.ready.v1 | Asynchronous | Lag ≤ 60 s |
2. Dependencies of regulator-portal-service (read-through only)
| Dependency | Interface | Failure behaviour |
|---|---|---|
compliance-engine | gRPC /v1/compliance/audit-log + REST /v1/compliance/reports | Partial report with WARNINGS section; no silent omission |
consent-ledger-service | REST /v1/internal/consent/aggregates | Same — report annotates missing slice |
sender-id-registry-service | REST /v1/internal/registry/exports | Same |
cdr-mediation-service | gRPC /v1/internal/cdr/status | Daily CDR status report displays STALE if stale |
analytics-service (ClickHouse cold-tier) | HTTPS query | Cold-window reports tagged with data-age |
auth-service | NATS auth.events.* | SIEM forwarder falls back to disk-WAL |
firewall-service | NATS firewall.audit.v1 | Same |
fraud-intel-service | NATS fraud.detected.* | Same |
cbc-service | NATS cbc.audit.v1 | Same |
Postgres regulator schema | Connection pool | Service /ready returns 503; portal degraded |
| Redis | Cache + session store | Re-auth required; reports can still be generated |
| NATS JetStream | Event producer + consumer | Outbox queues; disk-WAL engages for SIEM |
| Vault (Transit + KV + PKI) | HTTPS API | HSM signing blocked; see FM-04 |
| HSM (PKCS#11) | network / softhsm2 | Same |
S3 (ghasi-regulator bucket) | HTTPS | Report downloads blocked; LI delivery blocked |
| SFTP (ATRA drop-box) | SSH-2 | LI delivery retry + FM-06 runbook |
3. Conflict Policy per Aggregate
This service owns all writes to its own schema. There is no multi-master; multi-region strategy is active-standby (sovereign primary, DR warm standby). Conflict policies are therefore trivially defined but documented for completeness and for cases where the DR region takes over.
| Aggregate | Policy | Rationale |
|---|---|---|
RegulatorUser | server_authoritative + CRL cascade | Source of truth is national PKI; DB reflects |
LiRequest | append_only transitions via dual-control | Monotonic state machine; never rewinds |
LiAuditEntry | append_only (Postgres rule-protected) | Hash-chain makes tamper evident |
Complaint | server_authoritative | Platform-owned state; regulator reads back |
ScheduledReport | server_authoritative (platform admin) | Configuration |
ReportJob / GeneratedReport | append_only terminal state | Once READY, immutable; signature binds contents |
AttestationControl | server_authoritative (platform admin) | Catalog |
AttestationEvidence | lww+diff on collection | Later collection wins; evidence files immutable by hash |
AttestationBundle | append_only (annual) | Once signed, immutable (permanent object-lock) |
SiemDestination | server_authoritative (platform admin) | Configuration |
SiemDeliveryLog | append_only with terminal ACKED/DEADLETTERED | Delivery attempts append forever |
AuditorAccess | server_authoritative with TTL enforcement | Legal sign-off + backend TTL sweep |
4. Outbox / Inbox Patterns
4.1 Outbox (produced events)
- Every state change writes
regulator.outbox(event_id, subject, payload)in the same transaction as the aggregate mutation. - A relay pod tails
outbox WHERE published_at IS NULLand publishes to NATS. - Published rows are pruned 7 days post-publish for low-sensitivity events; LI and attestation events are retained indefinitely mirrored to immutable S3 (
s3://ghasi-regulator/outbox-archive/).
4.2 Inbox (consumed events)
- SIEM forwarder is a durable NATS consumer with explicit ACK per delivery.
- Complaint-ingest event consumer is idempotent on
regulatorRef(ATRA's unique reference). - Auditor access lifecycle events (
regulator.cert.revoked.v1fromauth-serviceor self-emitted) cascade-invalidate sessions in Redis.
5. Read-Through Semantics
regulator-portal-service never caches upstream authoritative data beyond short-lived in-request memoization (≤ 5 min). Reports are assembled at generation time and then the assembled snapshot is signed and frozen in S3. This means:
- A re-run of the same report can return different results if upstream state changed — by design (each report is a point-in-time snapshot).
- Once signed, the report is immutable (
signature binds contents). If ATRA disputes, regeneration is a newreportJobId.
6. Multi-Region Topology
Per ADR-0004 §14:
| Concern | Primary (sovereign AF) | DR (regional) |
|---|---|---|
| Regulator-facing endpoints | MUST serve from sovereign region | Disabled (regulatory data residency) |
| Auditor-facing endpoints | Sovereign by default | Enabled only for auditor firms with legal cross-border agreement |
Postgres regulator schema | Leader | Read replica (stream replication, not multi-master) |
| Redis | Regional | Warm standby |
| NATS JetStream | Regional | Mirror with 3 replicas |
S3 ghasi-regulator | Sovereign region only | No cross-region replication for LI/complaint data; bundles may be cross-region replicated for disaster recovery |
| SIEM forwarding | From sovereign region outbound | DR also forwards during active failover only |
| HSM | Regional (on-prem) | Secondary HSM (cold standby) |
Failover. Loss of the sovereign region is a declared incident. DR activation requires CISO + CTO dual-sign per ADR-0004 §14 runbook. Regulator-facing traffic redirection requires ATRA coordination (pre-negotiated CNAME flip). LI workflow is paused during failover — regulators are notified via pre-agreed out-of-band channel.
7. Schema Stability Guarantees
REST
/v1/*endpoints are stable within the major version.- Field additions with defaults are non-breaking.
- Breaking changes ship as
/v2/*with a 180-day deprecation window coordinated with ATRA.
Events
regulator.*.v1payloads follow the stability rules in EVENT_SCHEMAS §6.
DB
- External consumers (audit firms pulling exports) depend on the JSON-structured PDF reports, not on the Postgres schema directly. Schema changes are unobservable to consumers.
8. Versioning Policy
- REST: semantic within
/v1/. - Events: subject-level
v1→v2migration per deprecation window. - Database: forward-only migrations; expand/contract pattern; additive reviewed by Security for PII fields.