eFiche Patient Billing

Prerequisites

Docker path (recommended)

• Docker Desktop 4.x or later
• docker compose v2 — run docker compose version to verify

Manual path

• PHP 8.4 with extensions: pdo_pgsql, mbstring, xml, zip, bcmath
• Composer 2.x
• PostgreSQL 16
• Node.js 22 LTS
• pnpm 9 — npm i -g pnpm

Docker Compose

From the project root — pick whichever form you prefer:

# Option A — using Make
make up

# Option B — calling the script directly
bash scripts/up.sh

Both commands build images and start all core services in detached mode. Once running:

# Billing console
http://localhost:3001

# API base URL
http://localhost:8001/api

# Swagger UI
http://localhost:8001/swagger

# Documentation site
http://localhost:4000

# Seed demo data (run once, optional)
docker compose --profile seed up backend-seed

Services started by default:

• postgres — PostgreSQL 16 on port 5432
• backend-migrate — one-shot migration runner
• backend-api — Laravel HTTP API on port 8001
• backend-worker — Laravel queue worker
• backend-scheduler — Laravel task scheduler
• frontend — Next.js billing console on port 3001
• docs — Nginx static documentation site on port 4000

Subdomain Routing

An optional Nginx reverse proxy maps three subdomains to the right containers. Enable it by starting with the proxy profile:

docker compose --profile proxy up -d

Then add these lines to your hosts file and access via subdomains on port 80:

# Windows: C:\Windows\System32\drivers\etc\hosts
# Linux / macOS: /etc/hosts

127.0.0.1  billing.localhost
127.0.0.1  api.localhost
127.0.0.1  docs.localhost

Production deployment: see the Production section below for the VPS setup and deploy commands.

Manual Setup

cd eFiche-Billing-Backend
composer install
cp .env.example .env
# Edit .env: DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD
php artisan key:generate
php artisan migrate
php artisan db:seed --class=BillingSeeder
php artisan serve

cd efiche-billing-frontend
pnpm install
cp .env.example .env.local
# NEXT_PUBLIC_API_URL=http://localhost:8000/api
pnpm dev

cd eFiche-Billing-Backend
composer dump-autoload --optimize

Test Data

The landing page has a New Batch button that regenerates 12 varied visit scenarios. You can also run it directly from the terminal:

cd eFiche-Billing-Backend

# Seed facilities, insurers, and coverages (once)
php artisan db:seed --class=BillingSeeder

# Generate 12 varied test visits (re-run any time)
php artisan demo:generate-visits

API Reference

Base URL: http://localhost:8001/api  (or http://api.localhost/api with proxy)

All responses are JSON. Amounts are always integer cents — never floats.

{ "status": "ok", "time": "2026-04-26T10:00:00+00:00" }

Visits

{
  "visit":   { "id": "...", "status": "open" },
  "patient": { "full_name": "Alice Uwase", "mrn": "MRN-001" },
  "facility":{ "name": "Kigali Central Hospital", "currency": "RWF" },
  "invoice": {
    "status": "pending",
    "subtotal_cents": 500000,
    "insurance_covered_cents": 425000,
    "total_cents": 75000,
    "remaining_cents": 75000,
    "items":    [ { "type": "consult", "description": "...", "line_total_cents": 500000 } ],
    "payments": [ { "status": "confirmed", "amount_cents": 0 } ]
  }
}

{
  "insurance_coverage_id": 3,
  "items": [
    { "type": "consult", "description": "OPD", "quantity": 1, "unit_price_cents": 500000 },
    { "type": "lab",     "description": "CBC", "quantity": 1, "unit_price_cents": 150000 }
  ]
}

Insurance

Invoices

Payments

{ "method": "cash", "amount_cents": 75000, "idempotency_key": "a1b2-..." }

Webhooks

{
  "eventId":     "EVT-ABC123",
  "orderNumber": "INV-KXYZ01",
  "status":      "PAYMENT_COMPLETE",
  "amount":      7500000,
  "currency":    "RWF"
}

Debug Stubs

Testing helpers available in all environments. Use these to drive full end-to-end flows without a live eFichePay account.

{ "generated": 12, "message": "Generated 12 test visits with varied billing scenarios." }

Production VPS

The live deployment runs on a DigitalOcean VPS using system Nginx (not Dockerized) for SSL termination, forwarding to the Docker containers.

First-time setup

cp .env.prod.example .env.prod
# Edit .env.prod with real DB password, app key, webhook secret, etc.

# Option A
make init-ssl EMAIL=you@example.com

# Option B
bash scripts/init-ssl.sh you@example.com

Deploying

# Option A
make prod-deploy

# Option B
bash scripts/deploy.sh

# Force full image rebuild after dependency changes
bash scripts/deploy.sh --no-cache

The deploy script pulls the latest code, rebuilds images, restarts containers, and prints the live URLs.

Live URLs

Code Review

Analysis of the three code snippets from the brief — exact failure scenario, corrected implementation, and terminal output proving each bug and fix with real database evidence.

Design Document

Data model, concurrency strategy, offline behavior contract, what was shipped in V1, and explicit V1 exclusions.

Bug Demos

Each artisan command runs against your local database and produces before/after evidence — the bug with real data, then the fix with real data. All demo records are cleaned up automatically.