README

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 Global Currency Unit (GCU) serves as a complete reference implementation demonstrating how to build basket currencies, governance systems, and democratic financial instruments on this platform.

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?

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

┌─────────────────────┐
│   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

See Domain Management Guide for details.

Platform Capabilities

Core Banking

Digital Assets

Platform Services

Mobile Backend (v2.4.0+)

API Monetization (v5.2.0)

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

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

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 GCU as a basket currency reference

Production Readiness: The codebase includes production-grade infrastructure (CQRS, event sourcing, multi-tenancy, GraphQL API, event streaming, 50%+ test coverage, PHPStan Level 8, 4,900+ tests). However, a security audit and compliance review are required before any production deployment. See Security Policy for vulnerability reporting.

Community

• GitHub Discussions - Questions & Ideas
• GitHub Issues - Bug Reports
• Security Policy - Vulnerability Reporting
• Code of Conduct - Community Guidelines
• Changelog - Version History

License

Apache License 2.0

Built for the open-source financial community