vault

14 — Operations

docs/14-Operations.mdtype: operationalupdated: 2026-05-03

Operations

The operational view of the platform. Acts as a runbook index, defines the privileged-actions list, captures the CI/CD posture, and frames the regulated-operations themes (DORA / MiCA / FATF Travel Rule / DAC8) the architecture must support. Compliance brief: 15-Compliance.

Operational priorities

The platform must produce enough visibility to operate without guesswork across:

  • Transaction flow health (failures, stuck states, anomalies).
  • Provider availability + degraded-mode awareness.
  • Reconciliation visibility (operational vs accounting state).
  • Invoice + payout + API-order issue handling.
  • Wallet operational state (planned admin omnibus view — see 06-Admin Console).
  • Merchant + user issues (access, KYC, limits).
  • Admin-sensitive actions (every privileged action lands in audit_log).
  • Policy / content changes (06-Admin Console#Planned Pages section).
  • Environment health (per 12-Environments).

Monitoring areas

Transactions

Operations must see:

  • Failed / stuck transactions with reason codes.
  • Reconciliation-sensitive activity (mismatch between provider event + internal transactions row).
  • Unusual processing patterns (volume spikes, repeated retries).

Today: SQL on transactions + audit_log. Target: dashboards on top of TRES + CloudWatch metrics.

Providers

Operations must understand, for every provider in 05-External Providers:

  • Current health (degraded / out / nominal).
  • Which business areas are affected when degraded.
  • Whether action is needed (manual review, retry, escalation).

Wallets

Operations must review:

  • Omnibus / platform wallet visibility (admin only, see 06-Admin Console#Planned).
  • Send-related issues.
  • Operational anomalies (balance drift vs provider, unexpected deposits).

Merchants + clients

  • Access-related issues.
  • Invitation / subaccount problems (planned 03-Domains#Subaccounts).
  • Limit / fee tier issues.
  • Invoice / payout / API-order escalations.

Webhooks

  • webhook_events queue depth + dead-letter count.
  • Per-merchant delivery failure rate.
  • Retry curve health.

Privileged actions

Actions that must be treated as privileged when triggered from any admin surface:

Action Surface Audit metadata required
Fee changes (per tier or per op override) /admin/fees tier, operation, previous %, next %, actor
Limit changes (planned) /admin/users/[id] user id, limit field, previous, next, actor
Merchant enable / disable (planned) /admin/users/[id] user id, action, reason, actor
Client enable / disable / block /admin/users/[id] user id, action, reason, actor
KYC override /admin/users/[id] user id, previous status, next status, actor
Wallet send (omnibus) (planned) /admin/wallets asset, amount, destination, ticket reference, actor
Page / policy edits + version bumps (planned) /admin/pages page id, version, summary, actor
Merchant API key revoke / rotate /admin/users/[id] api_key_id, action, actor
Subaccount permission grants (planned, merchant-side) subaccount id, allowed sections, actor
Refund / reverse on bad payouts (planned, 09-Open Questions#Admin gaps) original transaction id, reason, actor

Every row above must produce an audit_log entry capturing who, when, where, to which object, with what result.

Permission philosophy

Account Scope
User Own data only — own balance, own history, own product actions
Merchant Merchant-bounded — merchant data, merchant API, merchant subaccount delegation within boundary
Admin Internal role-based — least privilege; not all admins have all sections

Admin role granularity is itself an open question — see 09-Open Questions#Admin role split.

Future runbook index

Concrete runbooks are deferred but the index of expected coverage is fixed:

  • Provider outage response (per provider in 05-External Providers).
  • Fireblocks / CoSigner issue handling.
  • TRES / accounting mismatch handling (target).
  • Invoice issue handling (stuck opened, partial payments, expired-but-paid).
  • Payout issue handling (payout failures, partial-success diagnosis).
  • API-order issue handling (webhook delivery failure, missed deposit).
  • Wallet send review (omnibus).
  • Admin access issue handling (lost 2FA, lockouts).
  • Limit breach handling.
  • Policy version release handling (the popup-on-login flow).
  • DR rehearsal cadence + execution.

Each runbook should reference: which provider/component is involved, who owns it, escalation contact, expected RPO/RTO impact.

CI/CD posture

Direction

  • GitHub or GitLab.
  • CI/CD pipelines per environment.
  • Controlled deployment: Dev → Test → Prod.
  • Reviewable changes, branch / release control, automated validation.

Phasing

Phase AWS build IaC
Initial cutover Manual AWS resource creation None — codify after the topology stabilises
Stabilised Promotion via pipeline Terraform introduced as backup of final infra logic
Steady-state Pipeline-driven Terraform is the source of truth; manual change requires retrofitted commit

Terraform is a late addition — early IaC on an unstable architecture creates rework. See 10-Roadmap.

CI controls

  • Code review.
  • Automated tests (unit + e2e + Bruno).
  • Artifact consistency across envs (same build, different config).
  • Deployment visibility (per-deploy audit trail).
  • Rollback story.

Compliance themes

The architecture must support regulated operating expectations across:

  • Environment separation (12-Environments).
  • Production-like testing posture (Test mirrors Prod).
  • Logging + monitoring (audit_log + CloudWatch + CloudTrail).
  • Backup + recovery (DR per env in 12-Environments).
  • Network segmentation (13-Network-Model).
  • Secure privileged access (AWS IAM Identity Center SSO + MFA, dedicated AWS WAF ruleset, separate admin subdomain).
  • Operational traceability (every privileged action in audit_log).
  • Auditable configuration changes (fee edits, KYC overrides, page versions).
  • Resilience and DR testing.

DORA-relevant themes

The Digital Operational Resilience Act (DORA) is supported through:

  • Environment separation.
  • Production-like Test environment.
  • Logging + monitoring.
  • DB DR for Test + Prod.
  • Provider dependency visibility (the 05-External Providers table).
  • Controlled admin access posture.
  • Documented security boundaries.

MiCA-relevant themes

MiCA-relevant logic is supported through:

  • Traceable transaction handling (transaction-centric model).
  • Controlled platform operations.
  • Accounting + reconciliation clarity (TRES, target).
  • Secure transaction execution path (Fireblocks + CoSigner).
  • Reviewable administrative actions.
  • Provider boundary clarity.

CASP licensing direction tracked under 09-Open Questions#CASP path.

FATF Travel Rule (TFR) — planned

Real-time originator + beneficiary identity attached to every custodial transfer. EU TFR (Regulation 2023/1113) has no de minimis — applies at any amount. The platform must:

  • Transmit IVMS 101 payload alongside every Send / Mass-Payout / API-order outbound.
  • Screen counterparty addresses against OFAC / EU / UK sanctions lists in addition to the existing Elliptic AML risk score.
  • Handle counterparty-VASP discovery (Notabene, Sumsub Travel Rule, Veriscope, Shyft, OpenVASP, or TRP).
  • Treat self-hosted destinations either as user-attested or as third-party beneficiary requiring identity capture.

See 15-Compliance#FATF Travel Rule for the full obligations + engineering surface, and 09-Open Questions#Travel Rule integration for the open vendor decision.

DAC8 / CARF — planned

Annual tax reporting on every customer's crypto activity. Applies from 1 January 2026; first reporting cycle 2027. Requires:

  • TIN + tax-residence collected per user at onboarding.
  • Per-customer per-asset annual aggregation across exchanges, transfers, and reportable payments.
  • CARF/DAC8 XML export to home tax authority.
  • Customer notice of data sharing.
  • 5-year retention minimum.

See 15-Compliance#DAC8 / CARF for scope (broader than Travel Rule — includes self-custody transfers, NFTs, stablecoins) and 09-Open Questions#DAC8 build for the build plan.

Architecture dependencies matrix

Compact cross-area view — useful for impact analysis when one component degrades.

Area Depends on Used by Criticality
User Account CloudFront + WAF, API GW, app containers, TRES, Mercuryo, Sumsub End users, support High
Merchant Account CloudFront + WAF, API GW, app + worker containers, Fireblocks, TRES, Resend Merchants, admin High
Admin Account IAM Identity Center, CloudFront (admin WAF), API GW, ALB, app containers, TRES, Fireblocks, audit log Internal admins Critical
Transactions App + worker containers, providers, TRES interpretation All Critical
Invoices Merchant Account, Transactions, PDF/content Merchant, Admin High
Payouts Merchant Account, Fireblocks, Transactions, accounting Merchant, Admin High
Wallets (admin) Fireblocks, admin operations, accounting Admin Critical
Portfolio TRES / accounting interpretation User, Merchant High
History Transaction model User, Merchant High
AWS edge (Route 53 + CloudFront + AWS WAF + Shield) Public entry, DDoS, rate limit All Critical
AWS IAM Identity Center SSO + MFA for admin entry Internal admins Critical
Fireblocks Send / Receive, payouts, wallets, CoSigner All Critical
TRES Internal ledger / accounting / reconciliation All Critical
Sumsub Verification-dependent access User, Merchant, Admin High
Elliptic AML / risk checks Transaction-sensitive flows High
Mercuryo Buy / Sell iframe User Account Medium
Email provider Invitations, notifications, policy comms All Medium

Use this matrix as a quick reference for outage triage — when X degrades, scan the "Used by" column.

Operational design principle

The architecture must produce enough visibility that operations do not rely on guesswork. If a runbook step needs SSH-into-prod or hand-grepping logs, that's a gap.

Drawbacks

  • Runbook coverage is currently aspirational. The MVP relies on tribal knowledge + audit_log queries.
  • TRES is a planned dependency that the operations workflow leans on heavily; until it's wired, reconciliation is manual SQL.

Open Questions

Cross-references