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.

Live Demo | Documentation | Quick Start | Contributing

Why FinAegis?

GCU: The Reference Implementation

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

See ADR-004: 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+/PostgreSQL 13+, Redis 6.0+, Node.js 18+

Platform Capabilities

Core Banking

Digital Assets

Platform Services

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 - Complete audit trail, temporal queries, replay capability
• CQRS - Separated read/write models for optimal performance
• Saga Pattern - Distributed transactions with automatic rollback
• DDD - 29 bounded contexts with clear boundaries

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 5 · 50%+ Coverage · Conventional Commits

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

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

Not recommended for production use without security audit and compliance review.

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