# boufarra-oussama/admin_backend architecture

> Architecture diagram of the GitHub repository boufarra-oussama/admin_backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boufarra-oussama/admin_backend
- Repository: https://github.com/boufarra-oussama/admin_backend

## Overview

1. This repository is a Laravel-based backend API for a medical records and clinic operations system. It is not primarily a web UI app; the main surface area is `routes/api.php` plus supporting console jobs, mail, notifications, and PDF generation.

2. The core architectural pattern is layered: API controllers handle HTTP concerns, `FormRequest` classes validate input, `Service` classes contain business logic, `Repository` classes abstract persistence for some domains, and `Eloquent` models map to the database. `RepositoryServiceProvider` binds interfaces to implementations.

3. Authentication is token-based and appears to use JWT as the main API auth mechanism. The auth flow is centered on `AuthController`, `JwtMiddleware`, `JwtTokenService`, and the `jwt_tokens` table. The README also shows login/refresh/logout/me endpoints, so token lifecycle is a distinct subsystem.

4. Authorization is role/permission driven. Roles and permissions are first-class models with pivot tables, and `PermissionMiddleware` enforces access on protected routes. The README documents protected operations such as user management, role management, bill management, and analytics access via permissions like `roles:view` and `bills:manage`.

5. The system’s major business domains are users, patients, doctors, appointments, billing, medical records, reminders, analytics, and activity logs. These are each separated into dedicated controllers and services, which suggests the API is organized by domain rather than by technical layer only.

6. Medical record handling is its own subsystem. Models such as `MedicalHistory`, `VitalSign`, `LabResult`, `PatientFile`, `PatientNote`, `PatientAlert`, `TimelineEvent`, and file/notification services indicate a patient-centered record timeline with uploads, alerts, and lifecycle tracking. Observers and notification services support side effects when records or profile data change.

7. Appointment management is split across general, doctor-facing, and patient-facing flows. `AppointmentService`, `DoctorAppointmentController`, `PatientAppointmentController`, `AppointmentObserver`, and reminder jobs suggest appointments are a central workflow with scheduling rules, blocked slots, and downstream reminder generation.

8. Billing and finance is another major bounded context. `BillController`, `BillService`, `BillItem`/`Bill` models, bill resources, PDF views, and `dompdf` config indicate bills can be created, filtered, itemized, exported, and downloaded as PDFs. The README also shows patient read-only bill access and staff-only management, so billing has role-specific access paths.

9. Reminders are implemented as an async subsystem. `ScheduleAppointmentReminders`, `SendAppointmentReminder`, and `CancelScheduledReminders` jobs, plus reminder settings/logs/analytics tables, show a queue-backed reminder engine. Email templates under `resources/views/emails/reminders` and `AppointmentReminderMail` indicate reminders are delivered through mail, with custom notification channels also available for SMS and push.

10. Analytics is service-oriented and reads aggregated data from operational tables. `AnalyticsService`, `FinancialAnalyticsService`, `DateFilterService`, and analytics controllers provide reporting for users, revenue, services, and doctor revenue. The README’s export endpoint suggests some analytics can be downloaded, likely as CSV.

11. Activity logging is pervasive and cross-cutting. `ActivityLogger` middleware, `ActivityLog` model/repository/service, and the Spatie activitylog setup referenced in the README indicate audit trails are recorded across sensitive operations such as authentication, CRUD actions, and billing. This is a system-wide observability boundary, not just a feature module.

12. AI diagnostic support is present as a separate capability. `AiDiagnosticController`, `AiDiagnosticService`, and `AiAnalysis`/`AiModel` models indicate the app can run or store AI-based medical analysis results. This appears integrated into the medical domain rather than exposed as a standalone product.

13. The data layer is explicitly modeled in migrations and seeders. The schema includes users, roles, permissions, appointments, patients, doctors, bills, medical records, reminders, notifications, and logs, with many junction tables for RBAC and AI model assignment. Seeders provide initial roles, permissions, test patients/doctors, appointments, and reminder data.

14. Infrastructure concerns are built into the repo. There are Docker images for multiple PHP versions, database scripts for PostgreSQL/MySQL/MariaDB, queue worker startup scripts, and Laravel queue/cache/session configs. This means the app expects database, queue, mail, and file-storage services to be part of the runtime architecture.

15. The main request flow is: API request enters Laravel, passes through JWT and permission middleware, hits a domain controller, validates with a FormRequest, executes service logic, optionally uses a repository, writes to Eloquent models/database, then emits side effects such as audit logs, notifications, queued jobs, email, or PDFs. That pipeline is the most important diagram boundary for this repo.

Main entry points: [`routes/api.php`](https://github.com/boufarra-oussama/admin_backend/blob/main/routes/api.php) (API routes), [`app/Models`](https://github.com/boufarra-oussama/admin_backend/tree/main/app/Models) (Domain models), [`app/Http/Controllers/Api/AuthController.php`](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Http/Controllers/Api/AuthController.php) (Auth), [`app/Services/JwtTokenService.php`](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/JwtTokenService.php) (Token service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_api["API layer"]
  node_routes_api["API routes<br/>route entrypoint<br/>[api.php]"]
  node_auth_controller["Auth<br/>api controller<br/>[AuthController.php]"]
  node_domain_controllers["Clinic APIs<br/>api controllers"]
  node_request_validation["Form requests<br/>request validators"]
end

subgraph group_group_domain["Domain services"]
  node_auth_service["Auth service<br/>[AuthService.php]"]
  node_jwt_service[("Token service<br/>jwt service")]
  node_access_control_service["Access control<br/>rbac service<br/>[UserService.php]"]
  node_appointment_service["Appointments<br/>workflow service"]
  node_medical_service["Medical records<br/>clinical service"]
  node_billing_service["Billing<br/>finance service<br/>[BillService.php]"]
  node_reminder_service["Reminders<br/>async workflow service"]
  node_analytics_service["Analytics<br/>reporting service"]
  node_activity_service["Activity logs<br/>audit service"]
  node_ai_service["AI diagnostics<br/>analysis service"]
end

subgraph group_group_data["Data layer"]
  node_repository_provider{{"Repo bindings<br/>service provider"}}
  node_repositories["Repositories<br/>persistence layer"]
  node_eloquent_models[("Domain models<br/>eloquent models")]
  node_schema_seed["Schema data<br/>migrations and seeders"]
end

subgraph group_group_async["Async side effects"]
  node_jobs_mail_notify["Async side effects<br/>jobs mail notifications"]
  node_pdf_views["PDF templates<br/>rendering views"]
end

subgraph group_group_crosscutting["Cross-cutting"]
  node_auth_middleware{{"JWT middleware<br/>[JwtMiddleware.php]"}}
  node_permission_middleware{{"Permission guard<br/>middleware"}}
  node_activity_logger{{"Activity logger<br/>middleware<br/>[ActivityLogger.php]"}}
end

node_routes_api -->|"protects"| node_auth_middleware
node_routes_api -->|"authorizes"| node_permission_middleware
node_routes_api -->|"audits"| node_activity_logger
node_routes_api -->|"auth endpoints"| node_auth_controller
node_routes_api -->|"domain endpoints"| node_domain_controllers
node_auth_controller -->|"validates"| node_request_validation
node_domain_controllers -->|"validates"| node_request_validation
node_auth_controller -->|"uses"| node_auth_service
node_auth_service -->|"issues tokens"| node_jwt_service
node_jwt_service -->|"stores"| node_eloquent_models
node_domain_controllers -->|"uses"| node_access_control_service
node_domain_controllers -->|"uses"| node_appointment_service
node_domain_controllers -->|"uses"| node_medical_service
node_domain_controllers -->|"uses"| node_billing_service
node_domain_controllers -->|"uses"| node_reminder_service
node_domain_controllers -->|"uses"| node_analytics_service
node_domain_controllers -->|"uses"| node_activity_service
node_domain_controllers -->|"uses"| node_ai_service
node_permission_middleware -->|"enforces"| node_access_control_service
node_activity_logger -->|"writes"| node_activity_service
node_access_control_service -->|"resolves via"| node_repository_provider
node_repository_provider -->|"maps to"| node_repositories
node_repositories -->|"persists"| node_eloquent_models
node_appointment_service -->|"queues reminders"| node_jobs_mail_notify
node_medical_service -->|"notifies"| node_jobs_mail_notify
node_billing_service -->|"renders PDFs"| node_pdf_views
node_analytics_service -->|"reads aggregates"| node_schema_seed
node_activity_service -->|"writes audits"| node_eloquent_models
node_jobs_mail_notify -->|"updates status"| node_eloquent_models
node_schema_seed -->|"defines schema"| node_eloquent_models
node_auth_middleware -->|"verifies"| node_jwt_service

click node_routes_api "https://github.com/boufarra-oussama/admin_backend/blob/main/routes/api.php"
click node_auth_controller "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Http/Controllers/Api/AuthController.php"
click node_request_validation "https://github.com/boufarra-oussama/admin_backend/tree/main/app/Http/Requests"
click node_auth_middleware "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Http/Middleware/JwtMiddleware.php"
click node_permission_middleware "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Http/Middleware/PermissionMiddleware.php"
click node_activity_logger "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Http/Middleware/ActivityLogger.php"
click node_auth_service "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/AuthService.php"
click node_jwt_service "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/JwtTokenService.php"
click node_access_control_service "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/UserService.php"
click node_appointment_service "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/AppointmentService.php"
click node_medical_service "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/Medical/PatientMedicalDataService.php"
click node_billing_service "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/BillService.php"
click node_reminder_service "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/ReminderService.php"
click node_analytics_service "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/AnalyticsService.php"
click node_activity_service "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/ActivityLogService.php"
click node_ai_service "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/AiDiagnosticService.php"
click node_repository_provider "https://github.com/boufarra-oussama/admin_backend/blob/main/app/Providers/RepositoryServiceProvider.php"
click node_repositories "https://github.com/boufarra-oussama/admin_backend/tree/main/app/Repositories"
click node_eloquent_models "https://github.com/boufarra-oussama/admin_backend/tree/main/app/Models"
click node_schema_seed "https://github.com/boufarra-oussama/admin_backend/tree/main/database"
click node_jobs_mail_notify "https://github.com/boufarra-oussama/admin_backend/tree/main/app/Jobs"
click node_pdf_views "https://github.com/boufarra-oussama/admin_backend/tree/main/resources/views/pdfs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routes_api,node_auth_controller,node_domain_controllers,node_request_validation toneBlue
class node_auth_service,node_jwt_service,node_access_control_service,node_appointment_service,node_medical_service,node_billing_service,node_reminder_service,node_analytics_service,node_activity_service,node_ai_service toneAmber
class node_repository_provider,node_repositories,node_eloquent_models,node_schema_seed toneMint
class node_jobs_mail_notify,node_pdf_views toneRose
class node_auth_middleware,node_permission_middleware,node_activity_logger toneIndigo
```

## Components

### API layer

HTTP entrypoints, middleware, controllers, and request validation

- [API routes](https://github.com/boufarra-oussama/admin_backend/blob/main/routes/api.php): route entrypoint · Main HTTP surface for the backend API · `routes/api.php`
- [Auth](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Http/Controllers/Api/AuthController.php): api controller · Login, refresh, logout, and current-user endpoints · `app/Http/Controllers/Api/AuthController.php`
- **Clinic APIs**: api controllers · Controllers for users, patients, doctors, appointments, billing, records, analytics, and reminders
- [Form requests](https://github.com/boufarra-oussama/admin_backend/tree/main/app/Http/Requests): request validators · Input validation for auth, billing, patients, roles, reminders, analytics, and personal data · `app/Http/Requests`

### Domain services

Core clinic workflows and business logic

- [Auth service](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/AuthService.php): auth service · Coordinates credential checks and session state · `app/Services/AuthService.php`
- [Token service](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/JwtTokenService.php): jwt service · Creates, refreshes, and revokes API tokens · `app/Services/JwtTokenService.php`
- [Access control](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/UserService.php): rbac service · Users, roles, permissions, and profile management · `app/Services/UserService.php`
- [Appointments](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/AppointmentService.php): workflow service · Scheduling logic for clinic appointments and doctor/patient flows · `app/Services/AppointmentService.php`
- [Medical records](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/Medical/PatientMedicalDataService.php): clinical service · Patient file timeline, notes, alerts, vitals, lab results, and uploads · `app/Services/Medical/PatientMedicalDataService.php`
- [Billing](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/BillService.php): finance service · Bill creation, itemization, filtering, and export support · `app/Services/BillService.php`
- [Reminders](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/ReminderService.php): async workflow service · Reminder settings, scheduling, cancellation, and delivery coordination · `app/Services/ReminderService.php`
- [Analytics](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/AnalyticsService.php): reporting service · Aggregated reporting for users, revenue, doctors, and services · `app/Services/AnalyticsService.php`
- [Activity logs](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/ActivityLogService.php): audit service · Audit trail capture and retrieval across sensitive operations · `app/Services/ActivityLogService.php`
- [AI diagnostics](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Services/AiDiagnosticService.php): analysis service · Medical AI analysis execution and persistence · `app/Services/AiDiagnosticService.php`

### Data layer

Models, repositories, schema, and persistence bindings

- [Repo bindings](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Providers/RepositoryServiceProvider.php): service provider · Binds repository interfaces to Eloquent implementations · `app/Providers/RepositoryServiceProvider.php`
- [Repositories](https://github.com/boufarra-oussama/admin_backend/tree/main/app/Repositories): persistence layer · Eloquent repository implementations for selected domains · `app/Repositories`
- [Domain models](https://github.com/boufarra-oussama/admin_backend/tree/main/app/Models): eloquent models · Core entities for users, patients, doctors, appointments, bills, records, roles, permissions, tokens, reminders, and logs · `app/Models`
- [Schema data](https://github.com/boufarra-oussama/admin_backend/tree/main/database): migrations and seeders · Database schema, pivots, indexes, and bootstrap data · `database`

### Async side effects

Jobs, mail, notifications, and document rendering

- [Async side effects](https://github.com/boufarra-oussama/admin_backend/tree/main/app/Jobs): jobs mail notifications · Queued reminders, mail delivery, and patient-file notifications · `app/Jobs`
- [PDF templates](https://github.com/boufarra-oussama/admin_backend/tree/main/resources/views/pdfs): rendering views · Bill and receipt templates used for downloadable PDFs · `resources/views/pdfs`

### Cross-cutting

Authentication, authorization, and audit concerns

- [JWT middleware](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Http/Middleware/JwtMiddleware.php): middleware · Token authentication guard for protected API routes · `app/Http/Middleware/JwtMiddleware.php`
- [Permission guard](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Http/Middleware/PermissionMiddleware.php): middleware · Role and permission enforcement on protected operations · `app/Http/Middleware/PermissionMiddleware.php`
- [Activity logger](https://github.com/boufarra-oussama/admin_backend/blob/main/app/Http/Middleware/ActivityLogger.php): middleware · Cross-cutting audit capture for sensitive actions · `app/Http/Middleware/ActivityLogger.php`

## Connections

- API routes → JWT middleware: protects · Protected API routes pass through token authentication
- API routes → Permission guard: authorizes · Sensitive endpoints are gated by permissions
- API routes → Activity logger: audits · Selected operations are captured for audit trails
- API routes → Auth: auth endpoints · Login and token lifecycle endpoints
- API routes → Clinic APIs: domain endpoints · Primary controllers for clinic operations
- Auth → Form requests: validates · Auth requests are validated before processing
- Clinic APIs → Form requests: validates · Controllers use FormRequest classes for input checks
- Auth → Auth service: uses · Delegates credential and session handling
- Auth service → Token service: issues tokens · Auth service relies on token lifecycle logic
- Token service → Domain models: stores · JWT token state is persisted in the data layer
- Clinic APIs → Access control: uses · User, role, permission, and profile flows
- Clinic APIs → Appointments: uses · Appointment creation, updates, and scheduling
- Clinic APIs → Medical records: uses · Medical history, files, notes, alerts, and lab data
- Clinic APIs → Billing: uses · Billing CRUD and export operations
- Clinic APIs → Reminders: uses · Reminder setup and bulk operations
- Clinic APIs → Analytics: uses · Reporting and export endpoints
- Clinic APIs → Activity logs: uses · Audit log access and admin views
- Clinic APIs → AI diagnostics: uses · AI-assisted diagnostic endpoints
- Permission guard → Access control: enforces · Protected operations depend on roles and permissions
- Activity logger → Activity logs: writes · Audit middleware feeds the activity log subsystem
- Access control → Repo bindings: resolves via · Repository interfaces are injected through the provider
- Repo bindings → Repositories: maps to · Interface implementations are wired here
- Repositories → Domain models: persists · Repository layer wraps Eloquent persistence
- Appointments → Async side effects: queues reminders · Appointments trigger scheduled reminders and notifications
- Medical records → Async side effects: notifies · Patient file and record changes emit notifications
- Billing → PDF templates: renders PDFs · Bills and receipts can be exported as PDF documents
- Analytics → Schema data: reads aggregates · Reporting is driven by operational tables and seeded data
- Activity logs → Domain models: writes audits · Activity logging is stored centrally
- Async side effects → Domain models: updates status · Reminder jobs and notifications record lifecycle state
- Schema data → Domain models: defines schema · Tables and seed data shape the model layer
- JWT middleware → Token service: verifies · Incoming requests are checked against token lifecycle state
