Code Escrow API – Full Documentation

Overview

A Laravel-based escrow system that manages gigs, freelancers, and transactions. It supports job queues, email notifications, and clean API architecture.

---

🚀 FULL SETUP GUIDE (FROM SCRATCH)

1. Install Laravel Project

composer create-project laravel/laravel code-escrow
cd code-escrow

2. Environment Setup

cp .env.example .env
php artisan key:generate

Update .env:

DB_CONNECTION=mysql
DB_DATABASE=code_escrow
DB_USERNAME=root
DB_PASSWORD=

QUEUE_CONNECTION=database

MAIL_MAILER=smtp
MAIL_HOST=sandbox.smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_FROM_ADDRESS="transaction@yourecapp.com"
MAIL_FROM_NAME="Code Escrow"

---

🧱 DATABASE SETUP

Create Database Tables

php artisan make:model Gig -m
php artisan make:model Freelancer -m
php artisan make:model Transaction -m

Example Migration (Transaction)

Schema::create('transactions', function (Blueprint $table) {
    $table->id();
    $table->foreignId('gig_id')->constrained()->cascadeOnDelete();
    $table->decimal('amount_usd', 10, 2);
    $table->string('status');
    $table->timestamps();
});

Run Migrations

php artisan migrate

---

⚙️ QUEUE SETUP (IMPORTANT)

Create Queue Tables

php artisan queue:table
php artisan migrate

Run Worker

php artisan queue:work

---

📂 PROJECT ARCHITECTURE (WITH FILES)

1. Routes (Switchboard)

📄 routes/api.php

Route::get('/gigs', [GigController::class, 'index']);
Route::post('/gigs', [GigController::class, 'store']);

Route::get('/freelancer', [FreelancerController::class, 'index']);
Route::post('/freelancer', [FreelancerController::class, 'store']);

Route::get('/transaction', [TransactionController::class, 'index']);
Route::patch('/freelancers/refresh-trust', [FreelancerController::class, 'refreshTrust']);

---

2. Bootstrap (Ignition Core)

📄 bootstrap/app.php

• Loads routes
• Registers middleware
• Handles exceptions

(No modification usually needed)

---

3. Requests (Firewall)

php artisan make:request StoreGigRequest

📄 app/Http/Requests/StoreGigRequest.php

public function rules()
{
    return [
        'title' => 'required|string',
        'price' => 'required|numeric'
    ];
}

---

4. Controllers (Traffic Cop)

php artisan make:controller GigController

📄 app/Http/Controllers/GigController.php

public function store(StoreGigRequest $request)
{
    return $this->gigService->create($request->validated());
}

---

5. Services (Engine)

📄 app/Services/GigService.php

class GigService
{
    public function create(array $data)
    {
        return Gig::create($data);
    }
}

---

6. Models (ORM)

📄 app/Models/Transaction.php

class Transaction extends Model
{
    protected $fillable = ['gig_id', 'amount_usd', 'status'];

    public function gig()
    {
        return $this->belongsTo(Gig::class);
    }
}

---

7. Migrations (DB Version Control)

php artisan make:migration create_transactions_table

---

8. Enums (Type Safety)

php artisan make:enum TransactionStatus

📄 app/Enums/TransactionStatus.php

enum TransactionStatus: string
{
    case PENDING = 'pending';
    case RELEASED = 'released';
}

---

9. Factories (Fake Data)

php artisan make:factory TransactionFactory

📄 database/factories/TransactionFactory.php

return [
    'amount_usd' => fake()->randomFloat(2, 10, 500),
    'status' => 'pending'
];

---

10. Seeders (Data Injector)

php artisan make:seeder DatabaseSeeder

📄 database/seeders/DatabaseSeeder.php

Transaction::factory(10)->create();

Run:

php artisan db:seed

---

11. Resources (Serialization)

php artisan make:resource TransactionResource

📄 app/Http/Resources/TransactionResource.php

public function toArray($request)
{
    return [
        'amount' => $this->amount_usd,
        'status' => $this->status,
        'gig' => new GigSummaryResource($this->whenLoaded('gig'))
    ];
}

---

12. Jobs (Background Tasks)

php artisan make:job SendPayoutEmailJob

📄 app/Jobs/SendPayoutEmailJob.php

public function handle()
{
    Mail::to($this->email)->send(new PayoutMail($this->transaction));
}

---

13. Blade View (Email UI)

📄 resources/views/emails/payout.blade.php

<h1>Payment Released</h1>
<p>Amount: {{ $transaction->amount_usd }}</p>

---

14. Mailer (Courier)

php artisan make:mail PayoutMail

📄 app/Mail/PayoutMail.php

public function build()
{
    return $this->view('emails.payout')
                ->with(['transaction' => $this->transaction]);
}

---

🔄 FULL FLOW (IMPORTANT)

1. Request hits api.php
2. Goes to Controller
3. Request validated
4. Service executes logic
5. DB transaction happens
6. Job dispatched
7. Queue processes job
8. Mail sent
9. Resource formats response

---

🧪 TEST JSON PAYLOADS

Create Gig

{
  "title": "Build Laravel API",
  "price": 150
}

Create Freelancer

{
  "name": "John Doe",
  "email": "john@example.com"
}

Refresh Trust

{}

---

🧠 FINAL NOTES

• Always run queue worker for jobs
• Use with('gig') to avoid resource errors
• Never put logic inside controllers
• Services = core brain of your app

---

This README now fully represents your project structure, setup, and execution pipeline.