Architecture Overview

The CPR (Clinical Patient Records) system is a multi-branch ophthalmic clinic management platform built with Laravel 12 serving as a RESTful API backend.

System Architecture

┌─────────────────────────────────────────────────────┐
│                   Frontend (SPA)                     │
│            Vue 3 + Inertia.js / API Client           │
└──────────────────────┬──────────────────────────────┘
                       │ HTTP / JSON
                       │ Authorization: Bearer <token>
                       │ X-Branch-Id: <branch_id>
┌──────────────────────▼──────────────────────────────┐
│                  Laravel 12 API                      │
│                                                      │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │  Sanctum    │  │  Middleware   │  │  Rate      │  │
│  │  Auth       │  │  Branch Ctx  │  │  Limiting  │  │
│  └──────┬──────┘  └──────┬───────┘  └─────┬──────┘  │
│         │                │                 │         │
│  ┌──────▼────────────────▼─────────────────▼──────┐  │
│  │              Controllers (API v1)              │  │
│  └──────────────────────┬─────────────────────────┘  │
│                         │                            │
│  ┌──────────────────────▼─────────────────────────┐  │
│  │           Services (Business Logic)            │  │
│  │         Actions  │  Pipelines  │  DTOs         │  │
│  └──────────────────────┬─────────────────────────┘  │
│                         │                            │
│  ┌──────────────────────▼─────────────────────────┐  │
│  │        Repositories (Data Access Layer)         │  │
│  │         Contracts / Interfaces                  │  │
│  └──────────────────────┬─────────────────────────┘  │
│                         │                            │
│  ┌──────────────────────▼─────────────────────────┐  │
│  │        Eloquent Models + Resources              │  │
│  └──────────────────────┬─────────────────────────┘  │
│                         │                            │
└─────────────────────────┼────────────────────────────┘
                          │
              ┌───────────▼───────────┐
              │    MySQL 8.4 / SQLite │
              │    Redis 7 (cache)    │
              └───────────────────────┘

Technology Stack

Layer	Technology	Version
Framework	Laravel	12.0
Language	PHP	8.2+
Database	MySQL (prod) / SQLite (dev)	8.4
Cache & Queue	Redis	7
Auth	Laravel Sanctum	4.0
RBAC	Spatie Laravel Permission	6.23
Audit Logging	Spatie Activity Log	4.12
Error Tracking	Sentry	4.20
API Docs	Dedoc Scramble	0.13
Testing	Pest PHP	4.1
Static Analysis	PHPStan (Larastan)	3.0
Containers	Docker (Laravel Sail)	-
Image Processing	Intervention Image	3.0

Design Patterns

The codebase follows a layered architecture with clear separation of concerns:

Repository Pattern

All data access is abstracted through repositories that implement contracts (interfaces). This decouples business logic from the database layer.

Controller → Service → Repository → Model → Database

Service Layer

Services orchestrate business logic and coordinate between repositories, actions, and pipelines. Controllers never access repositories directly.

Action Pattern

Single-responsibility command classes that encapsulate discrete operations (e.g., CreateBranchAction, ToggleMedicineStatusAction).

Pipeline Pattern

Sequential processing chains for complex workflows like patient creation and password resets. Each step is a class with a handle($data, Closure $next) method.

DTO Pattern

Data Transfer Objects carry validated data between layers, especially through pipelines.

Multi-Branch Architecture

The system supports multiple clinic branches with data isolation. Branch context is enforced via the EnsureBranchContext middleware, which resolves the branch from:

1. X-Branch-Id HTTP header (primary)
2. branch_id query parameter (fallback)
3. User's default_branch_id (last resort)

Branch-scoped routes ensure that patients, visits, queues, and billing data are isolated per branch.

Key Modules

Module	Description
Patient Management	Registration, search, export, demographics, top-occupation analytics
Patient Duplicates	patient-duplicates:scan artisan command + admin UI for merge/dismiss
Patient Visits	Visit tracking, plans, follow-ups
Clinical Examinations	14+ ophthalmic exam types (tonometry, refraction, slit lamp, biometry, indirect ophthalmoscopy + PRP, etc.)
Queue System	Service-based queue with tickets, transfers, priority types
Queue Reservations	Pre-booking for a future date; daily capacity guard + scheduled no-show marking
Billing	Transactions, bill items, payment methods, insurance
Pharmacy	Inventory, stock tracking, purchase orders, deliveries
Surgery	Scheduling, locations, doctor assignments
Administration	Branches, roles, permissions, audit logging, database backups
Data Migration	Legacy MS Access importer, data-mappings UI, import history (three independent permissions)

Canonical reference data

A few patient fields store canonical codes rather than free text — translated via App\Support\* classes and the data-mappings layer at import time:

Field	Storage	Source class
nationality	ISO-like code, e.g. phl, phl-cebuano	App\Support\Nationalities
occupation	Short job code, e.g. ACC, ENG	App\Support\Occupations
civil_status	Single character: S, M, W, D, A, P	App\Enums\PatientCivilStatusEnum

Pre-existing rows imported before 2026-05-25 may still hold raw adjectives or free text (no backfill). See memory: patient-demographic-storage.

Next Steps

• Backend Documentation - Detailed backend guide
• Backend How-To Guides - Task-oriented recipes
• Frontend Documentation - Nuxt 3 app guide
• Frontend How-To Guides - Form, typeahead, and verification recipes