# fenrir315/barangayconnect-system-roadmap-planning architecture

> Architecture diagram of the GitHub repository fenrir315/barangayconnect-system-roadmap-planning, 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/fenrir315/barangayconnect-system-roadmap-planning
- Repository: https://github.com/fenrir315/barangayconnect-system-roadmap-planning

## Overview

BarangayConnect is a barangay operations and resident-services platform. Residents and staff use separate portals to manage records and submit requests; staff process documents through approval and release, while appointments, complaints, and incidents have their own status workflows. The app also provides announcements, payments, reporting, audit trails, and public certificate verification. The sampled API shows a local PostgreSQL query gateway that authorizes and executes writes, then dispatches notifications and queued email. Several portal implementations were not sampled, so their data wiring is shown only where documented or explicit in the API.

Main entry points: [`src/app/api/local/db/route.ts`](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/api/local/db/route.ts) (Query API), [`src/app/resident`](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/resident) (Resident portal), [`src/app/admin`](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin) (Admin portal), [`src/app/api/documents/[id]/print/route.tsx`](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/api/documents/%5Bid%5D/print/route.tsx) (Certificate printing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["Portals and access"]
  node_residents["Resident portal"]
  node_admin["Admin portal"]
  node_login["Login page<br/>[page.tsx]"]
  node_auth["Auth context<br/>[useAuth.tsx]"]
end

subgraph group_operations["Barangay operations"]
  node_records["Residents and households"]
  node_documents["Document workflow"]
  node_appointments["Appointments"]
  node_complaints["Complaints"]
  node_incidents["Incident tracking"]
  node_announcements["Announcements"]
  node_payments["Payments"]
  node_reports["Reports and exports"]
  node_verify["Certificate verification<br/>[page.tsx]"]
end

subgraph group_services["Platform services"]
  node_authapi["Local auth API<br/>[route.ts]"]
  node_proxy["Role routing<br/>[proxy.ts]"]
  node_dbapi["Query API<br/>[route.ts]"]
  node_sql["SQL execution<br/>[sql.ts]"]
  node_acl["Query authorization<br/>[dbacl.ts]"]
  node_notify["Write notifications<br/>[notify.ts]"]
  node_mail["Email queue<br/>[mail.ts]"]
  node_print["Certificate printing<br/>[route.tsx]"]
  node_files["File endpoints<br/>[route.ts]"]
end

subgraph group_data["Persistence and integrations"]
  node_postgres[("PostgreSQL")]
end

node_resident_actor(("Resident"))
node_staff_actor(("Barangay staff"))
node_public_actor(("Public visitor"))

node_resident_actor -->|"uses"| node_residents
node_staff_actor -->|"uses"| node_admin
node_residents -->|"signs in"| node_login
node_admin -->|"signs in"| node_login
node_login -->|"authenticates"| node_authapi
node_auth -->|"checks session"| node_authapi
node_authapi -->|"reads and writes"| node_postgres
node_proxy -->|"checks role"| node_auth
node_residents -->|"queries records"| node_dbapi
node_admin -->|"manages records"| node_dbapi
node_dbapi -->|"authorizes query"| node_acl
node_dbapi -->|"executes query"| node_sql
node_sql -->|"reads and writes"| node_postgres
node_dbapi -->|"dispatches writes"| node_notify
node_dbapi -->|"drains queue"| node_mail
node_notify -->|"writes notifications"| node_postgres
node_mail -->|"reads pending mail"| node_postgres
node_documents -->|"requests PDF"| node_print
node_print -->|"reads certificate data"| node_postgres
node_print -->|"provides certificate number"| node_verify
node_public_actor -->|"checks certificate"| node_verify
node_residents -->|"uploads evidence"| node_files
node_admin -->|"uploads attachments"| node_files
node_files -->|"writes audit records"| node_postgres
node_reports -->|"reads report data"| node_dbapi

click node_residents "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/resident"
click node_admin "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin"
click node_login "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/(auth)/login/page.tsx"
click node_auth "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/hooks/useAuth.tsx"
click node_authapi "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/api/local/auth/route.ts"
click node_proxy "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/proxy.ts"
click node_records "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/residents"
click node_documents "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/documents"
click node_appointments "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/appointments"
click node_complaints "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/complaints"
click node_incidents "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/incidents"
click node_announcements "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/announcements"
click node_payments "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/payments"
click node_reports "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/reports"
click node_verify "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/verify/%5BcertificateNumber%5D/page.tsx"
click node_dbapi "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/api/local/db/route.ts"
click node_sql "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/lib/local/sql.ts"
click node_acl "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/lib/local/dbacl.ts"
click node_notify "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/lib/notify.ts"
click node_mail "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/lib/mail.ts"
click node_print "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/api/documents/%5Bid%5D/print/route.tsx"
click node_files "https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/api/local/files/route.ts"

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_residents,node_admin,node_login,node_auth toneBlue
class node_records,node_documents,node_appointments,node_complaints,node_incidents,node_announcements,node_payments,node_reports,node_verify toneAmber
class node_authapi,node_proxy,node_dbapi,node_sql,node_acl,node_notify,node_mail,node_print,node_files toneMint
class node_postgres toneRose
class node_resident_actor,node_staff_actor,node_public_actor toneIndigo
```

## Components

### Portals and access

- [Resident portal](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/resident): `src/app/resident`
- [Admin portal](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin): `src/app/admin`
- [Login page](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/(auth)/login/page.tsx): `src/app/(auth)/login/page.tsx`
- [Auth context](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/hooks/useAuth.tsx): `src/hooks/useAuth.tsx`

### Barangay operations

- [Residents and households](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/residents): `src/app/admin/residents`
- [Document workflow](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/documents): `src/app/admin/documents`
- [Appointments](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/appointments): `src/app/admin/appointments`
- [Complaints](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/complaints): `src/app/admin/complaints`
- [Incident tracking](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/incidents): `src/app/admin/incidents`
- [Announcements](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/announcements): `src/app/admin/announcements`
- [Payments](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/payments): `src/app/admin/payments`
- [Reports and exports](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/tree/master/src/app/admin/reports): `src/app/admin/reports`
- [Certificate verification](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/verify/%5BcertificateNumber%5D/page.tsx): `src/app/verify/[certificateNumber]/page.tsx`

### Platform services

- [Local auth API](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/api/local/auth/route.ts): `src/app/api/local/auth/route.ts`
- [Role routing](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/proxy.ts): `src/proxy.ts`
- [Query API](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/api/local/db/route.ts): `src/app/api/local/db/route.ts`
- [SQL execution](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/lib/local/sql.ts): `src/lib/local/sql.ts`
- [Query authorization](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/lib/local/dbacl.ts): `src/lib/local/dbacl.ts`
- [Write notifications](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/lib/notify.ts): `src/lib/notify.ts`
- [Email queue](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/lib/mail.ts): `src/lib/mail.ts`
- [Certificate printing](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/api/documents/%5Bid%5D/print/route.tsx): `src/app/api/documents/[id]/print/route.tsx`
- [File endpoints](https://github.com/fenrir315/barangayconnect-system-roadmap-planning/blob/master/src/app/api/local/files/route.ts): `src/app/api/local/files/route.ts`

### Persistence and integrations

- **PostgreSQL**

### Other components

- **Resident**
- **Barangay staff**
- **Public visitor**

## Connections

- Resident → Resident portal: uses
- Barangay staff → Admin portal: uses
- Resident portal → Login page: signs in
- Admin portal → Login page: signs in
- Login page → Local auth API: authenticates
- Auth context → Local auth API: checks session
- Local auth API → PostgreSQL: reads and writes
- Role routing → Auth context: checks role
- Resident portal → Query API: queries records
- Admin portal → Query API: manages records
- Query API → Query authorization: authorizes query
- Query API → SQL execution: executes query
- SQL execution → PostgreSQL: reads and writes
- Query API → Write notifications: dispatches writes
- Query API → Email queue: drains queue
- Write notifications → PostgreSQL: writes notifications
- Email queue → PostgreSQL: reads pending mail
- Document workflow → Certificate printing: requests PDF
- Certificate printing → PostgreSQL: reads certificate data
- Certificate printing → Certificate verification: provides certificate number
- Public visitor → Certificate verification: checks certificate
- Resident portal → File endpoints: uploads evidence
- Admin portal → File endpoints: uploads attachments
- File endpoints → PostgreSQL: writes audit records
- Reports and exports → Query API: reads report data