Skip to content

About

High-performance payment gateway API built with Symfony 8, PHP 8.4 and MySql 8

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Symfony Funds Transfer System

A high-performance, secure, and scalable Fintech API designed to handle real-time money transfers between accounts. Built with Symfony 8 and PHP 8.4, this project demonstrates enterprise-grade software engineering practices, adhering to strict Domain-Driven Design (DDD) and Hexagonal Architecture principles.

🚀 Installation & Setup

Prerequisites

  • Docker and Docker Compose installed
  • Git

Installation Steps

  1. Clone the repository

    git clone YOUR_REPOSITORY_URL
    cd symfony
  2. Initialize the project (First time setup)

    make init-fresh

    This command will:

    • Build Docker images (PHP 8.4, MySQL 8, Redis, Nginx, Mailpit)
    • Start all containers automatically
    • Install Composer dependencies (composer install)
    • Generate JWT authentication keys
    • Run database migrations (php bin/console doctrine:migrations:migrate)
    • Load test fixtures (php bin/console doctrine:fixtures:load)
    • Generate OpenAPI JSON file (php bin/console app:generate-openapi)

    Note: The servers are automatically started as part of init-fresh, so you don't need to run make start separately.

  3. Verify installation

    make test

    Select option 4 or 5 to run the full test suite.

Running the Application

The API will be available at http://localhost/api once containers are running.

Start containers (if stopped):

make start

Stop containers:

make down

View logs:

make logs

Access PHP container shell:

make shell

Key Commands

  • make init-fresh: Full project initialization (first time setup)
  • make init: Standard initialization (uses Docker cache)
  • make test: Interactive test runner menu
  • make generate-openapi: Generate OpenAPI JSON file for API documentation
  • make seed: Run migrations and load fixtures
  • make migrate: Run pending migrations
  • make generate-jwt: Generate new JWT keys

💾 Database Access

You can connect to the MySQL database using one of the following methods:

Method 1: Using Docker (Recommended)

This method works regardless of your local MySQL client version and avoids authentication plugin compatibility issues:

# Check your database name in .env (MYSQL_DATABASE) or use the default
docker compose exec mysql mysql -u app_user -papp_pass symfony_db

Or if using the default database name (app_db):

docker compose exec mysql mysql -u app_user -papp_pass app_db

Method 2: From Host Machine

Connection Details:

  • Host: 127.0.0.1 (or localhost)
  • Port: 3306
  • Database: symfony_db (or app_db if using default)
  • User: app_user
  • Password: app_pass

Example CLI connection:

mysql -h 127.0.0.1 -P 3306 -u app_user -papp_pass symfony_db

Note:

  • If you encounter authentication plugin errors (e.g., mysql_native_password cannot be loaded), use Method 1 (Docker) instead.
  • The database uses caching_sha2_password authentication (MySQL 8.0+ default) for better compatibility with modern MySQL clients.
  • If you have an existing database created with the old authentication plugin, you may need to recreate it: make down && make init-fresh

🌐 API Documentation

Interactive API Documentation:

http://localhost/api-docs/index.html

OpenAPI Specification:

http://localhost/api-docs/openapi.json

Default Test Credentials:

  • Email: api@example.com
  • Password: secure123

Generate a test token:

docker compose exec php bin/console app:auth:generate-token --email=api@example.com

🔒 Security Features

  • Rate Limiting: Implemented on authentication (5/min) and transfer endpoints (10/min, configurable for stress testing) to prevent abuse
  • JWT Authentication: Stateless RS256-based authentication for all API endpoints
  • Idempotency: POST requests support Idempotency-Key header to prevent duplicate processing
  • Pessimistic Locking: Financial transactions use SELECT ... FOR UPDATE to prevent race conditions
  • CSRF Protection: Not required (API-only, stateless authentication) - see Security Documentation
  • Input Validation: JSON content-type enforcement and request validation via DTOs

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

📋 Architecture Decisions Summary

This project follows several key architectural principles:

  • Hexagonal Architecture: Strict separation of Domain (business logic), Application (use cases), and Infrastructure (framework adapters)
  • PHP 8.4 Modern Features: Constructor property promotion, readonly classes, property hooks
  • Strict Typing: All PHP files use declare(strict_types=1);
  • Domain-Driven Design: Rich domain models with value objects (Money, Currency, AccountId)
  • Event-Driven: Side effects (emails) are handled asynchronously via Symfony Messenger
  • ACID Compliance: All financial operations are wrapped in database transactions with pessimistic locking
  • Hybrid Ledger: Balance snapshots for performance + immutable transaction records for auditability

For detailed architecture documentation, see docs/ARCH.md and docs/CONFIG.md.

✅ Quality Assurance & Validation

The codebase has been thoroughly validated and is production-ready:

  • ✅ Database Schema: Validated and in sync with entity mappings
  • ✅ Static Analysis: PHPStan Level 9 (max) - No errors
  • ✅ Test Coverage: 71.36% line coverage, 76.32% method coverage, all critical paths tested
  • ✅ Stress Testing: 200/200 concurrent requests successful, ACID guarantees verified
  • ✅ Code Style: All files conform to PHP-CS-Fixer standards
  • ✅ Security: Rate limiting, JWT auth, input validation all working

⏱️ Time Spent

Total approximate time spent: ~30 hours

Development Tasks (~20 hours)

  • Architecture design and planning: ~3 hours

    • Hexagonal architecture design
    • Domain-Driven Design (DDD) modeling
    • Technical decision documentation (ADR)
  • Infrastructure setup: ~2 hours

    • Docker environment configuration
    • Database setup and migrations
    • Redis and caching configuration
    • Nginx configuration
  • Domain model implementation: ~4 hours

    • Value objects (AccountId, Money, Currency, etc.)
    • Domain entities (Account, Transaction, BatchTransfer)
    • Domain services (FundTransferService)
    • Domain exceptions
  • Application layer: ~3 hours

    • Use cases (TransferFundsUseCase, ProcessBatchTransferUseCase)
    • DTOs and message handlers
    • Event handling
  • Infrastructure adapters: ~3 hours

    • Doctrine repositories
    • Controllers and API endpoints
    • Event subscribers and listeners
    • Security components
  • Testing: ~3 hours

    • Unit tests (Domain, Application, Infrastructure layers)
    • Integration tests
    • Functional API tests
    • Stress testing scripts
  • Documentation: ~2 hours

    • Architecture documentation (ARCH.md)
    • Configuration documentation (CONFIG.md)
    • Testing documentation (TESTING.md)
    • Security documentation (SECURITY.md)
    • Production deployment guide (PRODUCTION.md)

Refactoring & Manual Cleanups (~10 hours)

  • Code quality improvements and PHPStan fixes
  • PHPUnit test fixes and coverage improvements
  • Code style fixes (PHP-CS-Fixer)
  • Documentation updates and consistency
  • API documentation (OpenAPI) generation and setup
  • Nginx configuration refinements
  • Makefile improvements
  • README consolidation and cleanup

🤖 AI Tools & Prompts Used

This project was developed using a combination of AI-assisted development tools:

AI Tools

  • Google AI Studio (Gemini 3 Preview): Initial prompt building and architecture planning
  • Gemini CLI: 70-80% of slow, thoughtful AI-driven coding
  • Cursor: Final refactoring, documentation building, and code quality improvements

Models Used

  • Gemini 2.5: Architecture and design decisions
  • Gemini 3: Core implementation and business logic
  • Gemini 2.5 Flash: Fast iteration and code generation via Gemini CLI
  • GPT 5.1 & GPT 5.2: Code review and optimization in Cursor
  • Composer 1: Code generation assistance
  • Opus 4.5: Final refactoring and documentation in Cursor

Development Process

For detailed prompts and development workflow, see current/begin.md.

The development followed a structured approach:

  1. Architecture Phase: Defined hexagonal architecture, DDD principles, and technical standards
  2. Infrastructure Phase: Docker setup, database configuration, and development environment
  3. Implementation Phase: Iterative TDD approach with domain models, use cases, and infrastructure adapters
  4. Quality Assurance: Comprehensive testing, static analysis, and code quality improvements
  5. Documentation: Architecture decisions, configuration details, and usage documentation

About

High-performance payment gateway API built with Symfony 8, PHP 8.4 and MySql 8

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages