Search by

finaegis / core-banking-prototype-laravel

YOzaz

Core Banking Prototype - Educational Demonstration

Package info

github.com/FinAegis/core-banking-prototype-laravel

Type:project

pkg:composer/finaegis/core-banking-prototype-laravel

Fund package maintenance!

YOzaz

Patreon

Buy Me A Coffee

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 211

Open Issues: 8

v7.17.0 2026-11-19 18:47 UTC

This package is auto-updated.

Last update: 2026-11-19 21:28:39 UTC


README

FinAegis is open-source software. Using it does not make a deployment compliant. Licensing and regulatory compliance are the responsibility of the operator of each deployment. Nothing here is legal advice.

CI Pipeline Version License: Apache-2.0 PHP Version Laravel Version PRs Welcome Mobile Ready

An open-source core banking platform built with event sourcing, domain-driven design, and modern financial patterns.

FinAegis provides the foundation for building digital banking applications. The GCU demo is a reference implementation of a basket-referenced unit built with FinAegis, showing how basket valuation and governance modules fit together.

FinAegis vs Zelta: FinAegis is this open-source core-banking platform. Zelta is the hosted product and mobile wallet built on top of it — so production and hosted surfaces (for example the MCP server at mcp.zelta.app) carry the Zelta brand.

Live Demo | Documentation | Quick Start | Contributing

Why FinAegis?

Challenge FinAegis Solution
Building financial systems from scratch 61 domain modules
Audit trail requirements Event sourcing with domain-specific event tables
Complex multi-step transactions Saga pattern with automatic compensation
Regulatory tooling KYC/AML integration + GDPR export/erasure (real); SOC 2 / PCI-DSS readiness tooling — not third-party certified
Multi-tenant SaaS deployment Team-based tenant isolation (v2.0.0)
Hardware wallet security Ledger/Trezor support with multi-sig (v2.1.0)
Mobile wallet backend Biometric auth, passkeys, push notifications (v2.2.0+)
Privacy-preserving transactions ZK-KYC, Merkle trees, ERC-4337 gas abstraction (v2.4.0-v2.6.0)
Multi-jurisdiction RegTech MiFID II / MiCA / FATF Travel Rule report-format validators & adapters — no live regulator connectivity; not a licensed CASP/ARM (v2.8.0)
Cross-chain & DeFi Bridge protocol adapters, DEX aggregation, DeFi protocol adapters (v3.0.0)
Modular plugin architecture 61 domains with manifests, enable/disable, dependency resolution (v3.2.0)
Compliance scaffolding SOC 2 evidence helpers + a clean PCI-DSS SAQ-A footprint (tokenized cards, no PAN stored); no certification is held (v3.5.0)
GraphQL API Schema-first Lighthouse PHP, 45 domains, subscriptions (v4.0.0+)
Event Store v2 Domain routing (61 domains), upcasting, migration tooling (v4.0.0)
Plugin Marketplace Manager, loader, sandbox, security scanner (v4.0.0)
Event streaming Redis Streams publisher/consumer, live dashboard (v5.0.0)
API monetization x402 protocol: HTTP-native micropayments with USDC on Base (v5.2.0)
Privacy protocol RAILGUN shield/unshield/transfer with Merkle proofs (v5.6.0); non-custodial backend migration — public-address registration, on-device engine config, signed-URL RPC proxy (v7.16.0)
Mobile gamification Rewards system: quests, XP/levels, points shop, streaks (v5.7.0)
Fiat on/off ramp adapter Stripe Bridge with async webhook processing and provider-agnostic session management (v5.12.0)
Design system v2 Complete frontend overhaul with consistent typography, dark heroes (v5.12.0)
Developer ecosystem Plugin marketplace, developer portal, 3 official SDKs (v6.0.0)
Post-quantum cryptography ML-KEM-768, ML-DSA-65, hybrid encryption with key rotation (v6.1.0)
Feature completeness Card sync webhooks, bank transfer state machine, tenant provisioning (v6.1.1)
Distributed tracing OpenTelemetry, Zipkin, Jaeger, per-request trace propagation (v6.2.0)
AI agent commerce A2A messaging, DID identity, escrow, reputation framework (v6.3.0)
Machine payments MPP multi-rail (Stripe, USDC, Lightning), AP2 mandates, x402 Solana (v6.4.0)
Payment orchestration (experimental, opt-in) HyperSwitch routing for card deposits behind HYPERSWITCH_ENABLED (off by default — Stripe is the default rail); webhook-credited deposit completion (v6.4.2, wired in #1118)
Mobile launch readiness Quest auto-triggers, device attestation, JIT funding, rewards (v6.5.0)
SMS multi-rail payments VertexSMS integration, MPP-gated SMS, MCP tool for AI agents (v7.10.7)
Public MCP server OAuth-secured Model Context Protocol server at mcp.zelta.app, @finaegis/mcp npm wrapper (v7.11.0)
Non-custodial wallet Privy passkey/device-key signing, sponsored EVM + Solana sends, prepare/submit flow (v7.12.0)
Mobile subscriptions Apple App Store + Google Play IAP verification, pseudonymised receipts, revenue outbox (v7.13.0)
Fiat ↔ stablecoin ramp adapter Bridge.xyz API integration (bank-rail on-ramp, virtual accounts, USDC on Polygon), asymmetric webhook verification. Integration adapter for third-party APIs; no partnership or endorsement implied. (v7.15.0)
Learning modern architecture Complete DDD + CQRS + Event Sourcing example

Named third-party providers: Integration adapters for third-party APIs; no partnership or endorsement implied.

Plugin Architecture (v3.2.0)

FinAegis uses a modular plugin system where each domain is a self-contained module:

php artisan domain:list              # List all 61 domain modules with status
php artisan module:enable exchange   # Enable a module
php artisan module:disable exchange  # Disable a module (preserves data)
php artisan domain:verify exchange   # Verify module health
php artisan performance:report       # Generate performance baseline
  • Module manifests (module.json) define dependencies, interfaces, events, and commands
  • Route isolation — each domain loads its own Routes/api.php via ModuleRouteLoader
  • Admin UI — Filament page at /admin/modules with search, filters, enable/disable actions
  • REST API — GET /api/v2/modules for programmatic module management

GraphQL API (v4.0.0-v4.3.0)

FinAegis provides a schema-first GraphQL API via Lighthouse PHP covering 45 domains:

# Available at /graphql
# Interactive playground at /graphql-playground

# Example query
curl -X POST http://localhost:8000/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ accounts { id name balance currency } }"}'
  • 45 schema imports — 43 domain schemas (Account, AgentProtocol, AI, Asset, Banking, Basket, Exchange, Compliance, Governance, Lending, Treasury, Wallet, X402, …) plus directives and subscriptions; see graphql/schema.graphql for the authoritative list
  • Subscriptions — Real-time updates via WebSocket (account updates, wallet changes, compliance alerts, order matching)
  • DataLoaders — N+1 query prevention with batched loading
  • Security — @guard(with: ["sanctum"]), query cost analysis, introspection control

Event Streaming (v5.0.0)

Redis Streams-based event streaming for real-time data pipelines:

php artisan event-stream:monitor    # Monitor stream health, lag, throughput
  • Event publisher — Publishes domain events to 15 Redis Streams with XADD
  • Consumer groups — XREADGROUP-based consumers with acknowledgement and dead letter handling
  • Live dashboard — 5 REST endpoints for real-time metrics (projector lag, event throughput, domain health)
  • Notification system — Multi-channel notifications (email, push, in-app, webhook, SMS)
  • API gateway — Unified middleware with request ID tracing, timing headers

GCU: The Reference Implementation

The Global Currency Unit (GCU) is a software demonstration — a reference implementation built with FinAegis. It is not issued, offered or sold to anyone and has no monetary value. Any GCU balances, conversions or basket "votes" shown in the demo are simulated. Offering to the public in the EU a token that references a basket of currencies and/or commodities would require authorisation as an asset-referenced token issuer under MiCA (Title III); no such authorisation is held.

The GCU demo — a reference implementation of a basket-referenced unit built with FinAegis — exercises these modules:

  • Multi-Asset Basket - USD (40%), EUR (30%), GBP (15%), CHF (10%), JPY (3%), XAU (2%)
  • Governance module - Simulated votes on basket composition (demo only)
  • Automatic Rebalancing - Monthly adjustment to maintain target weights (simulated in the demo)
  • Basket valuation - Real-time value calculation from component rates
  • Full Integration - Uses Exchange, Governance, Compliance, and Treasury domains

The GCU demo shows how FinAegis primitives fit together.

┌─────────────────────┐
│   GCU Basket        │
├─────────────────────┤
│ USD ████████░░ 40%  │
│ EUR ██████░░░░ 30%  │
│ GBP ███░░░░░░░ 15%  │
│ CHF ██░░░░░░░░ 10%  │
│ JPY █░░░░░░░░░  3%  │
│ XAU █░░░░░░░░░  2%  │
└─────────────────────┘

See ADR-0010: GCU Basket Design for architecture details.

Quick Start

Demo Mode (Recommended)

No external dependencies - everything runs locally:

git clone https://github.com/FinAegis/core-banking-prototype-laravel.git
cd core-banking-prototype-laravel
composer install
cp .env.demo .env
php artisan key:generate
php artisan migrate --seed
npm install && npm run build
php artisan serve

Visit http://localhost:8000 with demo credentials:

  • demo.user@gcu.global / demo123
  • demo.business@gcu.global / demo123
  • demo.investor@gcu.global / demo123

Full Installation

git clone https://github.com/FinAegis/core-banking-prototype-laravel.git
cd core-banking-prototype-laravel
composer install && npm install
cp .env.example .env
php artisan key:generate
# Configure MySQL/PostgreSQL and Redis in .env
php artisan migrate --seed
npm run build
php artisan serve
php artisan queue:work --queue=events,ledger,transactions,transfers,webhooks

Requirements: PHP 8.4+, MySQL 8.0+ / MariaDB 10.3+ / PostgreSQL 13+, Redis 6.0+, Node.js 18+

Modular Installation (v1.3.0+)

Install only the domains you need:

# List available domains
php artisan domain:list

# Install specific domains
php artisan domain:install exchange
php artisan domain:install lending

# Check dependencies
php artisan domain:dependencies exchange

# Verify domain health
php artisan domain:verify
Domain Type Examples Installation
Core (always installed) account, user, compliance, shared Automatic
Financial exchange, lending, treasury, wallet domain:install
AI/Agent ai, agent-protocol, governance domain:install
Infrastructure monitoring, fraud, batch domain:install

See Domain Management Guide for details.

Platform Capabilities

Core Banking

Domain Capabilities
Account Multi-asset accounts, deposits, withdrawals, statements
Banking SEPA/SWIFT transfers, multi-bank routing, reconciliation
Compliance 3-tier KYC, AML screening, SAR/CTR reporting
Treasury Portfolio management and cash-allocation modelling

Digital Assets

Domain Capabilities
Exchange Order matching, liquidity pools, AMM, external connectors, WebSocket streaming
Stablecoin Multi-collateral minting, burning, liquidation
Wallet Non-custodial EVM sends (Polygon, Base, Arbitrum) + Solana; USDC receive on Solana/Tron; Ledger/Trezor hardware-wallet integration
Basket (GCU demo) Weighted currency basket, basket value calculation, rebalancing (simulated demo)

Platform Services

Domain Capabilities
Governance Democratic voting, proposals, asset-weighted strategies
Lending P2P loans, credit scoring, risk assessment
AI Framework MCP server, 20+ banking tools, natural language queries, pattern analysis (v2.8.0)
Agent Protocol A2A messaging, escrow, reputation system
RegTech Reporting and data-exchange modules modelled on MiFID II, MiCA and Travel Rule requirements; 4 jurisdiction report-format adapters — they do not by themselves make a deployment compliant (v2.8.0)
Multi-Tenancy Team-based isolation, tenant-aware event sourcing

Mobile Backend (v2.4.0+)

Domain Capabilities
Key Management Shamir's Secret Sharing (2-of-3), HSM integration
Privacy ZK-KYC verification, Proof of Innocence, selective disclosure
Card Issuance Card-issuing integration adapter (e.g. Marqeta API): virtual card lifecycle, JIT funding
Gas Relayer ERC-4337 meta-transactions, pay fees in USDC
TrustCert W3C Verifiable Credentials, QR/deep link verification
Mobile Biometric auth, push notifications, device management
Mobile Payments Payment intents, activity feed, receipts, USDC on Solana/Tron (v2.7.0)
Passkey Auth WebAuthn/FIDO2 with rpIdHash, UV/UP flags, COSE validation (v2.7.0+v5.7.0)
P2P Transfers Address validation, name resolution, fee quotes (v2.7.0)
Rewards Gamification: XP/levels, quests, points shop, streaks, race-safe redemption (v5.7.0)

API Monetization (v5.2.0)

Domain Capabilities
X402 Protocol HTTP 402 native micropayments, USDC on Base L2, EIP-3009/Permit2 payment schemes
Payment Gate Middleware-based API monetization, per-endpoint pricing, automatic settlement
AI Agent Payments Autonomous payments for AI agents, spending limits, MCP tool integration

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         API / Admin Panel                           │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ Account  │ │ Exchange │ │ Basket   │ │Compliance│ │ Treasury │  │
│  │  Domain  │ │  Domain  │ │  (GCU)   │ │  Domain  │ │  Domain  │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘  │
│       │            │            │            │            │         │
│  ┌────▼────────────▼────────────▼────────────▼────────────▼─────┐  │
│  │                    CQRS + Event Sourcing                      │  │
│  │  Commands → Aggregates → Events → Projectors → Read Models   │  │
│  └──────────────────────────────┬────────────────────────────────┘  │
│                                 │                                    │
│  ┌──────────────────────────────▼────────────────────────────────┐  │
│  │                    Saga / Workflow Engine                      │  │
│  │         Multi-step transactions with compensation              │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

Key Patterns:

  • Event Sourcing - Domain-specific event tables with Event Store v2, replay, and upcasting (v4.0.0)
  • CQRS - Separated read/write models for optimal performance
  • Saga Pattern - Distributed transactions with automatic rollback
  • DDD - 61 bounded contexts with clear boundaries
  • Multi-Tenancy - Team-based data isolation with stancl/tenancy v3.9
  • GraphQL - Schema-first Lighthouse PHP across 45 domains with subscriptions (v4.0.0+)
  • Event Streaming - Redis Streams publisher/consumer with live dashboard (v5.0.0)

See Architecture Decision Records for detailed design rationale.

Documentation

Category Links
Getting Started Quick Start · User Guides
Architecture Overview · ADRs · Roadmap
API REST Reference · OpenAPI · GraphQL
Version History Changelog · Version Roadmap
Development Contributing · Dev Guides
Reference GCU Design · Event Sourcing

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Fork, clone, then:
git checkout -b feature/your-feature
# Make changes with tests
./bin/pre-commit-check.sh --fix
# Submit PR

Standards: PSR-12 · PHPStan Level 8 · 50%+ Coverage · Conventional Commits

This project supports AI coding assistants. Look for AGENTS.md files for context-aware guidance.

Deployment

Kubernetes (v2.1.0+)

Deploy to any Kubernetes cluster with Helm:

# Add Bitnami repo for dependencies
helm repo add bitnami https://charts.bitnami.com/bitnami

# Install with staging values
helm upgrade --install finaegis ./helm/finaegis \
  --values ./helm/finaegis/values-staging.yaml \
  --namespace finaegis-staging \
  --create-namespace

# Install with production values
helm upgrade --install finaegis ./helm/finaegis \
  --values ./helm/finaegis/values-production.yaml \
  --namespace finaegis

Features:

  • Multi-stage Docker build (PHP 8.4-fpm-alpine)
  • Horizontal Pod Autoscaler (CPU, memory, queue depth)
  • Istio service mesh compatible (mTLS, circuit breaker)
  • External Secrets for Vault/AWS integration
  • Prometheus ServiceMonitor for observability
  • Network Policies for pod isolation

See Infrastructure & Deployment Guide for details.

MCP (Model Context Protocol)

Connect Claude Desktop, Cursor, or Continue.dev to your Zelta account:

npx -y @finaegis/mcp

Or use the remote URL directly: https://mcp.zelta.app/mcp. See docs/13-AI-FRAMEWORK/03-MCP-Quickstart.md.

Tech Stack

Layer Technology
Backend Laravel 12, PHP 8.4+
Event Sourcing Spatie Event Sourcing with Event Store v2 (domain routing, upcasting)
GraphQL Lighthouse PHP (schema-first, 45 domains, subscriptions)
Workflows Laravel Workflow (Waterline)
Multi-Tenancy stancl/tenancy v3.9
Database MySQL 8.0+ / MariaDB 10.3+ / PostgreSQL 13+
Cache/Queue/Streaming Redis (cache, queues, Streams), Laravel Horizon
Real-time Soketi (Pusher-compatible), Laravel Echo, Redis Streams
Testing Pest PHP (parallel, 1,170+ test files, 4,900+ tests), PHPStan Level 8
Admin Filament v3
Frontend Livewire, Tailwind CSS
Deployment Docker, Kubernetes (Helm), Istio

Project Status

This is a demonstration platform showcasing modern banking architecture. Use it for:

  • Learning event sourcing and DDD patterns
  • Understanding core banking concepts
  • Building proof-of-concepts
  • Contributing to open-source fintech
  • Studying the GCU demo as a basket reference implementation

Before any production use: The codebase includes CQRS, event sourcing, multi-tenancy, a GraphQL API, event streaming, 50%+ test coverage, PHPStan Level 8 and 4,900+ tests. However, a security audit and compliance review are required before any production deployment, and licensing and regulatory compliance are the responsibility of the operator of each deployment. No third-party SOC 2 or PCI-DSS certification is held — the compliance modules are audit-readiness tooling, and the payment-standards domains (ISO 20022, ISO 8583, SWIFT, Open Banking, SEPA, US rails, Interledger) are reference implementations at the message/logic layer, not live scheme connectivity or settlement. See Security Policy for vulnerability reporting.

Community

License

Apache License 2.0

Built for the open-source financial community