Skip to content

Epic 02 09 Briefs

Jump to bottom
Tiana_ edited this page May 30, 2026 · 1 revision

Epic-02..09 - Brief decomposition

Detail pages for each epic - compact form. Full task lists migrate to GitHub Issues during sprint planning.

Epic-02: Payments + Idempotency + Outbox

Target release: v0.2.0 Use cases: UC-06, UC-07, UC-08, UC-09

Goal

Ship the payment lifecycle with state machine, idempotency, retries, webhook handling, integration with Ledger and Decision Engine.

Features

  • F-02.1 Payment domain (aggregate, state machine, events log)
  • F-02.2 Payments DB schema (payments, payment_events, processed_webhooks)
  • F-02.3 PaymentService impl (initiate, cancel, retry)
  • F-02.4 BankProvider interface + sandbox impl
  • F-02.5 Inbound webhook handler (HMAC verify, dedup)
  • F-02.6 Scheduled retry job
  • F-02.7 Integration tests (full payment lifecycle, including webhook callback)
  • F-02.8 Property tests (idempotency, state transitions)
  • F-02.9 OpenAPI updates
  • F-02.10 Helm chart updates

Effort: ~140h

Dependencies

  • Blocked by: E-01 Ledger, E-03 Event-Bus, E-05 Decision Engine

Epic-03: Event Bus (Outbox Dispatcher + Kafka)

Target release: v0.2.0

Goal

Reliable event distribution: outbox dispatcher publishes from DB to Kafka, idempotent consumer pattern, retry topics, DLQ.

Features

  • F-03.1 Outbox dispatcher worker (lease-based, SKIP LOCKED)
  • F-03.2 Event Envelope (CloudEvents-aligned)
  • F-03.3 Kafka configuration (Redpanda default, Apache Kafka profile)
  • F-03.4 Topic creation / management
  • F-03.5 Idempotent consumer base class / annotation
  • F-03.6 Retry topic + DLQ pattern
  • F-03.7 Spring Cloud Stream integration
  • F-03.8 Cleanup job (delete published rows)
  • F-03.9 Metrics (pending, lag, failed)
  • F-03.10 Integration tests (Kafka outage, dispatcher restart)

Effort: ~80h

Epic-04: Compliance (KYC + AML + Cases)

Target release: v0.3.0 Use cases: UC-10, UC-11, UC-12

Goal

Compliance orchestration framework: pluggable KYC providers, rule-based AML, human case management with optional AI copilot.

Features

  • F-04.1 Compliance domain (KycSession, AmlAlert, ComplianceCase, AmlRule)
  • F-04.2 DB schema (compliance.*)
  • F-04.3 KycProvider interface + sandbox impl
  • F-04.4 SanctionsProvider interface + sandbox impl
  • F-04.5 AML consumer (subscribes ledger.events.transaction.posted)
  • F-04.6 AML rules engine (uses Decision Engine)
  • F-04.7 Compliance case service (open, claim, resolve, escalate)
  • F-04.8 AmlCopilot interface (LLM plug-in, optional)
  • F-04.9 RuleSynthesizer interface (LLM, optional)
  • F-04.10 Encrypted PII columns (Vault DEK)
  • F-04.11 SAR/STR draft generation (preview, full in Y1 H2)
  • F-04.12 Integration tests + property tests

Effort: ~180h

Dependencies

  • Blocked by: E-01, E-03, E-05

Epic-05: Decision Engine

Target release: v0.2.0 Use cases: UC-13, UC-14 Standalone repo: tiana-code/decision-engine

Goal

Standalone deterministic JSON-DSL rule engine with audit log, replay mode, optional LLM rule synthesis. Standalone library + service.

Features

  • F-05.1 DSL parser + validator (server-side)
  • F-05.2 Evaluator (operators: =, !=, <, <=, >, >=, in, not_in, matches, all/any/none, nested)
  • F-05.3 Rule storage (decision.decision_rules, rule_versions)
  • F-05.4 Decision logs (decision_logs partitioned by month, 7y retention)
  • F-05.5 Replay mode (run new ruleset against historical inputs, diff)
  • F-05.6 RuleSynthesizer plug-in interface (LLM)
  • F-05.7 REST API (/v1/decision/...)
  • F-05.8 Library mode (Maven artifact com.fincore:decision-engine)
  • F-05.9 Performance: p99 < 10ms for ≤100 rules
  • F-05.10 Property tests (determinism)
  • F-05.11 Standalone repo extraction (after v0.2)

Effort: ~120h

Epic-06: Sandbox (Bank, KYC, demo data)

Target release: v0.1.0

Goal

Production-equivalent sandbox: fake bank, fake KYC, deterministic scenarios, seed data for demo.

Features

  • F-06.1 SandboxBankAdapter (success/fail/delay scenarios per amount)
  • F-06.2 SandboxKycProvider (auto-approve / reject / manual review)
  • F-06.3 SandboxSanctionsProvider (deterministic test list)
  • F-06.4 Seed data script (scripts/seed.sh)
  • F-06.5 demo.sh end-to-end script
  • F-06.6 Postman collection
  • F-06.7 docker-compose service entries

Effort: ~50h

Epic-07: Observability (metrics, logs, traces, dashboards)

Target release: v0.1.0

Goal

Production-grade observability: structured logs to Loki, Prometheus metrics, OpenTelemetry traces to Tempo, Grafana dashboards, alerts.

Features

  • F-07.1 Logback config (logstash-encoder, MDC)
  • F-07.2 Micrometer + Prometheus exporter
  • F-07.3 OpenTelemetry SDK + auto-instrumentation
  • F-07.4 ServiceMonitor (Prometheus Operator)
  • F-07.5 PII scrubbing (Logback filter)
  • F-07.6 Custom business metrics (per Architecture-Observability)
  • F-07.7 Grafana dashboards (Service Health, Ledger, Resilience, etc.)
  • F-07.8 Alert rules (P0..P3)
  • F-07.9 docker-compose observability profile

Effort: ~80h

Epic-08: Sandbox UI (React dashboard)

Target release: v0.4.0

Goal

React 19 SPA for sandbox demo: account browser, transaction explorer, payment initiation, decision log viewer, compliance case operator UI.

Features

  • F-08.1 Vite + TypeScript + React 19 setup
  • F-08.2 shadcn/ui component library
  • F-08.3 TanStack Query for API calls
  • F-08.4 OAuth2 PKCE auth (Keycloak)
  • F-08.5 Account browser (list, detail, balance, entries)
  • F-08.6 Transaction explorer
  • F-08.7 Payment initiation form
  • F-08.8 Decision log viewer
  • F-08.9 Compliance case board (operator workflow)
  • F-08.10 Build + Helm packaging

Effort: ~120h

Dependencies

  • Blocked by: E-01, E-02, E-04, E-05

Epic-09: Developer Experience (CLI + SDKs + docs site)

Target release: v0.4.0

Goal

Make adopters productive in 1 hour. CLI for local management, Kotlin/TypeScript SDKs, Docusaurus docs site.

Features

  • F-09.1 CLI tool fincore (Kotlin Native or Go)
    • fincore init - bootstrap project
    • fincore status - health check
    • fincore run-demo - full demo
  • F-09.2 Kotlin SDK (com.fincore:sdk-kotlin)
  • F-09.3 TypeScript SDK (@fincore/sdk-typescript)
  • F-09.4 Postman / Insomnia collection generation
  • F-09.5 Docusaurus docs site (tiana-code/docs)
  • F-09.6 Auto-deploy to GitHub Pages
  • F-09.7 Examples directory (Spring Boot example, Quarkus example, Node.js example)
  • F-09.8 Webhook subscription test harness

Effort: ~150h

Cross-epic considerations

Refactor / migration epics (when needed, post-v1.0)

  • Service extraction from modular monolith (1-2 weeks per service)
  • TigerBeetle adapter integration (Y1 H2 - separate sub-epic)
  • Multi-region replication (v1.5+)
  • SAR/STR auto-reporting (Y1 H2)
  • Compliance-as-Code GitOps (v0.4)

Total v0.1.0 effort

E-01 (190h) + E-06 (50h) + E-07 (80h) = ~320 hours = ~8 weeks at 40h/week.

Maintainable for solo maintainer + Claude assistance over June 2026.

Related

FinCore Engine - open-source fintech core (BSL 1.1 -> Apache 2.0). Repo - Roadmap - Vision

Product

Architecture

Decisions (ADR)

Engineering

Delivery

Risk and Ops

Clone this wiki locally