# mjgaspar-dotcom/barangay-request-system architecture

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

- Interactive diagram: https://gitdiagram.com/mjgaspar-dotcom/barangay-request-system
- Repository: https://github.com/mjgaspar-dotcom/barangay-request-system

## Overview

This is a barangay document-request system with registered-resident and guest submission, staff/admin processing, tracking, account administration, and operational records. The principal workflow runs from request submission through status processing and tracking; a useful internal layer is the status service, which owns transition rules and invokes audit and notification behavior. The README states the product purpose but provides little architecture detail. Several frontend pages and backend capabilities are visible only in the tree or route references, so those relationships are not asserted beyond documented routing and clearly marked unverified API communication.

Main entry points: [`app/Http/Controllers/Api/BarangayRequestController.php`](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/BarangayRequestController.php) (Request endpoints), [`routes/api.php`](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/routes/api.php) (API routing), [`app/Services/RequestStatusService.php`](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/RequestStatusService.php) (Status transitions), [`app/Http/Controllers/Api/GuestRequestController.php`](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/GuestRequestController.php) (Guest request endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_browser["Web application<br/>[main.jsx]"]
  node_auth["Authentication state<br/>[AuthProvider.jsx]"]
  node_clientapi["API client<br/>[api.js]"]
  node_residentpages["Resident and guest pages"]
  node_staffpages["Staff workspace"]
  node_adminpages["Admin workspace"]
end

subgraph group_api["API workflows"]
  node_routing["API routing<br/>[api.php]"]
  node_requestapi["Request endpoints"]
  node_guestapi["Guest request endpoints"]
  node_identityapi["Identity and access endpoints<br/>[AuthController.php]"]
  node_adminapi["Admin management endpoints"]
end

subgraph group_domain["Request domain"]
  node_requestrecords[("Request records")]
  node_identityrecords[("Identity and document records")]
  node_status["Status transitions"]
  node_tracking["Tracking lookup"]
end

subgraph group_operations["Administration and records"]
  node_audit["Audit logging<br/>[AuditService.php]"]
  node_notifications["Notifications"]
  node_ocr["OCR parsing"]
  node_reports["Request reports"]
  node_qrcode["QR generation<br/>[QrCodeService.php]"]
  node_documenttypes[("Document types<br/>[DocumentType.php]")]
end

node_resident(("Resident or guest"))
node_external["OCR or QR provider"]

node_browser -->|"provides context"| node_auth
node_browser -->|"loads routes"| node_routing
node_routing -->|"routes requests"| node_requestapi
node_routing -->|"routes guests"| node_guestapi
node_routing -->|"routes identity"| node_identityapi
node_routing -->|"routes administration"| node_adminapi
node_requestapi -->|"creates and queries"| node_requestrecords
node_requestapi -->|"delegates status"| node_status
node_requestapi -->|"logs actions"| node_audit
node_requestapi -->|"generates codes"| node_qrcode
node_requestapi -->|"loads document type"| node_documenttypes
node_requestapi -->|"looks up tracking"| node_tracking
node_guestapi -->|"delegates status"| node_status
node_guestapi -->|"logs actions"| node_audit
node_guestapi -->|"generates codes"| node_qrcode
node_status -->|"updates status"| node_requestrecords
node_status -->|"records transitions"| node_audit
node_status -->|"notifies changes"| node_notifications
node_audit -->|"persists audit entries"| node_identityrecords
node_requestapi -->|"checks requester role"| node_identityrecords
node_adminapi -->|"manages residents"| node_identityrecords
node_resident -.->|"uses portal"| node_browser
node_residentpages -.->|"requests API data"| node_clientapi
node_staffpages -.->|"requests API data"| node_clientapi
node_adminpages -.->|"requests API data"| node_clientapi
node_clientapi -.->|"calls backend"| node_routing
node_requestapi -.->|"may support reporting"| node_reports
node_routing -->|"exposes OCR test"| node_ocr
node_ocr -.->|"provider integration"| node_external

click node_browser "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/frontend/src/main.jsx"
click node_auth "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/frontend/src/contexts/AuthProvider.jsx"
click node_clientapi "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/frontend/src/services/api.js"
click node_residentpages "https://github.com/mjgaspar-dotcom/barangay-request-system/tree/main/frontend/src/pages"
click node_staffpages "https://github.com/mjgaspar-dotcom/barangay-request-system/tree/main/frontend/src/pages/staff"
click node_adminpages "https://github.com/mjgaspar-dotcom/barangay-request-system/tree/main/frontend/src/pages/admin"
click node_routing "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/routes/api.php"
click node_requestapi "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/BarangayRequestController.php"
click node_guestapi "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/GuestRequestController.php"
click node_identityapi "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/AuthController.php"
click node_adminapi "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/AdminUserController.php"
click node_requestrecords "https://github.com/mjgaspar-dotcom/barangay-request-system/tree/main/app/Models"
click node_identityrecords "https://github.com/mjgaspar-dotcom/barangay-request-system/tree/main/app/Models"
click node_status "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/RequestStatusService.php"
click node_tracking "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/BarangayRequestController.php"
click node_audit "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/AuditService.php"
click node_notifications "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/NotificationService.php"
click node_ocr "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/OcrParsingService.php"
click node_reports "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/RequestReportService.php"
click node_qrcode "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/QrCodeService.php"
click node_documenttypes "https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Models/DocumentType.php"

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_browser,node_auth,node_clientapi,node_residentpages,node_staffpages,node_adminpages toneBlue
class node_routing,node_requestapi,node_guestapi,node_identityapi,node_adminapi toneAmber
class node_requestrecords,node_identityrecords,node_status,node_tracking toneMint
class node_audit,node_notifications,node_ocr,node_reports,node_qrcode,node_documenttypes toneRose
class node_resident,node_external toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Authentication state](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/frontend/src/contexts/AuthProvider.jsx): `frontend/src/contexts/AuthProvider.jsx`
- [API client](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Resident and guest pages](https://github.com/mjgaspar-dotcom/barangay-request-system/tree/main/frontend/src/pages): `frontend/src/pages`
- [Staff workspace](https://github.com/mjgaspar-dotcom/barangay-request-system/tree/main/frontend/src/pages/staff): `frontend/src/pages/staff`
- [Admin workspace](https://github.com/mjgaspar-dotcom/barangay-request-system/tree/main/frontend/src/pages/admin): `frontend/src/pages/admin`

### API workflows

- [API routing](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/routes/api.php): `routes/api.php`
- [Request endpoints](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/BarangayRequestController.php): `app/Http/Controllers/Api/BarangayRequestController.php`
- [Guest request endpoints](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/GuestRequestController.php): `app/Http/Controllers/Api/GuestRequestController.php`
- [Identity and access endpoints](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/AuthController.php): `app/Http/Controllers/Api/AuthController.php`
- [Admin management endpoints](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/AdminUserController.php): `app/Http/Controllers/Api/AdminUserController.php`

### Request domain

- [Request records](https://github.com/mjgaspar-dotcom/barangay-request-system/tree/main/app/Models): `app/Models`
- [Identity and document records](https://github.com/mjgaspar-dotcom/barangay-request-system/tree/main/app/Models): `app/Models`
- [Status transitions](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/RequestStatusService.php): `app/Services/RequestStatusService.php`
- [Tracking lookup](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Http/Controllers/Api/BarangayRequestController.php): `app/Http/Controllers/Api/BarangayRequestController.php`

### Administration and records

- [Audit logging](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/AuditService.php): `app/Services/AuditService.php`
- [Notifications](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/NotificationService.php): `app/Services/NotificationService.php`
- [OCR parsing](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/OcrParsingService.php): `app/Services/OcrParsingService.php`
- [Request reports](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/RequestReportService.php): `app/Services/RequestReportService.php`
- [QR generation](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Services/QrCodeService.php): `app/Services/QrCodeService.php`
- [Document types](https://github.com/mjgaspar-dotcom/barangay-request-system/blob/main/app/Models/DocumentType.php): `app/Models/DocumentType.php`

### Other components

- **Resident or guest**
- **OCR or QR provider**

## Connections

- Web application → Authentication state: provides context (evidence: `frontend/src/main.jsx`)
- Web application → API routing: loads routes
- API routing → Request endpoints: routes requests (evidence: `routes/api.php`)
- API routing → Guest request endpoints: routes guests (evidence: `routes/api.php`)
- API routing → Identity and access endpoints: routes identity (evidence: `routes/api.php`)
- API routing → Admin management endpoints: routes administration (evidence: `routes/api.php`)
- Request endpoints → Request records: creates and queries (evidence: `app/Http/Controllers/Api/BarangayRequestController.php`)
- Request endpoints → Status transitions: delegates status (evidence: `app/Http/Controllers/Api/BarangayRequestController.php`)
- Request endpoints → Audit logging: logs actions (evidence: `app/Http/Controllers/Api/BarangayRequestController.php`)
- Request endpoints → QR generation: generates codes (evidence: `routes/api.php`)
- Request endpoints → Document types: loads document type (evidence: `app/Http/Controllers/Api/BarangayRequestController.php`)
- Request endpoints → Tracking lookup: looks up tracking (evidence: `app/Http/Controllers/Api/BarangayRequestController.php`)
- Guest request endpoints → Status transitions: delegates status (evidence: `app/Http/Controllers/Api/GuestRequestController.php`)
- Guest request endpoints → Audit logging: logs actions (evidence: `app/Http/Controllers/Api/GuestRequestController.php`)
- Guest request endpoints → QR generation: generates codes (evidence: `app/Http/Controllers/Api/GuestRequestController.php`)
- Status transitions → Request records: updates status (evidence: `app/Services/RequestStatusService.php`)
- Status transitions → Audit logging: records transitions (evidence: `app/Services/RequestStatusService.php`)
- Status transitions → Notifications: notifies changes (evidence: `app/Services/RequestStatusService.php`)
- Audit logging → Identity and document records: persists audit entries (evidence: `app/Services/AuditService.php`)
- Request endpoints → Identity and document records: checks requester role (evidence: `app/Http/Controllers/Api/BarangayRequestController.php`)
- Admin management endpoints → Identity and document records: manages residents (evidence: `app/Http/Controllers/Api/AdminUserController.php`)
- Resident or guest → Web application: uses portal (evidence: `README.md`)
- Resident and guest pages → API client: requests API data (evidence: `frontend/src/pages/admin/ManageRequests.jsx`)
- Staff workspace → API client: requests API data
- Admin workspace → API client: requests API data (evidence: `frontend/src/pages/admin/ManageRequests.jsx`)
- API client → API routing: calls backend
- Request endpoints → Request reports: may support reporting
- API routing → OCR parsing: exposes OCR test (evidence: `routes/api.php`)
- OCR parsing → OCR or QR provider: provider integration
