# kev-003/bataeno-pass-barangay architecture

> Architecture diagram of the GitHub repository kev-003/bataeno-pass-barangay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kev-003/bataeno-pass-barangay
- Repository: https://github.com/kev-003/bataeno-pass-barangay

## Overview

Bataeño Pass is a barangay identity and services platform: residents request certificates and manage household information; barangay officials review requests, enforce signing authority, and issue documents; municipal administrators oversee barangay records. The graph includes the documented governance, notification, lineage, NFC/QR, and queued-PDF capabilities. Source excerpts directly establish only selected controller and client notification behavior; other subsystem relationships are shown only where the README documents them.

Main entry points: [`app/Http/Controllers/DocumentController.php`](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Http/Controllers/DocumentController.php) (Document requests), [`app/Livewire`](https://github.com/kev-003/bataeno-pass-barangay/tree/main/app/Livewire) (Resident portal), [`app/Jobs/ProcessDocumentApproval.php`](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Jobs/ProcessDocumentApproval.php) (PDF generation job), [`app/Models/DocumentTransaction.php`](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Models/DocumentTransaction.php) (Document records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_resident["Resident services"]
  node_resident_portal["Resident portal"]
  node_lineage["Family lineage<br/>[LineageD3.js]"]
end

subgraph group_official["Official operations"]
  node_nfc_qr["NFC and QR lookup"]
  node_official_panel["Official panel"]
  node_city_panel["Municipal oversight"]
end

subgraph group_governance["Governance and registry"]
  node_term_authority["Terms and delegation<br/>[Delegation.php]"]
  node_registry["Household registry<br/>[Household.php]"]
end

subgraph group_documents["Document services"]
  node_document_request["Document requests"]
  node_approval["Approval service"]
  node_governance_check["Signing authority"]
  node_pdf_job["PDF generation job"]
  node_document_generation["Document generation"]
  node_document_models[("Document records")]
end

subgraph group_platform["Platform infrastructure"]
  node_notifications["Request notifications"]
  node_client_realtime["Live notifications<br/>[app.js]"]
  node_identity["Bataeño identity<br/>[BataenoService.php]"]
end

node_resident(("Resident"))
node_official(("Barangay official"))
node_admin(("City admin"))
node_bataeno{{"Bataeño Pass"}}
node_database[("Application database")]
node_queue["Laravel queue"]
node_reverb{{"Reverb WebSockets"}}

node_resident -->|"uses"| node_resident_portal
node_resident_portal -->|"submits requests"| node_document_request
node_resident_portal -->|"views lineage"| node_lineage
node_official -->|"handles requests"| node_official_panel
node_official -->|"looks up residents"| node_nfc_qr
node_admin -->|"oversees records"| node_city_panel
node_official_panel -->|"processes requests"| node_document_request
node_document_request -->|"creates or updates"| node_document_models
node_document_request -->|"checks authority"| node_governance_check
node_document_request -->|"requests approval"| node_approval
node_approval -->|"dispatches after commit"| node_pdf_job
node_pdf_job -->|"generates document"| node_document_generation
node_document_generation -->|"records issuance"| node_document_models
node_document_models -->|"persists records"| node_database
node_term_authority -->|"stores terms"| node_database
node_registry -->|"stores household data"| node_database
node_document_request -.->|"notifies requesters"| node_notifications
node_notifications -.->|"broadcasts"| node_reverb
node_reverb -->|"delivers events"| node_client_realtime
node_identity -->|"authenticates and fetches profiles"| node_bataeno
node_nfc_qr -.->|"looks up identity"| node_identity
node_pdf_job -->|"runs asynchronously"| node_queue

click node_resident_portal "https://github.com/kev-003/bataeno-pass-barangay/tree/main/app/Livewire"
click node_lineage "https://github.com/kev-003/bataeno-pass-barangay/blob/main/resources/js/components/LineageD3.js"
click node_nfc_qr "https://github.com/kev-003/bataeno-pass-barangay/tree/main/app/Livewire/Officials"
click node_official_panel "https://github.com/kev-003/bataeno-pass-barangay/tree/main/app/Filament/Official"
click node_city_panel "https://github.com/kev-003/bataeno-pass-barangay/tree/main/app/Filament/CityAdmin"
click node_term_authority "https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Models/Delegation.php"
click node_registry "https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Models/Household.php"
click node_document_request "https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Http/Controllers/DocumentController.php"
click node_approval "https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Services/DocumentApprovalService.php"
click node_governance_check "https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Services/GovernanceService.php"
click node_pdf_job "https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Jobs/ProcessDocumentApproval.php"
click node_document_generation "https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Listeners/GenerateDocument.php"
click node_document_models "https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Models/DocumentTransaction.php"
click node_notifications "https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Notifications/DocumentRequestReceived.php"
click node_client_realtime "https://github.com/kev-003/bataeno-pass-barangay/blob/main/resources/js/app.js"
click node_identity "https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Services/BataenoService.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_resident_portal,node_lineage toneBlue
class node_nfc_qr,node_official_panel,node_city_panel,node_database toneAmber
class node_term_authority,node_registry toneMint
class node_document_request,node_approval,node_governance_check,node_pdf_job,node_document_generation,node_document_models,node_queue toneRose
class node_notifications,node_client_realtime,node_identity,node_resident,node_official,node_admin,node_bataeno,node_reverb toneIndigo
```

## Components

### Resident services

- [Resident portal](https://github.com/kev-003/bataeno-pass-barangay/tree/main/app/Livewire): `app/Livewire`
- [Family lineage](https://github.com/kev-003/bataeno-pass-barangay/blob/main/resources/js/components/LineageD3.js): `resources/js/components/LineageD3.js`

### Official operations

- [NFC and QR lookup](https://github.com/kev-003/bataeno-pass-barangay/tree/main/app/Livewire/Officials): `app/Livewire/Officials`
- [Official panel](https://github.com/kev-003/bataeno-pass-barangay/tree/main/app/Filament/Official): `app/Filament/Official`
- [Municipal oversight](https://github.com/kev-003/bataeno-pass-barangay/tree/main/app/Filament/CityAdmin): `app/Filament/CityAdmin`

### Governance and registry

- [Terms and delegation](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Models/Delegation.php): `app/Models/Delegation.php`
- [Household registry](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Models/Household.php): `app/Models/Household.php`

### Document services

- [Document requests](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Http/Controllers/DocumentController.php): `app/Http/Controllers/DocumentController.php`
- [Approval service](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Services/DocumentApprovalService.php): `app/Services/DocumentApprovalService.php`
- [Signing authority](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Services/GovernanceService.php): `app/Services/GovernanceService.php`
- [PDF generation job](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Jobs/ProcessDocumentApproval.php): `app/Jobs/ProcessDocumentApproval.php`
- [Document generation](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Listeners/GenerateDocument.php): `app/Listeners/GenerateDocument.php`
- [Document records](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Models/DocumentTransaction.php): `app/Models/DocumentTransaction.php`

### Platform infrastructure

- [Request notifications](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Notifications/DocumentRequestReceived.php): `app/Notifications/DocumentRequestReceived.php`
- [Live notifications](https://github.com/kev-003/bataeno-pass-barangay/blob/main/resources/js/app.js): `resources/js/app.js`
- [Bataeño identity](https://github.com/kev-003/bataeno-pass-barangay/blob/main/app/Services/BataenoService.php): `app/Services/BataenoService.php`

### Other components

- **Resident**
- **Barangay official**
- **City admin**
- **Bataeño Pass**
- **Application database**
- **Laravel queue**
- **Reverb WebSockets**

## Connections

- Resident → Resident portal: uses
- Resident portal → Document requests: submits requests
- Resident portal → Family lineage: views lineage
- Barangay official → Official panel: handles requests
- Barangay official → NFC and QR lookup: looks up residents
- City admin → Municipal oversight: oversees records
- Official panel → Document requests: processes requests
- Document requests → Document records: creates or updates
- Document requests → Signing authority: checks authority
- Document requests → Approval service: requests approval
- Approval service → PDF generation job: dispatches after commit
- PDF generation job → Document generation: generates document
- Document generation → Document records: records issuance
- Document records → Application database: persists records
- Terms and delegation → Application database: stores terms
- Household registry → Application database: stores household data
- Document requests → Request notifications: notifies requesters
- Request notifications → Reverb WebSockets: broadcasts
- Reverb WebSockets → Live notifications: delivers events
- Bataeño identity → Bataeño Pass: authenticates and fetches profiles
- NFC and QR lookup → Bataeño identity: looks up identity
- PDF generation job → Laravel queue: runs asynchronously