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.
- Docker and Docker Compose installed
- Git
-
Clone the repository
git clone YOUR_REPOSITORY_URL cd symfony -
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 runmake startseparately. -
Verify installation
make testSelect option
4or5to run the full test suite.
The API will be available at http://localhost/api once containers are running.
Start containers (if stopped):
make startStop containers:
make downView logs:
make logsAccess PHP container shell:
make shellmake init-fresh: Full project initialization (first time setup)make init: Standard initialization (uses Docker cache)make test: Interactive test runner menumake generate-openapi: Generate OpenAPI JSON file for API documentationmake seed: Run migrations and load fixturesmake migrate: Run pending migrationsmake generate-jwt: Generate new JWT keys
You can connect to the MySQL database using one of the following methods:
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_dbOr if using the default database name (app_db):
docker compose exec mysql mysql -u app_user -papp_pass app_dbConnection 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_dbNote:
- If you encounter authentication plugin errors (e.g.,
mysql_native_password cannot be loaded), use Method 1 (Docker) instead. - The database uses
caching_sha2_passwordauthentication (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
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- 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-Keyheader to prevent duplicate processing - Pessimistic Locking: Financial transactions use
SELECT ... FOR UPDATEto 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
Comprehensive documentation is available in the docs/ directory:
- System Architecture: C4 diagrams and architecture rationale
- Architectural Decision Records: Key technical decisions
- Configuration Decisions: Configuration details
- Security Documentation: Security features and practices
- Testing Documentation: Testing strategy and coverage
- Production Deployment: Production setup guide
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.
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
Total approximate time spent: ~30 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)
- 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
This project was developed using a combination of AI-assisted development 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
- 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
For detailed prompts and development workflow, see current/begin.md.
The development followed a structured approach:
- Architecture Phase: Defined hexagonal architecture, DDD principles, and technical standards
- Infrastructure Phase: Docker setup, database configuration, and development environment
- Implementation Phase: Iterative TDD approach with domain models, use cases, and infrastructure adapters
- Quality Assurance: Comprehensive testing, static analysis, and code quality improvements
- Documentation: Architecture decisions, configuration details, and usage documentation