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
Patient Visits	Visit tracking, plans, follow-ups
Clinical Examinations	14+ ophthalmic exam types (tonometry, refraction, slit lamp, etc.)
Queue System	Service-based queue with tickets, transfers, priority types
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

Next Steps

• Backend Documentation - Detailed backend guide