# chis132060/barangay_ai architecture

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

- Interactive diagram: https://gitdiagram.com/chis132060/barangay_ai
- Repository: https://github.com/chis132060/barangay_ai

## Overview

Smart Barangay is a resident-services platform with an administrative portal, resident PWA, FastAPI backend, and AI-assisted knowledge services. Residents and staff use the web experiences to access requests, records, announcements, certificates, and assistance; the backend handles API workflows and connects to shared data and AI capabilities. The graph preserves the documented RAG, memory, and provider stages, plus administration and communication features. Some frontend-to-backend and storage links are shown from README documentation; unsampled implementation details are not inferred.

Main entry points: [`apps/admin-portal/app/(dashboard)/layout.tsx`](https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/layout.tsx) (Admin Portal), [`apps/api/main.py`](https://github.com/chis132060/barangay_ai/blob/main/apps/api/main.py) (FastAPI Backend), [`apps/api/services/orchestrator.py`](https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/orchestrator.py) (RAG Orchestrator), [`apps/resident-pwa/app/(app)/layout.tsx`](https://github.com/chis132060/barangay_ai/blob/main/apps/resident-pwa/app/(app)/layout.tsx) (Resident PWA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Administration"]
  node_admin_portal["Admin Portal<br/>[layout.tsx]"]
  node_resident_records["Resident Records<br/>[actions.ts]"]
  node_rbac["Roles &amp; Access<br/>[rbac-actions.ts]"]
  node_business["Business Services<br/>[actions.ts]"]
  node_communications["Communications<br/>[actions.ts]"]
  node_documents["Documents &amp; Requests<br/>[actions.ts]"]
end

subgraph group_resident["Resident Services"]
  node_resident_pwa["Resident PWA<br/>[layout.tsx]"]
  node_service_requests["Service Requests<br/>[actions.ts]"]
  node_chat["Chat Interface<br/>[route.ts]"]
end

subgraph group_backend["Backend API"]
  node_api["FastAPI Backend<br/>[main.py]"]
  node_rag_routes["RAG Endpoints<br/>[rag_router.py]"]
  node_graphql["GraphQL API<br/>[schema.py]"]
end

subgraph group_ai["AI Knowledge Services"]
  node_orchestrator["RAG Orchestrator<br/>[orchestrator.py]"]
  node_retrieval["Hybrid Retrieval<br/>[hybrid_search.py]"]
  node_memory["Conversation Memory<br/>[memory_service.py]"]
  node_ai_providers["AI Provider Manager<br/>[manager.py]"]
  node_ai_policy["AI Policy Engine<br/>[policy_engine.py]"]
end

subgraph group_integrations["Platform Integrations"]
  node_supabase[("Supabase Data")]
  node_vector_index[("Knowledge Index")]
  node_firebase["Firebase Notifications"]
end

node_staff(("Barangay Staff"))
node_residents(("Residents"))

node_residents -->|"use"| node_resident_pwa
node_staff -->|"use"| node_admin_portal
node_resident_pwa -->|"access"| node_api
node_admin_portal -->|"access"| node_api
node_resident_pwa -->|"submit requests"| node_service_requests
node_resident_pwa -->|"ask questions"| node_chat
node_admin_portal -->|"manage records"| node_resident_records
node_admin_portal -->|"manage access"| node_rbac
node_admin_portal -->|"manage services"| node_business
node_admin_portal -->|"manage announcements"| node_communications
node_admin_portal -->|"process certificates"| node_documents
node_api -->|"mounts routes"| node_rag_routes
node_api -->|"mounts schema"| node_graphql
node_rag_routes -->|"invoke"| node_orchestrator
node_rag_routes -.->|"audit via service"| node_supabase
node_orchestrator -->|"retrieve context"| node_retrieval
node_orchestrator -->|"retrieve context"| node_memory
node_orchestrator -->|"generate responses"| node_ai_providers
node_orchestrator -->|"read/write data"| node_supabase
node_api -->|"use shared data"| node_supabase
node_api -->|"use knowledge index"| node_vector_index
node_api -.->|"send notifications"| node_firebase
node_ai_providers -.->|"policy gate"| node_ai_policy

click node_admin_portal "https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/layout.tsx"
click node_resident_records "https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/residents/actions.ts"
click node_rbac "https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/administration/rbac-actions.ts"
click node_business "https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/business/actions.ts"
click node_communications "https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/communication/actions.ts"
click node_documents "https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/documents/actions.ts"
click node_resident_pwa "https://github.com/chis132060/barangay_ai/blob/main/apps/resident-pwa/app/(app)/layout.tsx"
click node_service_requests "https://github.com/chis132060/barangay_ai/blob/main/apps/resident-pwa/app/(app)/requests/actions.ts"
click node_chat "https://github.com/chis132060/barangay_ai/blob/main/apps/resident-pwa/app/api/chat/route.ts"
click node_api "https://github.com/chis132060/barangay_ai/blob/main/apps/api/main.py"
click node_rag_routes "https://github.com/chis132060/barangay_ai/blob/main/apps/api/routers/rag_router.py"
click node_graphql "https://github.com/chis132060/barangay_ai/blob/main/apps/api/graphql_api/schema.py"
click node_orchestrator "https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/orchestrator.py"
click node_retrieval "https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/ai/retrieval/hybrid_search.py"
click node_memory "https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/memory/memory_service.py"
click node_ai_providers "https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/ai/manager.py"
click node_ai_policy "https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/ai/policy/policy_engine.py"
click node_supabase "https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/supabase_service.py"

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_admin_portal,node_resident_records,node_rbac,node_business,node_communications,node_documents toneBlue
class node_resident_pwa,node_service_requests,node_chat toneAmber
class node_api,node_rag_routes,node_graphql toneMint
class node_orchestrator,node_retrieval,node_memory,node_ai_providers,node_ai_policy toneRose
class node_supabase,node_vector_index,node_firebase,node_staff,node_residents toneIndigo
```

## Components

### Administration

- [Admin Portal](https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/layout.tsx): `apps/admin-portal/app/(dashboard)/layout.tsx`
- [Resident Records](https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/residents/actions.ts): `apps/admin-portal/app/(dashboard)/residents/actions.ts`
- [Roles & Access](https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/administration/rbac-actions.ts): `apps/admin-portal/app/(dashboard)/administration/rbac-actions.ts`
- [Business Services](https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/business/actions.ts): `apps/admin-portal/app/(dashboard)/business/actions.ts`
- [Communications](https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/communication/actions.ts): `apps/admin-portal/app/(dashboard)/communication/actions.ts`
- [Documents & Requests](https://github.com/chis132060/barangay_ai/blob/main/apps/admin-portal/app/(dashboard)/documents/actions.ts): `apps/admin-portal/app/(dashboard)/documents/actions.ts`

### Resident Services

- [Resident PWA](https://github.com/chis132060/barangay_ai/blob/main/apps/resident-pwa/app/(app)/layout.tsx): `apps/resident-pwa/app/(app)/layout.tsx`
- [Service Requests](https://github.com/chis132060/barangay_ai/blob/main/apps/resident-pwa/app/(app)/requests/actions.ts): `apps/resident-pwa/app/(app)/requests/actions.ts`
- [Chat Interface](https://github.com/chis132060/barangay_ai/blob/main/apps/resident-pwa/app/api/chat/route.ts): `apps/resident-pwa/app/api/chat/route.ts`

### Backend API

- [FastAPI Backend](https://github.com/chis132060/barangay_ai/blob/main/apps/api/main.py): `apps/api/main.py`
- [RAG Endpoints](https://github.com/chis132060/barangay_ai/blob/main/apps/api/routers/rag_router.py): `apps/api/routers/rag_router.py`
- [GraphQL API](https://github.com/chis132060/barangay_ai/blob/main/apps/api/graphql_api/schema.py): `apps/api/graphql_api/schema.py`

### AI Knowledge Services

- [RAG Orchestrator](https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/orchestrator.py): `apps/api/services/orchestrator.py`
- [Hybrid Retrieval](https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/ai/retrieval/hybrid_search.py): `apps/api/services/ai/retrieval/hybrid_search.py`
- [Conversation Memory](https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/memory/memory_service.py): `apps/api/services/memory/memory_service.py`
- [AI Provider Manager](https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/ai/manager.py): `apps/api/services/ai/manager.py`
- [AI Policy Engine](https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/ai/policy/policy_engine.py): `apps/api/services/ai/policy/policy_engine.py`

### Platform Integrations

- [Supabase Data](https://github.com/chis132060/barangay_ai/blob/main/apps/api/services/supabase_service.py): `apps/api/services/supabase_service.py`
- **Knowledge Index**
- **Firebase Notifications**

### Other components

- **Barangay Staff**
- **Residents**

## Connections

- Residents → Resident PWA: use (evidence: `README.md`)
- Barangay Staff → Admin Portal: use (evidence: `README.md`)
- Resident PWA → FastAPI Backend: access (evidence: `README.md`)
- Admin Portal → FastAPI Backend: access (evidence: `README.md`)
- Resident PWA → Service Requests: submit requests (evidence: `README.md`)
- Resident PWA → Chat Interface: ask questions (evidence: `README.md`)
- Admin Portal → Resident Records: manage records (evidence: `README.md`)
- Admin Portal → Roles & Access: manage access
- Admin Portal → Business Services: manage services (evidence: `README.md`)
- Admin Portal → Communications: manage announcements (evidence: `README.md`)
- Admin Portal → Documents & Requests: process certificates (evidence: `README.md`)
- FastAPI Backend → RAG Endpoints: mounts routes (evidence: `apps/api/main.py`)
- FastAPI Backend → GraphQL API: mounts schema (evidence: `apps/api/main.py`)
- RAG Endpoints → RAG Orchestrator: invoke (evidence: `apps/api/routers/rag_router.py`)
- RAG Endpoints → Supabase Data: audit via service (evidence: `apps/api/routers/rag_router.py`)
- RAG Orchestrator → Hybrid Retrieval: retrieve context (evidence: `apps/api/services/orchestrator.py`)
- RAG Orchestrator → Conversation Memory: retrieve context (evidence: `apps/api/services/orchestrator.py`)
- RAG Orchestrator → AI Provider Manager: generate responses (evidence: `apps/api/services/orchestrator.py`)
- RAG Orchestrator → Supabase Data: read/write data (evidence: `apps/api/services/orchestrator.py`)
- FastAPI Backend → Supabase Data: use shared data (evidence: `README.md`)
- FastAPI Backend → Knowledge Index: use knowledge index (evidence: `README.md`)
- FastAPI Backend → Firebase Notifications: send notifications (evidence: `README.md`)
- AI Provider Manager → AI Policy Engine: policy gate