# NextPayday Borrower API - Architecture Overview

This project is a clean, API-only Laravel 11/13 backend built to handle the borrower system for NextPayday. There is no frontend code (no React, Vue, or Blade views) included, making it a pure, lightweight REST API.

---

## 🏢 Core Folders (Where you write code)

### 1. `app/` (The Brain of the Application)
This is where almost all of your custom backend logic lives.
*   **`app/Http/Controllers/`**: Functions that handle your API requests. If a user hits `POST /api/loan-request`, a controller here receives the data, processes it, and returns the JSON response.
*   **`app/Models/`**: This is where you define your Database tables using Laravel's "**Eloquent ORM**" (e.g., `User`, `Loan`, `Transaction`). Models define relationships (e.g., a User has many Loans).
*   **`app/Providers/`**: Bootstrapping classes that register services when your app starts (mostly handled by Laravel automatically).

### 2. `routes/` (The Traffic Cop)
This defines your URL endpoints.
*   **`routes/api.php`**: **(You will use this 99% of the time)**. This is where you define your REST API endpoints (`GET`, `POST`, `PUT`, `DELETE`). Anything defined here automatically gets prefixed with `/api` (e.g. `http://localhost:8000/api/users`). It also automatically strips out session cookies since APIs should be stateless.
*   **`routes/web.php`**: You can mostly ignore this. It's for loading HTML views, but since you're building an API, you might only use this for a simple standard homepage (like `return response()->json(['status' => 'API is running']);`).
*   **`routes/console.php`**: For defining custom terminal console commands (e.g. `php artisan schedule:run`).

### 3. `database/` (Data & Structure)
Everything related to shaping your Database (SQLite currently).
*   **`database/migrations/`**: These are PHP scripts that act as schema "version control". Instead of writing raw SQL to make an `accounts` table, you write a migration file. 
*   **`database/seeders/`**: Used to generate dummy data/admin users for local testing.
*   **`database/factories/`**: Blueprints for generating fake data (helpful when you want 100 fake users for testing).

### 4. `config/` (Settings & Setup)
Contains framework configurations. You rarely change files in here directly. Instead, you usually set values in the `.env` file, and the `/config` folder automatically pulls from `.env`.

---

## ⚙️ Supporting Folders

*   **`bootstrap/`**: Contains the `app.php` file, which sets up middleware and exception handling, and boots the framework. 
*   **`public/`**: The strictly public-facing folder. It holds the `index.php` file (the single entry point for all requests). 
*   **`storage/`**: Where Laravel stores generated files, like application logs (`storage/logs/laravel.log`). **If you get an error, `storage/logs/laravel.log` is the first place you look.**
*   **`tests/`**: Where you write automated PHPUnit tests.
*   **`vendor/`**: Your dependencies. This is where Composer installs all the framework core code and third-party packages. **Never edit files in here.** 

---

## 📝 Key Files
*   **`.env`**: Your secret environment variables. Holds your DB passwords, secret API keys (like Paystack). **Never commit this to GitHub.**
*   **`composer.json`**: Lists your PHP package dependencies mapping.
*   **`artisan`**: The powerhouse CLI tool! You'll use this constantly to create files automatically.

---

## 🎯 Usecase Work Flow Example: Building a "Loan Request" Feature

If you were going to build a new feature to let users request a loan right now, the pure-backend workflow looks like this:

1. **Scaffold:** Run `php artisan make:model Loan -mfc` in the terminal.
   *(This creates a Model, a Migration for the DB table, a Factory, and a Controller all at once)*
2. **Database:** Open `database/migrations/...create_loans_table.php` and add columns like `$table->decimal('amount')` and `$table->string('status')`. Run `php artisan migrate` to create the table.
3. **Routing:** Open `routes/api.php` and add: `Route::post('/loans', [LoanController::class, 'store']);`
4. **Logic:** Open `app/Http/Controllers/LoanController.php` and write the precise logic to receive the user's data payload, check their ledger/balance, and save the Loan to the database.