update README.md
This commit is contained in:
Meghdad
293
README.md
293
README.md
@@ -1,58 +1,279 @@
|
||||
<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>
|
||||
# BankFlow
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
|
||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
|
||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
|
||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
|
||||
</p>
|
||||
BankFlow is a Laravel API for creating and processing bank loan applications through configurable, type-specific workflows.
|
||||
|
||||
## About Laravel
|
||||
Each loan is assigned an immutable published workflow configuration when it is created. Administrators can create draft configurations, select and order supported stages, define stage-specific rules, and publish a new version for a loan type without changing loans already in progress.
|
||||
|
||||
Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:
|
||||
## Project status
|
||||
|
||||
- [Simple, fast routing engine](https://laravel.com/docs/routing).
|
||||
- [Powerful dependency injection container](https://laravel.com/docs/container).
|
||||
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
|
||||
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
|
||||
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
|
||||
- [Robust background job processing](https://laravel.com/docs/queues).
|
||||
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).
|
||||
The repository is currently in the **blueprint and scaffolding phase**. The Laravel application skeleton and project documentation exist, but the BankFlow models, API routes, workflow engine, PostgreSQL schema, admin configuration endpoints, and Docker image have not yet been implemented.
|
||||
|
||||
Laravel is accessible, powerful, and provides tools required for large, robust applications.
|
||||
The approved implementation plan is documented in [Project Blueprint](docs/project-blueprint.md).
|
||||
|
||||
## Learning Laravel
|
||||
## Documentation
|
||||
|
||||
Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework.
|
||||
| Document | Description |
|
||||
| --- | --- |
|
||||
| [Challenge requirements](docs/bank-flow.md) | Functional requirements, business rules, and deliverables |
|
||||
| [API reference](docs/api-routes.md) | Public routes, request bodies, responses, and processing rules |
|
||||
| [Project blueprint](docs/project-blueprint.md) | Architecture, models, database schema, workflow design, and test plan |
|
||||
|
||||
In addition, [Laracasts](https://laracasts.com) contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.
|
||||
## Technology stack
|
||||
|
||||
You can also watch bite-sized lessons with real-world projects on [Laravel Learn](https://laravel.com/learn), where you will be guided through building a Laravel application from scratch while learning PHP fundamentals.
|
||||
- PHP 8.4
|
||||
- Laravel 13
|
||||
- PostgreSQL
|
||||
- Eloquent ORM
|
||||
- Pest 4
|
||||
- Laravel Pint
|
||||
- Docker
|
||||
|
||||
## Agentic Development
|
||||
## Architecture
|
||||
|
||||
Laravel's predictable structure and conventions make it ideal for AI coding agents like Claude Code, Cursor, and GitHub Copilot. Install [Laravel Boost](https://laravel.com/docs/ai) to supercharge your AI workflow:
|
||||
BankFlow uses a layered Laravel architecture with domain grouping and single-purpose Actions.
|
||||
|
||||
```bash
|
||||
composer require laravel/boost --dev
|
||||
|
||||
php artisan boost:install
|
||||
```text
|
||||
HTTP Request
|
||||
↓
|
||||
Form Request
|
||||
↓
|
||||
Controller
|
||||
↓
|
||||
Action
|
||||
↓
|
||||
Workflow Engine / Eloquent
|
||||
↓
|
||||
PostgreSQL
|
||||
```
|
||||
|
||||
Boost provides your agent 15+ tools and skills that help agents build Laravel applications while following best practices.
|
||||
Important architectural decisions:
|
||||
|
||||
## Contributing
|
||||
- Controllers remain thin and contain no business rules.
|
||||
- Application operations use dedicated Action classes instead of a generic service layer.
|
||||
- Eloquent is used directly; no Repository layer is introduced.
|
||||
- Workflow stages are stateless classes with one responsibility each.
|
||||
- Loan processing is synchronous and runs inside one database transaction.
|
||||
- Row locking and database uniqueness constraints prevent duplicate stage execution.
|
||||
- Expected business outcomes are persisted as loan history; Laravel logs are reserved for unexpected operational errors.
|
||||
- Queues, microservices, CQRS, Event Sourcing, and a generic Rule Engine are outside the project scope.
|
||||
|
||||
Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).
|
||||
## Configurable workflows
|
||||
|
||||
## Code of Conduct
|
||||
Workflow configuration is stored in PostgreSQL and belongs to a specific `loan_type_id`.
|
||||
|
||||
In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).
|
||||
```text
|
||||
LoanType
|
||||
└── WorkflowConfiguration
|
||||
└── WorkflowConfigurationStep
|
||||
└── StageDefinition
|
||||
```
|
||||
|
||||
## Security Vulnerabilities
|
||||
Configuration lifecycle:
|
||||
|
||||
If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.
|
||||
1. An administrator creates a draft for a loan type.
|
||||
2. Supported stages are selected and ordered.
|
||||
3. Stage-specific rules are stored as validated JSON.
|
||||
4. The complete workflow is validated.
|
||||
5. Publishing archives the previous version and makes the new version immutable.
|
||||
6. New loans use the new published version.
|
||||
7. Existing loans continue using their originally assigned version.
|
||||
|
||||
## License
|
||||
The database stores stable stage codes, not executable PHP or SQL. A trusted application registry maps each code to its handler class.
|
||||
|
||||
The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
|
||||
## Domain model
|
||||
|
||||
Primary models:
|
||||
|
||||
- `LoanType`
|
||||
- `StageDefinition`
|
||||
- `WorkflowConfiguration`
|
||||
- `WorkflowConfigurationStep`
|
||||
- `Loan`
|
||||
- `LoanHistory`
|
||||
|
||||
The domain keeps three concepts separate:
|
||||
|
||||
| Concept | Values |
|
||||
| --- | --- |
|
||||
| Loan status | `SUBMITTED`, `IN_PROGRESS`, `MANUAL_REVIEW`, `APPROVED`, `REJECTED` |
|
||||
| Workflow stage | `VALIDATION`, `FRAUD_CHECK`, `GUARANTOR_CHECK`, `CREDIT_CHECK`, `MANAGER_APPROVAL` |
|
||||
| Stage result | `PASS`, `FAIL`, `MANUAL_REVIEW` |
|
||||
|
||||
## Default workflows
|
||||
|
||||
### Personal loan
|
||||
|
||||
```text
|
||||
VALIDATION
|
||||
↓
|
||||
FRAUD_CHECK
|
||||
↓
|
||||
CREDIT_CHECK
|
||||
↓
|
||||
MANAGER_APPROVAL (when applicable)
|
||||
↓
|
||||
APPROVED
|
||||
```
|
||||
|
||||
### Business loan
|
||||
|
||||
```text
|
||||
VALIDATION
|
||||
↓
|
||||
FRAUD_CHECK
|
||||
↓
|
||||
GUARANTOR_CHECK
|
||||
↓
|
||||
CREDIT_CHECK
|
||||
↓
|
||||
MANAGER_APPROVAL (when applicable)
|
||||
↓
|
||||
APPROVED
|
||||
```
|
||||
|
||||
A `FAIL` result immediately rejects the loan. A `MANUAL_REVIEW` result stops automatic processing and moves the loan to manual review.
|
||||
|
||||
## Public API
|
||||
|
||||
| Method | Route | Description |
|
||||
| --- | --- | --- |
|
||||
| `POST` | `/api/v1/loans` | Create a loan application |
|
||||
| `POST` | `/api/v1/loans/{loanId}/process` | Process all remaining workflow stages |
|
||||
| `GET` | `/api/v1/loans/{loanId}` | Get a loan application |
|
||||
| `GET` | `/api/v1/loans/{loanId}/history` | Get processing history |
|
||||
| `GET` | `/health` | Check service health |
|
||||
|
||||
One call to the process route runs all remaining applicable stages until the loan becomes `APPROVED`, `REJECTED`, or `MANUAL_REVIEW`. Calling it again after a terminal status returns the current state without rerunning stages or adding history.
|
||||
|
||||
See [API Reference](docs/api-routes.md) for request and response examples.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
For local development:
|
||||
|
||||
- PHP 8.4 with the PostgreSQL extension
|
||||
- Composer
|
||||
- PostgreSQL
|
||||
- Node.js and npm for frontend asset compilation
|
||||
|
||||
Laravel Herd may be used for the local PHP runtime and site management.
|
||||
|
||||
## Local setup
|
||||
|
||||
Install dependencies and create the environment file:
|
||||
|
||||
```bash
|
||||
composer install
|
||||
cp .env.example .env
|
||||
php artisan key:generate
|
||||
npm install
|
||||
```
|
||||
|
||||
Configure PostgreSQL in `.env`:
|
||||
|
||||
```dotenv
|
||||
DB_CONNECTION=pgsql
|
||||
DB_HOST=127.0.0.1
|
||||
DB_PORT=5432
|
||||
DB_DATABASE=bankflow
|
||||
DB_USERNAME=postgres
|
||||
DB_PASSWORD=
|
||||
```
|
||||
|
||||
After the BankFlow migrations and seeders are implemented, initialize the database with:
|
||||
|
||||
```bash
|
||||
php artisan migrate --seed
|
||||
```
|
||||
|
||||
Build frontend assets when required:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Run the complete Pest suite:
|
||||
|
||||
```bash
|
||||
php artisan test --compact
|
||||
```
|
||||
|
||||
Run a focused test:
|
||||
|
||||
```bash
|
||||
php artisan test --compact --filter=ProcessLoanTest
|
||||
```
|
||||
|
||||
The planned suite covers:
|
||||
|
||||
- unit tests for every workflow stage;
|
||||
- workflow order, stopping behavior, and rule validation;
|
||||
- workflow configuration draft and publication behavior;
|
||||
- public API feature tests;
|
||||
- admin configuration authorization and validation;
|
||||
- idempotent and concurrent processing;
|
||||
- PostgreSQL persistence and history ordering.
|
||||
|
||||
## Code style
|
||||
|
||||
Format modified PHP files with:
|
||||
|
||||
```bash
|
||||
vendor/bin/pint --dirty --format agent
|
||||
```
|
||||
|
||||
## Docker
|
||||
|
||||
The completed project must support the challenge commands:
|
||||
|
||||
```bash
|
||||
docker build -t bankflow .
|
||||
docker run -p 8080:8080 bankflow
|
||||
```
|
||||
|
||||
The service must become ready within 60 seconds and preserve loan data across an application process restart.
|
||||
|
||||
> **Current status:** the required `Dockerfile` has not been implemented yet, so these commands do not work in the current repository state.
|
||||
|
||||
## Planned project structure
|
||||
|
||||
```text
|
||||
app/
|
||||
├── Actions/
|
||||
│ ├── Loan/
|
||||
│ └── WorkflowConfiguration/
|
||||
├── Domain/
|
||||
│ └── Loan/
|
||||
│ ├── Contracts/
|
||||
│ ├── Data/
|
||||
│ ├── Enums/
|
||||
│ └── Workflow/
|
||||
├── Http/
|
||||
│ ├── Controllers/
|
||||
│ ├── Requests/
|
||||
│ └── Resources/
|
||||
└── Models/
|
||||
|
||||
database/
|
||||
├── factories/
|
||||
├── migrations/
|
||||
└── seeders/
|
||||
|
||||
tests/
|
||||
├── Feature/
|
||||
└── Unit/
|
||||
```
|
||||
|
||||
The complete file and class layout is defined in [Project Blueprint](docs/project-blueprint.md#4-project-structure).
|
||||
|
||||
## Implementation principles
|
||||
|
||||
- Do not add behavior that is absent from the requirements or approved blueprint.
|
||||
- Do not allow clients to select `workflow_configuration_id`; the server selects the published configuration for the requested loan type.
|
||||
- Do not edit a published workflow configuration. Create and publish a new version.
|
||||
- Do not store executable class names, PHP, SQL, or unrestricted expressions in admin-managed rules.
|
||||
- Do not perform business validation in a way that bypasses workflow history.
|
||||
- Do not process one stage per API call; one process request runs to a terminal automatic-processing status.
|
||||
- Keep documentation synchronized with the implemented behavior.
|
||||
|
||||
Reference in New Issue
Block a user