Feature Specifications

Feature 1 — Resident Certificate/Form Request

Enables residents to digitally apply for barangay documents without visiting the barangay hall.

Input: Document type selection, stated purpose, supporting file uploads (e.g., utility bill for residency, valid ID).

Process:

1. System verifies the resident's barangay link
2. Checks for existing active duplicate of the same document type
3. Creates a document_transactions record with status: pending

Output: Tracking ID for the resident to monitor request status.

Edge Cases:

• Unverified user → prompted to complete eGovPH registration first
• Purpose = "Other" → mandatory free-text field appears

Feature 2 — Official-Led Resident Registration

Allows barangay officials to assist residents with limited tech access.

Target Users: Barangay Secretary, Enrollment Staff.

Registration methods supported:

• PhilID QR code scan (custom blood type decoding included)
• NFC card tap (UID → local resident lookup)
• Manual 2-column form (Name + Birthday)

"Double-Guard" Duplicate Detection:

• UI: Create button disabled on match
• Server-side: UUID and email uniqueness check

Edge Cases:

• Resident already exists → "Record Found" displayed; offers to update residency details

Feature 3 — Document Issuance (In-App & Walk-In)

Officials review and sign documents through the Filament panel.

Signing Authority — Triple Match Check

Before any document can be issued, the system validates:

1. Auth — Is the official authenticated?
2. Authority — Is the official's term currently active (ended_at IS NULL)?
3. Scope — Does the official's barangay_id match the requester's barangay_id?

Signing Hierarchy Check

Is the official the Barangay Captain?
  ✓ Yes → Proceed as Native
  ✗ No  → Is there an active Delegation for this document_type?
             ✓ Yes → Proceed as Acting
             ✗ No  → Deny Access

Document Rendering by Capacity:

• Native → "Hon. [Captain Name], Barangay Captain"
• Acting → "Hon. [Secretary Name], Barangay Secretary — By Authority of the Barangay Captain"

Document Validity Periods

Expiry formula: E = issued_at + validity_days

Edge Cases

• Expired official term → "Issue" button disabled; admin prompted to update Officials Directory
• Captain term ends with active delegation → system automatically voids all delegations tied to that term_id

Feature 4 — Leadership Terms History Tracking

Maintains an auditable record of all barangay official tenures.

Database: barangay_terms — one row per official, per position, per barangay. ended_at IS NULL = currently active.

Key constraint: A barangay cannot have two active "Barangay Captain" terms simultaneously. Inserting a new Captain must trigger ended_at on the predecessor.

Suspension support: An active term can be marked Revoked or Suspended to immediately cut system access without closing the term record.

Feature 5 — Household Clustering & Head Designation

Groups residents by physical structure and economic unit, manages dynamic leadership and presence status.

Data Model Layers

House (physical structure)
  └── Household (economic/social unit)
        └── HouseholdMemberProfile (user ↔ household with role/presence)

Key Constraints

Resident Dashboard (Livewire)

• View all active residences
• Switch presence status (one-click; syncs barangay_id automatically)
• Register new residence (multi-step form)
• Join existing residence (searchable by head name)
• Household Head: invite members via debounced search + ResidencyRequest

Official Approval Workflow

On approving a ResidencyRequest:

1. If household_id is present → link user to existing household
2. If household_id is null → auto-create new House + Household
3. If role = Head → update households.household_head_id
4. Sync user's barangay_id to new location

Edge Cases

Feature 6 — Family Lineage Tracking

Tracks nuclear family relationships and automates family lifecycle management.

Automated Family Lifecycle — UserObserver

Lineage Tree — D3.js

The interactive SVG family tree is integrated as an Alpine.js component in the resident profile. Complex family JSON is passed via hidden <script> tags to avoid HTML attribute quoting issues.

Interactive features: Mouse-wheel zoom, click-and-drag panning, smooth curved links between nodes.

Visual indicators: Highlighted current user node, gender-coded gradient fills, strikethrough styling for deceased ancestors.

Feature 7 — City Admin Panel

Read-only, municipality-scoped panel for oversight across all barangays in a municipality.

Panel URL: /city-admin Tenant slug: municity_code

Resources (all read-only):

• BarangaysResource — barangay list with active captain status badge
• OfficialsResource — all official terms, filterable by position/barangay/active status
• ResidentResource — resident list with lineage tree modal
• FamilyResource — family list with members modal
• HouseResource — house list with inhabitants modal
• HouseholdResource — household list with full infolist view

Performance: Eager loading on OfficialsResource (user + barangay + position relations). Barangay ID lookups cached for 30 minutes. Database notification polling disabled.