Knowledge Base
Ask AI View repo

Ecosystem Architecture

Platform layers spanning client products, orchestration, primitives, foundation services, and infrastructure.

Source: docs/02_ecosystem_architecture.md

Ask about this page Copy for LLM View as Markdown Edit on GitHub

Layered Architecture Flow

React Flow interpretation of the high-level platform layering described in the source document.

React Flow

Mermaid View

Mermaid source is preserved for maintainable architecture diagrams.

flowchart TD
    A["Client Products"] --> B["Unified Product API"]
    B --> C["Product Orchestration Layer"]
    C --> D["Primitive Services"]
    D --> E["Foundation Services"]
    E --> F["External Financial Ecosystem"]
    F --> G["Infrastructure"]

Overview

FinFactory is a composable fintech platform built from reusable financial primitives. The ecosystem is organized into several layers: client products, unified API access, product orchestration, primitive services, foundation services, external networks, and infrastructure.

High-level architecture

Client Products
    ↓
Unified Product API
    ↓
Product Orchestration Layer
    ↓
Primitive Services
    ↓
Foundation Services
    ↓
External Financial Ecosystem
    ↓
Infrastructure

Client products

Client products are the fintech applications, platforms, and embedded financial experiences built on top of FinFactory.

Examples include:

  • Stored-value e-wallets
  • Merchant acquiring platforms
  • POS payment solutions
  • QRPh payment products
  • Card issuing programs
  • Healthcare benefits wallets
  • Sharia-compliant wallets
  • Closed-loop merchant wallets
  • Agent-assisted financial operations

Client products should consume a unified API rather than directly coordinating multiple primitives.

Unified Product API

The Unified Product API is the external-facing API layer exposed to a client product.

Its purpose is to hide primitive complexity and present a clean product-specific API.

For example, a stored-value wallet product should expose concepts such as:

  • Customers
  • Wallets
  • Balances
  • Cash-ins
  • Cash-outs
  • QR payments
  • Transfers
  • Transactions
  • Statements

The client should not need to know whether a request touches the KYC service, wallet issuing service, ledger service, QRPh service, or fraud service.

Product orchestration layer

The product orchestration layer coordinates workflows across primitives.

It owns:

  • Product templates
  • Workflow definitions
  • Tenant configuration
  • Feature flags
  • Product limits
  • Routing rules
  • Primitive activation
  • Policy enforcement
  • Cross-service transaction state

The orchestration layer determines which primitives are involved in a product and how they should interact.

Primitive services

Primitive services are independent financial capabilities.

Each primitive should have:

  • Clear bounded context
  • Own database
  • Own public or internal API
  • Own event contracts
  • Own administrative workflows
  • Own audit logs
  • Own operational metrics
  • Own service-level responsibilities

Primitive services should not share databases with each other.

Foundation services

Foundation services are shared platform capabilities used by multiple primitives.

Examples include:

  • Notification service
  • Settlement service
  • Reconciliation service
  • Audit and compliance service
  • Configuration service
  • Feature flag service
  • Webhook service
  • Reporting service
  • Observability stack

Foundation services should be reusable across products and primitives.

External financial ecosystem

FinFactory integrates with regulated and external financial systems.

Examples include:

  • Banks
  • EMI partners
  • Card networks
  • Issuer processors
  • Acquirer processors
  • QRPh and InstaPay participants
  • KYC providers
  • POS hardware providers
  • Payment terminals
  • Settlement banks
  • Compliance data providers

External integrations should be isolated behind specific adapter services or primitive services. Product-facing APIs should not expose provider-specific complexity unless explicitly required.

Infrastructure layer

The infrastructure layer provides the runtime foundation.

It includes:

  • Cloud infrastructure
  • Databases
  • Message bus
  • Cache
  • Object storage
  • Secrets management
  • KMS
  • CI/CD
  • Logging
  • Metrics
  • Tracing
  • Alerting

Infrastructure should support strong isolation, auditability, observability, and reliable financial transaction processing.

Architectural principle

FinFactory should optimize for product composability without sacrificing financial correctness.

This means:

  • Products are flexible
  • Primitive boundaries are strict
  • Ledger behavior is deterministic
  • Money movement is auditable
  • External integrations are isolated
  • AI actions are controlled
  • Configuration is tenant-aware
  • APIs are stable and versioned