Introduction

Implementation status (2026-07-10): All 8 phases built in modules/Barangay/ (v1.0.0) — 21 controllers, 40+ models, 8 idempotent migrations (36 tables), 4 cron jobs, 4 seeders, 96 green module tests. Post-build adversarial review (5 dimensions, per-finding verification) confirmed 15 defects — all fixed, including 2 critical cross-tenant PDF-path issues (now tenant-scoped via barangay_files_dir()). Pending: live multi-tenant QA on a provisioned second tenant; CardMaker PNG templates for raster IDs (HTML card path shipped); deferred scope per Assumptions (AI copilot, offline officer app, PhilSys relying-party API).

This plan adapts the greenfield "Barangay Good Governance Information System" proposal (barangay_module_claude_implementation_plan.md + barangay_governance_module_prototype.html) to the ERPat platform. The original plan's monorepo stack (Next.js/NestJS/PostgreSQL/Redis) is replaced wholesale by ERPat's architecture: each barangay becomes an ERPat tenant (database-per-tenant via the Tenancy module), every generic capability (ticketing, announcements, events, messaging, users/RBAC, notifications, assets, finance GL, forms, CMS, appointments, kiosk, audit logs) is reused from existing modules/core, and only the barangay-specific governance domain (resident registry, document issuance + QR verification, Katarungang Pambarangay, VAW Desk/BPO, blotter, DRRM, FDP compliance, barangay IDs) is built new inside one self-contained module: modules/Barangay/ (slug barangay). The plan is grounded in verified Philippine legal requirements (RA 7160, RA 9262, RA 11261, RA 11032, RA 10121, RA 10173, DILG MC 2014-81, RA 10742, RA 9710, COA barangay manual) — see §8 research notes.

Reuse Map — Original Plan Modules → ERPat

This table is the governing decision record for "reuse vs. build". Generic = reuse/configure; barangay-domain = build inside modules/Barangay/.

1. Requirements & Constraints

Functional Requirements

Registry (RBI)

• REQ-001: Maintain an individual + household resident registry (RBI) owned by the Barangay Secretary role: identity fields, address/purok, residency start date, civil status, citizenship, occupation, optional PhilSys PCN, sector tags (senior/PWD/solo parent/youth/pregnant/informal settler/evacuation priority), verification status, with a Data Privacy Notice + consent capture on every intake form.
• REQ-002: Households: head, members with relationships, dwelling type, purok/sitio, risk tags; purok master list with risk level.
• REQ-003: Residency engine: compute years/months of stay; assembly eligibility (≥15 y.o., ≥6-month resident); duplicate detection on name+birthdate+household.
• REQ-004: Excel import/export of residents following the Assets/Forms importer pattern; export aligned to DILG LGUSS-BIMS/RBI field structure.

Documents & Certificates

• REQ-010: Configurable document types (Barangay Clearance, Business Clearance, Certificate of Residency, Indigency, First-Time Jobseeker, Good Moral, custom) with per-type: fee rule (ordinance-configurable, never hardcoded), requirements checklist, ARTA SLA class (simple=3 / complex=7 / highly-technical=20 working days), template key, validity days.
• REQ-011: Request workflow: intake (staff or citizen portal) → requirements check → eligibility checks (residency/age/KP-blotter flags) → fee/OR → review → PDF render (mPDF) → signatory approval → release; SLA countdown with breach/deemed-approved flagging (RA 11032).
• REQ-012: Issued documents get a serial number, SHA-256 document hash, and a public QR verification endpoint exposing only validity + minimal metadata (doc type, serial, issue date, status) — never resident personal data.
• REQ-013: First-Time Jobseeker (RA 11261): certificate is FREE (fee forcibly ₱0), one-time per resident (registry-enforced block), 1-year validity, Oath of Undertaking captured, availee roster report.
• REQ-014: Business clearance (LGC Sec 152c): 7-working-day action window with deemed/escalation state; fee from ordinance config.
• REQ-015: Citizen's Charter page auto-generated per service: requirements, responsible officer, processing time, fees, steps, complaint procedure (RA 11032 six data points).

Fees / Treasury

• REQ-020: Official Receipts: serial-controlled OR series (POS receipt-series pattern), collected-by, void workflow, exemption handling; RAAF report (Report of Accountability for Accountable Forms, one series/year).
• REQ-021: Collections post to modules/Finance/ (payments/journals) — no parallel GL.

Katarungang Pambarangay

• REQ-030: KP case lifecycle with an automatic deadline engine: summons issued next working day after complaint → PB mediation 15 days from first meeting → Pangkat constitution (convenes ≤3 days) → conciliation 15 days (+ one 15-day extension the Pangkat must explicitly grant — never automatic) → settlement → repudiation window 10 days (sworn statement, fraud/violence/intimidation grounds only) → final (force of court judgment) → Lupon execution window 6 months (court action thereafter); arbitration path (written agreement; award only after the 10-day repudiation lapse); prescription-suspension tracking capped at 60 days.
• REQ-031: Jurisdiction-exclusion checklist at intake — blocks KP filing and auto-routes to blotter/PNP/VAW Desk instead: government party; public officer re official functions; penalty >1 yr or fine >₱5,000; no private offended party; juridical-entity party (natural persons only); cross-city/municipality residence (unless adjoining barangays + agreement); real property in different LGUs; labor and agrarian disputes; urgent court remedies; VAWC — HARD BLOCK, RA 9262 Sec 33 prohibits KP conciliation of VAWC (route to VAW Desk/BPO). Non-appearance rules: complainant absent → dismiss without prejudice + Certification to Bar Action; respondent absent → ex parte + CFA.
• REQ-032: Generate numbered KP Forms via the config-mapped template registry (standard DILG set: Form 7 Complaint, 8 Notice of Hearing–Mediation, 9 Summons, 10/11 Pangkat constitution notices, 12 Notice of Hearing–Conciliation, 13 Subpoena, 14 Arbitration Agreement, 15 Arbitration Award, 16 Amicable Settlement, 17 Repudiation, 20 Certification to File Action, 21 Certification to Bar Action, 22 Bar Counterclaim, 23–25 execution set). ⚠ Form numbering/titles vary across DILG regional printings — templates MUST be config-remappable per tenant, never hardcoded. CFA issuance blocked until the lawful stage (issued by Secretary, attested by Lupon/Pangkat Chairman).
• REQ-033: Lupon directory (PB chair + 10–20 members, 3-year term, Barangay Secretary as ex-officio Lupon Secretary), KP docket (consecutively numbered), monthly KP report (court/DILG), searchable computerized case database + LTIA evidence export (DILG MC 2023-022/2023-110: ≥10 settled cases, systematic records). KP records confidential — never in public/citizen surfaces; settlement-negotiation statements flagged privileged/inadmissible.

VAW Desk / BPO (restricted)

• REQ-040: Separate, permission-walled VAW case module: victim/respondent identifiers encrypted at rest, case list visible only to barangay_vaw grantees; excluded from global search, dashboards, blotter, and all citizen surfaces (RA 9262 Sec 44).
• REQ-041: BPO issuance: ex parte, same-day, issuer = Punong Barangay (or Kagawad with attestation; PB attests within 24h), validity exactly 15 days (auto-expiry), reliefs limited to Sec 5(a)/5(b) prohibited acts (no custody/support templates), service log with proof, violation → PNP referral record.
• REQ-042: Quarterly VAW Desk statistical report (counts only, no identities).

Blotter / Peace & Order

• REQ-050: Serialized blotter/incident register (datetime, reporting person, respondent, narrative, witnesses, action taken, recording officer) separate from KP intake — a blotter entry NEVER auto-creates a KP case; endorsement to Lupon is an explicit action that re-runs the exclusion checklist. Referral links (blotter → KP case, blotter → PNP, blotter → VAW Desk); certified-true-copy issuance with access control + audit; confidential (never public). Tanod/BPSO roster (appointed by PB on BPOC recommendation, DILG MC 2003-042) + patrol log; BPOC record per EO 309/366 + DILG MC 2020-047 (composition, monthly meetings, BPOPSP plan, annual functionality report).

DRRM

• REQ-060: BDRRMC roster (PB chair + ≥2 CSO reps), BDRRM plan record, evacuation centers with capacity, household evacuation-priority list (driven by registry risk tags), relief distributions with recipient logging (QR-scannable), early-warning advisory drafts published via Announcements/CMS.
• REQ-061: LDRRMF tracker: ≥5% of estimated regular-source revenue, internal 70/30 split (prevention-mitigation-preparedness / QRF), unexpended balance → special trust fund with 5-year aging.

Finance compliance / FDP

• REQ-070: Budget record per fiscal year with a mandatory-allocation validator using each allocation's own base: SK 10% of general fund (RA 10742), GAD ≥5% of total budget (RA 9710), LDRRMF ≥5% of regular-source revenue (RA 10121), Senior 1% of IRA/NTA + PWD 1% of IRA/NTA (separate), BCPC 1%, 20% Development Fund of NTA, 55% PS cap; budget cannot be marked "Enacted" while under-funded; Sec 333 review workflow (submit within 10 days; 60-day review; deemed-in-force).
• REQ-071: FDP posting tracker for the 8-item BFDP document set (DILG MC 2014-81) with per-item frequency (monthly collections/disbursements; quarterly BFR + notices of award; annual budget, SIE, 20% DF utilization, APP; SK financials), dual-channel logging (FDP-Portal upload date + physical BFDP-Board posting date), and BFDP Monitoring Form No. 1 generation; public transparency page via Content CMS.

Governance records / Assembly

• REQ-080: Legislative registry: ordinances/resolutions/EOs/minutes with number, adoption date, quorum/majority-of-all-members vote record, signatories, posting proof (dates/locations), file attachment (general_files), visibility (public/internal), and the ordinance review workflow (transmit to C/M sanggunian within 10 days; 30-day review clock → deemed approved on lapse); penalty-ceiling validation for penal ordinances (barangay fines ≤ ₱1,000); public records browse page via CMS. Record classes carry NAP GRDS-based retention metadata (temporary vs permanent; disposal only via recorded Certificate-of-Authority workflow — never silent purge).
• REQ-081: Barangay Assembly: member eligibility list (from registry engine), twice-yearly meetings (any Sat/Sun of March and October per Proclamation 599 + DILG omnibus guidelines), 1-week prior written notice generation, attendance capture against the registered member list, semestral activities-and-finances report publication.

Reuse wiring

• REQ-090: Complaints/issues run on Helpdesk: seed barangay ticket types (streetlight, waste, drainage, noise, road, etc.) + groups (Kagawad-Infra, Tanod, Maintenance); citizen intake via Contact_support and Customer_portal; ticket SLA via Helpdesk auto-close/escalation jobs.
• REQ-091: Announcements to staff/officials via core Announcements; public citizen advisories/news via Content CMS blog + public_pages.php; events via Events module.
• REQ-092: Barangay properties/equipment in Assets module; facility booking via Appointments resources (covered court, hall, session room).
• REQ-093: Notification events registered in the notifications engine (email + web + push): document ready-for-pickup, KP hearing schedule, BPO expiry warning, SLA breach, FDP posting due.
• REQ-094: Dashboard widgets: pending document queue, SLA at-risk count, open tickets (Helpdesk data), KP deadlines this week, FDP compliance status, resident count.

Security Requirements

• SEC-001: All endpoints with side effects gated by with_permission(); module gate with_module('barangay') in every controller constructor.
• SEC-002: All SQL parameterized via Query Builder bindings or $this->db->escape(); SQL only in models.
• SEC-003: All view output escaped via html_escape(); resident PII never rendered unescaped.
• SEC-004: CSRF middleware active for all POST routes; public endpoints (QR verify, citizen intake) rate-limited.
• SEC-005: Multi-tenancy isolation preserved — all barangay tables live in the tenant DB; no cross-tenant reads.
• SEC-006: VAW tier: victim/respondent name/address/contact columns encrypted (AES-256-GCM via a module crypto helper following api_crypto_helper.php patterns; key from .env); access to any VAW record writes a system_logs view-audit entry; VAW data excluded from exports, global search, and DataTable joins elsewhere.
• SEC-007: Public QR verification endpoint returns validity metadata only — never names, addresses, or purposes; token stored hashed.
• SEC-008: Data Privacy (RA 10173): consent snapshot rows on resident intake and citizen submissions (Lending *_consents precedent); DPO contact setting; retention settings per record class; every resident-record view/export audit-logged.
• SEC-009: Blotter and KP surfaces are staff-only (never exposed on citizen portal or public pages); third-party disclosure requires a recorded lawful-basis entry.

Performance Requirements

• PERF-001: All list_data endpoints use model-level JOINs (Pattern 16) — resident lists join households/puroks in one query.
• PERF-002: Registry imports processed in batches (seeder/importer batch pattern); duplicate detection via indexed lookups, not full scans.
• PERF-003: KP/document deadline sweeps run as cron jobs (Pattern 21 — notifications deferred outside loops).
• PERF-004: Dashboard widgets query pre-aggregated counts with date-bounded queries (Pattern 19).

Constraints

• CON-001: PHP 8.2+, CodeIgniter 3 — module controllers unnamespaced, loaded via App_Router.
• CON-002: Self-contained module: ALL routes in modules/Barangay/config/routes.php, permissions in config/permissions.php, menu in config/menu.php + required config/default_menu.php — never in core (G15/G16, module-files.md).
• CON-003: All SQL in models extending Crud_model; Crud_model::save() takes $data by reference (named variable, never literal array).
• CON-004: Soft deletes — every WHERE includes deleted = 0.
• CON-005: Migrations in modules/Barangay/migrations/ with real local timestamps (Get-Date -Format "yyyyMMddHHmmss" immediately before file creation), idempotent (table_exists/SHOW COLUMNS/SHOW INDEX guards), reversible down(), tracked in migrations_barangay.
• CON-006: New tables end with created_by, created_at, updated_at, deleted in that order.
• CON-007: UTC storage / local display via date_time_helper (get_current_utc_time(), format_to_*). KP/ARTA deadline math in working days needs a helper honoring holidays (get_paid_holidays/holiday table).
• CON-008: All user-facing strings via lang('key') in modules/Barangay/language/english/barangay_lang.php.
• CON-009: Dark/light theme tokens only (--surface-*, --text-*, --border-*); full pages wrap <div id="page-content" class="p20 clearfix">; modal forms general-form form-horizontal; Select2 needs class + init.
• CON-010: The prototype HTML (barangay_governance_module_prototype.html) defines the information architecture (menus/screens) but NOT the visual system — views follow ERPat brand tokens and component patterns, not the prototype's palette.
• CON-011: AI is assistive only and deferred from v1; no AI approval of official actions (original plan Principle 2 preserved).

Conventions / Patterns to Follow

• PAT-016: N+1 elimination — JOIN puroks/households/users in get_details().
• PAT-017: Race-condition prevention — UNIQUE indexes on (serial_no, deleted) for issued documents and ORs; FTJS one-time enforced by UNIQUE (resident_id, deleted) on the registry + check-then-insert.
• PAT-019: Date-range filtering for KP calendars, blotter lists, relief distributions.
• PAT-020: Pre-fetch maps for import validation and deadline sweeps.
• PAT-021: Defer notifications outside loops in cron jobs.
• PAT-029: is_array() guards before foreach on helper returns.

Guidelines

• GUD-001: Follow modules/Todo/ (canon) + .claude/rules/module-files.md for every module file; scaffold with php erpat make:module Barangay then extend.
• GUD-002: Reference precedents: Lending (compliance/consent patterns), Helpdesk (ticket wiring), Pos (receipt series), Recruitment Job_portal (public guest flows + RA 10173 consent), Kiosk (sessionless tenant + QR scan).
• GUD-003: Public pages follow seo-dynamic-page.md (head partial, JSON-LD, contained-hero spacing) and register via config/public_pages.php + modules/Content/config/cms.php route_keys.
• GUD-004: Every mutation calls set_system_logs() with an event registered in modules/Barangay/config/system_logs.php.

2. Implementation Steps

Phase 1: Module scaffold, barangay profile, resident & household registry (RBI)

• GOAL-001: modules/Barangay/ exists, enables in Manage Modules, and staff can CRUD puroks, officials, residents, households with consent capture, sector tags, residency/assembly-eligibility computation, and Excel import/export.

Phase 2: Document & certificate issuance engine (queue → fee/OR → PDF → sign → release → QR verify)

• GOAL-002: A configurable document engine issues at least 6 document types end-to-end with ARTA SLA tracking, ordinance-configurable fees, serial-controlled ORs, mPDF certificates with QR, and a public verification endpoint.

Phase 3: Reuse wiring — complaints (Helpdesk), announcements/events/CMS, citizen portal, notifications, dashboard

• GOAL-003: Citizens can submit and track complaints, see announcements/news/events, and request documents online — all through existing ERPat surfaces configured for the barangay; staff get barangay dashboard widgets.

Phase 4: Katarungang Pambarangay + Blotter / Peace & Order

• GOAL-004: Full KP case lifecycle with the statutory deadline engine and numbered KP forms; a blotter register distinct from KP with referral links; Lupon and Tanod directories.

Phase 5: VAW Desk / BPO (restricted, encrypted)

• GOAL-005: A permission-walled, encrypted VAW case workspace issuing compliant 15-day BPOs with service logs, referrals, and identity-free quarterly reports.

Phase 6: DRRM + Health & Social Services

• GOAL-006: BDRRMC operations (evac centers, priority lists, relief with QR logging, LDRRMF tracking) and assistance-request workflow are live.

Phase 7: Finance compliance, FDP, governance records, assembly, reports & SGLGB

• GOAL-007: Budget-allocation validation, FDP posting tracker + public transparency page, legislative registry with review workflow, assembly records, and the barangay report/export set.

Phase 8: ID renderer, kiosk, hardening & release

• GOAL-008: Barangay/resident/officer IDs render via CardMaker; barangay-hall kiosk flow works; security, privacy, tenancy, and QA gates pass.

3. Alternatives

• ALT-001: Greenfield monorepo (original plan §2: Next.js + NestJS + PostgreSQL + Redis) — rejected. It duplicates ~70% of what ERPat already ships (tenancy, RBAC, ticketing, notifications, CMS, finance, assets, PDF/QR, audit logs), doubles infrastructure and maintenance, and abandons the existing operations tooling. The ERPat module path delivers the barangay domain on proven rails.
• ALT-002: Multiple small modules (BarangayCore, BarangayKP, BarangayVAW, …) — rejected for v1. One modules/Barangay/ keeps the shared resident registry, document engine, and treasury in one package (no cross-module model coupling); the permission system already provides internal walls (VAW). A split can happen later via the modularization runbook if sub-domains need independent versioning.
• ALT-003: Residents as users rows (user_type=customer) — rejected as the primary registry. RBI must hold non-account holders (children, seniors) and demographic history; a dedicated residents table with an OPTIONAL user_id link for portal accounts is correct.
• ALT-004: Building a new complaint/ticket engine inside the module (as the prototype's Kanban board implies) — rejected per user directive: Helpdesk is the ticket engine; the module only seeds types/groups and reads counts for widgets.
• ALT-005: Barangay profile as its own table — rejected; tenant-level singletons belong in settings (get_setting()), consistent with company profile handling.

4. Dependencies

• DEP-001: modules/Tenancy/ + core provisioner — barangay tenant provisioning (existing).
• DEP-002: modules/Helpdesk/ enabled — complaints (REQ-090); widgets degrade gracefully if disabled.
• DEP-003: modules/Content/ enabled for public CMS chrome/pages; public pages must fail-safe render without it (seo-dynamic-page.md §10).
• DEP-004: modules/Finance/ optional — journal posting hook (TASK-054) skips if disabled.
• DEP-005: modules/Appointments/, modules/Assets/, modules/Events/, modules/Forms/ optional reuse surfaces (seeded config only).
• DEP-006: mPDF (vendor/mpdf/mpdf — present), Phpqr (application/libraries/Phpqr.php + application/third_party/phpqr/ — present), CardMaker + Intervention Image (present), PhpSpreadsheet (present).
• DEP-007: Helpers: get_setting(), set_system_logs(), get_current_utc_time(), general_files helpers (move_temp_file_smart(), get_source_url_of_file()), notifications helper.
• DEP-008: .env key BARANGAY_ENCRYPTION_KEY (base64 32 bytes) — required before Phase 5 deploys; STOP and request if missing (credential policy).
• DEP-009: Working-day math needs the holidays table populated per tenant (existing Holidays feature).

5. Files

New Files (module package — representative, not exhaustive)

• FILE-001: modules/Barangay/module.json — manifest (slug barangay)
• FILE-002: modules/Barangay/config/{module_config,routes,menu,default_menu,permissions,system_logs,widgets,public_pages,document_templates,user_guides}.php
• FILE-003: modules/Barangay/migrations/ — 8 idempotent migrations (TASK-002/003/011/012/029/030/038/044/048; real timestamps at creation)
• FILE-004: modules/Barangay/models/ — ~22 models listed in tasks
• FILE-005: modules/Barangay/controllers/ — Barangay_residents.php, Barangay_households.php, Barangay_puroks.php, Barangay_officials.php, Barangay_settings.php, Barangay_documents.php, Barangay_treasury.php, Barangay_verify.php (public), Barangay_charter.php (public), Barangay_public.php (public), Barangay_portal.php (customer), Barangay_kp.php, Barangay_blotter.php, Barangay_vaw.php, Barangay_drrm.php, Barangay_health.php, Barangay_fdp.php, Barangay_records.php, Barangay_reports.php, Barangay_ids.php, Barangay_kiosk.php
• FILE-006: modules/Barangay/views/barangay/** — per-feature views + templates/ (certificates + KP forms)
• FILE-007: modules/Barangay/helpers/{barangay_helper,barangay_crypto_helper,barangay_widget_helper}.php
• FILE-008: modules/Barangay/jobs/{DocumentSlaSweepJob,KpDeadlineSweepJob,BpoExpirySweepJob,FdpComplianceSweepJob}.php
• FILE-009: modules/Barangay/seeders/{BarangayDocumentTypesSeeder,BarangayHelpdeskSeeder,BarangayFacilitiesSeeder,BarangayDemoSeeder}.php
• FILE-010: modules/Barangay/language/english/barangay_lang.php
• FILE-011: modules/Barangay/tests/{bootstrap.php,ResidencyEligibilityTest.php,KpDeadlineEngineTest.php,BudgetAllocationValidatorTest.php,VawIsolationTest.php,DocumentSerialTest.php}
• FILE-012: modules/Barangay/README.md, modules/Barangay/CHANGELOG.md

Modified Files (minimal, by design)

• FILE-101: modules/Content/config/cms.php — register module.barangay.* route_keys (charter, landing, transparency, verify info)
• FILE-102: .env.example — BARANGAY_ENCRYPTION_KEY=, optional SMS driver keys
• FILE-103: (none in core application/ — G15/G16 compliance: zero core routes, zero Roles.php rows, zero Left_menu edits)

Schema Changes (tenant DB, tracked in migrations_barangay)

• MIG-001: Registry: puroks, barangay_officials, residents, households, household_members, resident_sector_tags (+ indexes, dup-detection index)
• MIG-002: Documents: barangay_document_types, barangay_document_requests, barangay_document_requirements, barangay_issued_documents (UNIQUE serial), barangay_or_series, barangay_official_receipts (UNIQUE or_no), barangay_ftjs_registry (UNIQUE resident one-time)
• MIG-003: KP/Blotter: kp_cases, kp_hearings, kp_settlements, kp_pangkat_members, blotter_entries (UNIQUE entry_no), tanod_patrols, bpoc_members
• MIG-004: VAW: vaw_cases, vaw_bpo_orders, vaw_referrals, vaw_access_logs (encrypted columns + iv/tag)
• MIG-005: DRRM/Health: evacuation_centers, relief_distributions, relief_recipients, drrm_fund_entries, assistance_requests, health_visits
• MIG-006: Finance/Records: barangay_budgets, barangay_budget_allocations, fdp_postings, barangay_legislations, barangay_assemblies
• All tables end with created_by, created_at, updated_at, deleted.

Permissions (modules/Barangay/config/permissions.php)

• PERM-001: barangay — module access (default_level: module)
• PERM-002: barangay_resident + _create/_update/_delete — registry
• PERM-003: barangay_document + _create/_update/_delete — document queue
• PERM-004: barangay_signatory — sign/release issued documents
• PERM-005: barangay_treasurer — fees, ORs, RAAF, void
• PERM-006: barangay_kp + _create/_update/_delete — KP docket (Lupon Secretary/Chair)
• PERM-007: barangay_blotter + _create/_update/_delete — blotter/peace & order
• PERM-008: barangay_vaw — VAW Desk (restricted; NO admin-implied visibility in listings)
• PERM-009: barangay_drrm + _create/_update/_delete — DRRM operations
• PERM-010: barangay_health + _create/_update/_delete — health/social services
• PERM-011: barangay_finance — budgets, FDP, treasury reports
• PERM-012: barangay_records + _create/_update/_delete — legislations/assembly
• PERM-013: barangay_reports — reports & SGLGB dashboard
• PERM-014: barangay_settings — profile, document types, charter setup

Lang Keys (prefix barangay_; full list grows per phase — representative)

• LANG-001: barangay — module label; barangay_governance — menu group
• LANG-002: barangay_residents, barangay_households, barangay_puroks, barangay_officials
• LANG-003: barangay_documents, barangay_document_types, barangay_issued, barangay_verify_valid, barangay_verify_invalid, barangay_or, barangay_raaf
• LANG-004: barangay_kp_cases, barangay_kp_mediation, barangay_kp_pangkat, barangay_kp_settlement, barangay_kp_cfa, barangay_blotter
• LANG-005: barangay_vaw_desk, barangay_bpo, barangay_bpo_expires, barangay_vaw_confidential_notice
• LANG-006: barangay_drrm, barangay_evacuation_centers, barangay_relief, barangay_ldrrmf
• LANG-007: barangay_budget, barangay_fdp, barangay_legislations, barangay_assembly, barangay_charter
• LANG-008: CRUD toasts per entity: *_added, *_updated, *_deleted (declared explicitly in the lang file as built)

System Log Events (modules/Barangay/config/system_logs.php)

• LOG-001: created|updated|deleted:barangay_resident (+ viewed:barangay_resident for privacy audit)
• LOG-002: created|updated:barangay_document_request, issued|signed|released|revoked:barangay_document
• LOG-003: collected|voided:barangay_or
• LOG-004: created|staged|settled|repudiated|cfa_issued:kp_case
• LOG-005: created|referred:blotter_entry
• LOG-006: created|accessed:vaw_case, issued|served|expired:bpo_order
• LOG-007: posted:fdp_item, enacted|reviewed:barangay_budget, adopted|transmitted:barangay_legislation
• LOG-008: distributed:relief, approved|released:assistance_request

6. Testing

• TEST-001: ResidencyEligibilityTest — assembly eligibility (age/residency), residency duration math (pure helper, no DB).
• TEST-002: KpDeadlineEngineTest — 15d mediation, 15+15d conciliation, 10d repudiation, 6-month execution, CFA stage gating (pure model-method tests with injected dates).
• TEST-003: BudgetAllocationValidatorTest — each allocation computed off its correct base; enactment blocked when under-funded.
• TEST-004: VawIsolationTest — 403 without barangay_vaw; encrypted columns round-trip; no plaintext in get_details() without explicit decrypt.
• TEST-005: DocumentSerialTest — serial uniqueness, FTJS one-time block, QR token hash verify, free-document fee forced to 0.
• TEST-006: Migration idempotency — php erpat migrate:modules twice on fresh tenant; down() runs clean.
• TEST-007: Manual smoke per phase (list/create/update/delete + workflow transitions) via run-erpat; permission matrix toggle per PERM entry.
• TEST-008: Multi-tenancy isolation (TASK-060) — two tenants, parallel data, zero leakage; sessionless public endpoints resolve by company_key.
• TEST-009: Public QR verify returns only whitelisted fields (assert response shape).
• TEST-010: php erpat module:test Barangay green; core php erpat test:run green (ModuleLoaderTest default_menu requirement).

7. Risks & Assumptions

Risks

• RISK-001: VAW confidentiality breach is a statutory penalty risk (RA 9262 Sec 44, fines to ₱500k) — mitigated by encryption, permission wall, access logging, isolation test (TASK-042), and exclusion from every shared surface.
• RISK-002: Wrong statutory numbers (BPO 30d instead of 15d; single-base fund math; blotter=KP conflation) — mitigated by the research-verified rules baked into REQ text and unit tests (TEST-002/003).
• RISK-003: Scope breadth — 8 phases is a large module. Mitigated by strict phase gating: Phases 1–3 are a shippable MVP (registry + documents + citizen surface); each later phase is independently releasable.
• RISK-004: Working-day SLA math wrong when tenant holiday table is empty — mitigated by seeding national holidays in the demo seeder and a helper fallback (calendar days + warning flag).
• RISK-005: Serial/OR race conditions under concurrent issuance — mitigated by UNIQUE indexes + atomic next-number claim (Pattern 17).
• RISK-006: Public endpoints (verify, charter, kiosk) enlarge the attack surface — mitigated by GuestController + rate limiting + whitelisted response shapes + security-review pass (TASK-058).
• RISK-007: Reused modules disabled by a tenant admin (Helpdesk/Content/Finance) — mitigated by fail-safe gates: widgets/hooks check module_enabled() and degrade (documented in README).
• RISK-008: DILG format drift (BFDP forms, KP form revisions, LGUSS-BIMS fields) — mitigated by template-registry indirection (templates are config-mapped views, replaceable without schema change).

Assumptions

• ASSUMPTION-001: One barangay = one tenant; the LGU/operator provisions tenants via the existing Tenancy flow. Cross-barangay (city-level) aggregation is out of scope v1.
• ASSUMPTION-002: Residents do NOT require login for staff-side operations; citizen portal accounts are optional customer users linked to resident rows.
• ASSUMPTION-003: PhilSys integration v1 = store PCN + use the free public eVerify QR check operationally; the relying-party eVerify API awaits PSA onboarding (out of scope).
• ASSUMPTION-004: eBOSS/city-BPLS integration is export/status-surface only in v1 (no API agreement yet — matches prototype's "For API agreement" status).
• ASSUMPTION-005: AI copilot features (triage drafts, summaries) are deferred; Helpdesk's existing surfaces stand in where applicable.
• ASSUMPTION-006: The original plan's officer offline-first field app is deferred; the End-User API is the future mobile path.

8. Related Specifications / Further Reading

• Input documents: barangay_module_claude_implementation_plan.md (original greenfield plan), barangay_governance_module_prototype.html (IA/screen prototype — menus and flows authoritative, visual style not).
• .claude/rules/module-files.md — the module contract (G1–G16); companion skill module-dev.
• specs/modular-architecture-documentation/20-FEATURE-MODULARIZATION-RUNBOOK.md, 17/18/21 contracts.
• .claude/rules/{migrations,security-owasp,sql-standards,seo-dynamic-page,general-files,seeders,multi-tenancy,theming,html-css-style}.md.
• Reference modules: modules/Todo/ (canon), modules/Lending/ (PH-compliance patterns), modules/Helpdesk/, modules/Pos/ (receipt series), modules/Recruitment/ (public portal + consent), application/controllers/Kiosk_manager.php (sessionless tenant), application/libraries/CardMaker.php + Phpqr.php.
• Legal grounding (verified 2026-07-10 via research pass): RA 7160 Ch.7 Secs 399–422 + SC AC 14-93 (KP; summons next-working-day, 15/≤3-day-convene/15+15/10-day/6-month/60-day timelines, KP Forms 1–25 with printing-variance caveat, full exclusion list incl. juridical entities/labor/agrarian; RA 9262 §33 bars VAWC conciliation); DILG MC 2023-022/2023-110 (LTIA — searchable case records, ≥10 settlements); RA 9262 + JMC 2010-2 + DILG MC 2017-114 (VAW Desk; BPO 15-day, ex parte, PB/Kagawad+attestation, Sec 44 confidentiality); EO 309/366 + DILG MC 2020-047 (BPOC, BPOPSP, monthly meetings) + DILG MC 2003-042 (Tanod); RA 11261 + IRR (FTJS free/one-time/1-year/oath/roster); RA 11032 (3/7/20 working days, Citizen's Charter 6 points, deemed approval); LGC Sec 152 (clearance fees, retailer tax ≤1% within ₱50k/₱30k ceilings) + 7-working-day business-clearance rule; LGC Secs 391/397-398 + Proclamation 599 (assembly March/October, 1-week notice; ordinance penalty ceiling ₱1,000; Sec 57 10-day transmit/30-day deemed-approved review); NAP GRDS circulars (retention/disposal — pull exact per-series values from NAP before hardcoding); DILG MC 2010-083/2011-134/2010-149/2014-81/2022-027 + LGC Sec 352 (FDP: 8-item BFDP set, dual posting, BFDP Monitoring Form 1); RA 10742 §20 (SK 10% of general fund), RA 9710 (GAD ≥5% of total budget), RA 10121 §21 (LDRRMF ≥5% of regular revenue, 70/30, 5-year trust), RA 9994/RA 10070 (separate 1% senior + 1% PWD of IRA), LGC §287 (20% Dev Fund of NTA), LGC §333 (60-day budget review); COA Manual on Financial Management of Barangays (OR/RAAF serial control, BFR); RA 10173 + NPC opinions (consent, blotter confidentiality, DPO, 72-hour breach); RA 11292 + DILG SGLGB MCs (3 core + 1 essential — DILG construct; BADAC functionality is a core Safety indicator); RA 11055 + EO 162 (PhilSys/eVerify); DILG LGUSS-BIMS mandate (11 sub-systems — align exports, don't compete).