Milestone-Based Youth Governance & Civic Accountability Platform Deployed on Stellar Soroban Testnet and powered by Firebase and Google Gemini 2.5 AI.
- Overview
- Problem & Solution
- Visual Interface Showcase
- System Architecture
- User Roles & Access Control Matrix
- Smart Contract Escrow Engine (Rust / Soroban)
- Google Gemini 2.5 AI Dual-Telemetry Engine
- Philippine Statutory & Legal Framework
- User Journeys & Lifecycle Flows
- Firestore Collections Schema
- Security & Governance Safeguards
- Tech Stack
- Environment Variables
- Local Setup & Installation
- Folder Structure
- Project Roadmap
- License & Authors
Barangay Bond is a decentralized civic banking platform built specifically for Sangguniang Kabataan (SK) youth governance and local community accountability in the Philippines. It bridges official local government administration and citizen verification with public blockchain trust networks.
By pairing Stellar Soroban WASM smart contracts with Google Gemini 2.5 AI and Firebase Cloud Firestore, Barangay Bond guarantees that municipal civic budgets are locked in tamper-proof escrow contracts. Funds are disbursed in multi-phase milestone tranches only when verified local youth residents review uploaded accomplishment proofs (site photos, receipts) and cast on-chain consensus votes.
- Centralized Discretion & Ghost Projects: Local youth development funds are susceptible to uncontrolled lump-sum releases, project abandonment, and opaque accounting without citizen oversight.
- Low Civic Engagement: Youth residents lack simple, transparent channels to audit community initiatives, vote on fund releases, and inspect financial ledgers in real time.
- Identity Spoofing & Sybil Attacks: Online voting and project registration are prone to duplicate accounts, fake credentials, and non-resident participation.
- Multi-Phase Smart Contract Escrows: 100% of approved project budgets are locked on-chain in Soroban smart contracts. Funds are partitioned into milestone tranches (e.g. 40%-30%-30%) disbursed sequentially upon citizen consensus.
- Gemini 2.5 AI Proposal Telemetry: Pre-audits project feasibility against Philippine Department of Trade and Industry (DTI) market rate indices to flag budget padding before escrow lock.
- AI OCR Document Verification: Real-time visual analysis of Philippine government IDs (PhilSys, Postal ID, Driver's License, Voter's ID) with PSGC boundary matching to prevent duplicate registrations.
- Cryptographic e-OR Receipts: Automated generation of print-ready electronic Official Receipts (e-ORs) compliant with R.A. 8792 for every on-chain tranche payout.
- Immutable Public Audit Trails: Every voter registration, project proposal, milestone proof, and fund release is logged immutably on the Stellar blockchain explorer.
| Landing Page (Dark Mode) | 3D Holographic Vault Parallax HUD |
|---|---|
![]() |
![]() |
| Interactive Protocol Engine (4-Phase Escrow) | 7-Stack Technology Architecture Grid |
|---|---|
![]() |
![]() |
| Philippine Statutory Compliance (R.A. 7160, 10742, 8792) | 12-Item Searchable System FAQ |
|---|---|
![]() |
![]() |
| Admin Treasury Overview & Escrow Vault | Resident KYC Verification Queue (AI Match Scoring) |
|---|---|
![]() |
![]() |
| Admin Dashboard Overview & Live Telemetry | Resident ID Inspection & Validation Modal |
|---|---|
![]() |
![]() |
| SK Studio Workspace | 3-Tranche Milestone Division Editor |
|---|---|
![]() |
![]() |
| SK Projects Management | SK Official Financial Dashboard |
|---|---|
![]() |
![]() |
| Resident Mobile Dashboard & Civic Keypair | Mobile Projects & Deliverables View |
|---|---|
![]() |
![]() |
| Citizen Milestone Voting & Proof Modal | Mobile Activity & Immutable Ledger |
|---|---|
![]() |
![]() |
| Public Ledger Feed (Guest Explorer Mode) | Active Project Milestones & Deliverables Modal |
|---|---|
![]() |
![]() |
| Civic Auth Sign-In Portal | 4-Step Resident Registration & PSGC Selector |
|---|---|
![]() |
![]() |
Barangay Bond implements a modular architecture combining reactive off-chain data coordination (Firebase Firestore + Google Gemini AI) with decentralized cryptographic finality (Stellar Soroban).
graph TD
Browser[Client Vite Web App] -->|1. Sign Up / Upload Gov ID| FirebaseStorage[Firestore uploaded_documents]
Browser -->|2. Form Data / Base64 Profile| FirebaseAuth[Firebase Auth Credential]
FirebaseAuth -->|3. Trigger Verification Hook| FirestoreDB[(Firestore Database)]
FirestoreDB -->|4. Retrieve Document Ref| GeminiAI[Google Gemini 2.5 Vision API]
GeminiAI -->|5. Title Case/Fuzzy OCR Match| Browser
Browser -->|6. In-App Keypair / SWK Link| SWK[StellarWalletsKit / Civic Vault]
SWK -->|7. Sign Transaction Envelope| RPC[Stellar Testnet RPC Node]
RPC -->|8. Execute State Transition| Soroban[Soroban Smart Contract #707]
Soroban -->|9. Emit Events on State Change| EventPoll[Events Polling Service]
EventPoll -->|10. Feed Real-Time Dashboard| Browser
The platform enforces a hierarchical, role-based access control (RBAC) model aligned with Philippine Local Government Code boundaries:
SYSTEM ADMIN βββΊ Approves Barangays & Barangay Admins, Monitors System Audits
β
ββββΊ BARANGAY ADMIN βββΊ Manages Treasury, Locks Escrow, Verifies KYC Queue
β
ββββΊ SK OFFICIAL βββΊ Proposes Projects, Defines Tranches, Uploads Milestone Proof
β
ββββΊ RESIDENT (YOUTH 15-30) βββΊ Votes on Milestones, Audits Proofs, Manages Civic Vault
β
ββββΊ PUBLIC EXPLORER / VIEWER βββΊ Read-only inspection of ledgers & e-OR receipts
- System Admin: Platform supervisor. Verifies new LGU onboarding requests, audits cross-barangay telemetry, and manages root security configurations.
- Barangay Admin (Captain / Treasurer): Executive treasury authority. Reviews Gemini AI proposal scores, locks 100% budget into Soroban escrow, and verifies resident KYC profiles.
- SK Official (Youth Council Lead): Civic project builder. Drafts proposals, partitions budgets into multi-phase tranches, and uploads milestone completion proofs.
- Youth Resident (15β30 Years Old): Democratic citizen auditor. Holds In-App Civic Keypair voting rights to approve or reject milestone proofs before funds can be released.
- Public Explorer (Guest): Open-access auditor. Browses public project ledgers, inspects deliverable photos, and downloads official receipts without signing in.
Budgets are guarded on-chain by the barangay_bond Soroban contract written in Rust and compiled to WebAssembly (WASM):
pub fn create_project(
env: Env,
admin: Address,
sk_official: Address,
name: String,
budget: i128,
description: String,
milestones: Vec<u32>, // Custom percentage splits summing to 100%
immediate_phase_1: bool, // Immediate Mobilization vs Public Feasibility Vote
) -> u32;
pub fn submit_milestone_proof(
env: Env,
sk_official: Address,
project_id: u32,
milestone_index: u32,
proof_url: String,
);
pub fn vote_milestone(
env: Env,
voter: Address,
project_id: u32,
milestone_index: u32,
approve: bool,
);-
Budget Integrity:
milestones.iter().sum() == 100is enforced at execution. Total project budget is transferred directly to the contract account. -
Conflict of Interest Protection (R.A. 10742):
voter != project.creatorβ SK Officials cannot vote on their own project milestones. -
Separation of Powers:
voter != adminβ Barangay Admins are blocked from voting on citizen consensus quorums. -
Tranche-Gated Payouts: Funds for Phase
$N$ are disbursed only when milestone approvals reach quorum consensus.
sequenceDiagram
participant SK as SK Official
participant BA as Barangay Admin
participant SC as Soroban Smart Contract
participant R as Verified Residents
SK->>BA: Submit Proposal (Multi-Tranche Division)
BA->>SC: create_project(100% Budget Escrow Lock)
SC->>SK: Disburse Phase 1 Mobilization (if enabled)
SK->>SC: submit_milestone_proof(Photos, Receipts)
R->>SC: vote_milestone(Approve / Reject)
Note over R,SC: Requires Consensus Quorum
SC->>SK: release_milestone_escrow(Phase N Payout)
SC-->>SK: Generate Electronic Official Receipt (e-OR)
Barangay Bond incorporates Google Gemini 2.5 Flash across two critical governance pipelines:
graph LR
subgraph "1. Proposal Risk & Cost Telemetry"
A[SK Proposal Submission] --> B[Gemini Budget Analyzer]
B --> C[DTI Municipal Index Check]
C --> D[Feasibility Score 0-100]
D --> E[Admin Escrow Recommendation]
end
subgraph "2. Multi-Modal Identity KYC"
F[Resident ID + Selfie] --> G[Canvas Client Downscaler]
G --> H[Gemini Vision OCR]
H --> I[PSGC Boundary Matching]
I --> J[Duplicate & Sybil Detection]
end
- Autonomous Proposal Auditor: Analyzes itemized material costs, compares pricing with Philippine Department of Trade and Industry (DTI) indices, and assigns a scope feasibility rating.
- Identity Verification & Anti-Sybil Pipeline: Cross-validates government ID details against PSGC registered barangay boundaries and performs multi-factor fuzzy matching to block duplicate enrollments.
Barangay Bond is engineered to fulfill the requirements of three core Philippine Republic Acts:
| Republic Act | Governance Statute | System Implementation |
|---|---|---|
| R.A. 7160 | Local Government Code of 1991 | Full public disclosure and open ledger inspection for all LGU disbursements. |
| R.A. 10742 | Sangguniang Kabataan Reform Act of 2015 | Democratic youth quorum requirements and financial autonomy for youth councils. |
| R.A. 8792 | Electronic Commerce Act of 2000 | Cryptographically signed electronic Official Receipts (e-ORs) with verifiable hashes. |
Guest βββΊ Sign Up βββΊ PSGC LGU Select βββΊ Upload ID & Photo βββΊ Gemini OCR Match βββΊ Admin KYC Approval βββΊ In-App Keypair Generated βββΊ Active Citizen βββΊ Vote on Milestone Proofs
SK Official βββΊ Draft Proposal βββΊ 3-Tranche Breakdown βββΊ Gemini AI Telemetry βββΊ Barangay Admin Locks Escrow βββΊ Execute Milestone βββΊ Upload Site Photos/Receipts βββΊ Citizen Quorum Passed βββΊ Automatic Tranche Payout βββΊ Download e-OR PDF
The platform organizes its off-chain user profiles, verification queues, and audit feeds in a normalized Firestore structure:
| Collection | Purpose | Access Control |
|---|---|---|
users |
User profiles, roles (resident, sk_official, barangay_admin), and verification scores |
Authenticated user write own; Admin read/update. |
barangays |
Master directory of approved Philippine LGUs and PSGC codes | System Admin write; Public read. |
resident_verification_queue |
Pending citizen applicants with Gemini OCR scorecards | Barangay Admin read/update. |
project_proposals |
Itemized proposals, AI audit telemetry, and milestone specs | SK Official write; Admin review; Public read. |
uploaded_documents |
Isolated Base64 government IDs and verification photos | Secure upload hook; Admin audit read-only. |
audit_logs |
Immutable audit trial of all administrative and governance events | System-generated write; Admin read-only. |
wallet_links |
Links Firestore UIDs to public Stellar account keys | Owner write; Public read to verify voting keys. |
- Data Isolation: All sensitive identity documents (Base64 images) are housed in
/uploaded_documents, completely isolated from general user profiles to prevent data harvesting. - Anti-Enumeration Rules: Unauthenticated users cannot read or search user collections. Duplicate scanning for signups is wrapped in safe client blocks and computed securely in administrator sessions.
- Session Verification Hooks: Account statuses (
pending,suspended,inactive) are evaluated synchronously on bothsignInandonAuthStateChangedcallbacks to prevent session hijacking. - Dual Wallet Architecture: Frictionless In-App Civic Keypair Vault for 1-click citizen transactions, with optional support for external hardware/software wallets (Freighter, Albedo, xBull).
- Frontend Framework: React 19, TypeScript 6, Vite 8
- Styling Engine: Vanilla CSS (Glassmorphic Specular Highlights & Micro-animations)
- Blockchain Core: Stellar Network, Soroban Smart Contracts (Rust / WASM)
- Wallet Protocol: In-App Civic Keypairs +
@creit-tech/stellar-wallets-kit - Off-Chain Backend: Firebase (Authentication, Cloud Firestore, Security Rules)
- AI Telemetry: Google Gemini 2.5 Flash Vision & Text APIs
- Receipt Engine: jsPDF R.A. 8792 Electronic Official Receipt Generator
- Geographic Index: Philippine Standard Geographic Code (PSGC) API
Create a .env file at the root of the project to configure your API integrations:
# Gemini API Key (Identity OCR & Proposal Telemetry)
VITE_GEMINI_API_KEY=AIzaSy...
# Firebase Client Configuration
VITE_FIREBASE_API_KEY=AIzaSy...
VITE_FIREBASE_AUTH_DOMAIN=tugma-8514e.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=tugma-8514e
VITE_FIREBASE_STORAGE_BUCKET=tugma-8514e.firebasestorage.app
VITE_FIREBASE_MESSAGING_SENDER_ID=578517024363
VITE_FIREBASE_APP_ID=1:578517024363:web:5ed04cf894eb1e73f4bb2e
VITE_FIREBASE_MEASUREMENT_ID=G-874ELHD8J6- Node.js v22.14.0+ & npm v11.2.0+
- Rust 1.95.0+ with target
wasm32v1-none - Stellar CLI 26.0.0+
- A Stellar wallet browser extension (e.g., Freighter) configured for Stellar Testnet.
-
Clone the Repository:
git clone https://github.com/FWDP/barangay-bond.git cd barangay-bond -
Initialize Environment Configuration: Create a
.envfile in the root directory and populate your Firebase and Gemini API keys. -
Install Frontend Dependencies:
npm install
-
Run the Vite Local Server:
npm run dev
Open
http://localhost:5173to launch the platform.
barangay-bond/
βββ contracts/ # Soroban Smart Contract source code (Rust)
β βββ contracts/barangay-bond/src/lib.rs
βββ docs/ # Project Documentation assets
β βββ screenshots/ # UI Polished Screens (27 high-res captures)
β βββ README-assets/ # Architecture Diagrams
βββ src/ # React Frontend Core
β βββ components/ # Reusable UI Panels, Modals, and Widgets
β βββ configuration/ # Stellar network & contract configurations
β βββ contexts/ # Auth, Wallet, and Theme state providers
β βββ events/ # Stellar RPC event polling listeners
β βββ hooks/ # Contract state and telemetry hooks
β βββ repositories/ # Firestore data repositories
β βββ rpc/ # Horizon transaction simulation client
β βββ services/ # Gemini AI & Firebase service integrations
β βββ transactions/ # Stellar keypair submit handlers
β βββ utils/ # Currency formatting, PDF generator, and QR tools
β βββ views/ # Main Landing, Auth, and Dashboard layouts
β βββ types/ # TypeScript interface specifications
βββ firestore.rules # Granular database security rules
- Phase 1: Foundation & Civic Identity β In-App Civic Keypairs, role access control, and PSGC boundaries.
- Phase 2: Multi-Phase Soroban Escrow β Rust WASM contract with multi-tranche milestone payouts and conflict-of-interest guards.
- Phase 3: Google Gemini 2.5 AI Telemetry β Proposal scope/DTI pricing audits and visual document OCR verification.
- Phase 4: Statutory Legal Compliance β Automated cryptographic e-OR PDF generation under R.A. 8792.
- Phase 5: High-End UI Modernization β Luxury landing page, 3D holographic vault HUD, protocol simulator, and mobile-optimized resident dashboard.
- Phase 6: Multi-Barangay Scale β Cross-boundary federation for city and municipal federations.
- License: Distributed under the MIT License. See LICENSE for more details.
- Authors: Built with π by FWDP / Barangay Bond Development Team.





















