UrbanDAO is a blockchain-powered smart-city management platform built as an Angular PWA with a gasless, role-based decentralized governance system. The project combines on-chain transparency, operational efficiency, and frictionless user experience to coordinate every aspect of municipal interaction—from citizen grievances and taxation to project funding and feedback—through a multi-level DAO fueled by Ethereum (Sepolia, Polygon mainnet soon) and a robust Hardhat development environment.

• Overview
• Key Features
• System Architecture
• Roles & Permissions
• Core Smart Contracts
• Workflow Lifecycles
• Gasless Meta-Transactions
• Security Practices
• Tech Stack & Setup
• UI/UX Guidelines
• Contributing
• License

UrbanDAO is designed as an operating layer for smart cities, modernizing traditional grievance and tax management into an on-chain, trustless, and democratic system. Every major civic process is coordinated through carefully tiered roles in a DAO, ensuring accountability, efficiency, and accessibility with gasless transactions.

UrbanDAO’s entire governance, project management, and transaction lifecycles are enforced by smart contracts and powered by ERC-20 and NFT incentives. The project demonstrates advanced mastery of Solidity, DAO patterns, meta-transaction relayer systems, and seamless UI engineering.

• Frontend: Angular PWA, mobile-first, optimal responsiveness, no sidebar, smooth navigation.
• Blockchain Layer: Solidity smart contracts, Hardhat environment (v2.16.0+), deployed on Ethereum Sepolia testnet (Polygon and other L1/L2s planned), all contracts designed for upgradeability (UUPS).
• Interaction Layer: Ethers.js v6.15.0+, ERC-2771 meta-transactions using OpenGSN/Biconomy for gasless calls.
• Storage Layer: Event logs on-chain, text bodies/proofs on IPFS via Pinata.
• Access Control: Each role mapped to one EOA; OpenZeppelin’s AccessControl keeps admin hierarchy enforceable.
• Relayer Module: Trusted "Tx Payer" account for all contract gas.

Note: Each role = one address, except Citizen: multiple citizens per city/district. See roles.png for a diagram.

• Enforced by OpenZeppelin AccessControl (on contract level).
• Each role’s admin is its immediate superior.
• All addresses can be changed/rotated only by their respective admins.

• Use of mappings (vs arrays) for O(1) lookups.
• Packed enums for status (vs strings).
• All event logs (no large text) on-chain; heavy data stored on IPFS.
• Upgradable (UUPS) proxies throughout.

1. Register on UI with KYC details (IPFS hash upload).
2. Validator checks documents and approves/rejects.
3. UrbanToken mints minimal reward for every new successful onboard.

1. TaxCollector assigns annual tax post KYC (per address/user).
2. Citizen pays using payTax() (meta-tx, so no gas paid directly).
3. Receipt minted as ERC-721 SBT; proves tax paid (required for DAO votes).

1. Citizen files up to 3 grievances/month.
2. Validator reviews for spam/abuse.
3. adminHead adjudicates, may open new project if valid.
4. Project proposal is open for quadratic vote.
5. If passed, ProjectManager handles execution and fund tranches released on milestone proofs.

• Citizens can send feedback after resolution.
• Unresolved status = grievance reopens; three reopens auto-escalate to adminGovt.

• Meta-tx Framework: ERC-2771 (OpenGSN/Biconomy) for relayed, gasless txs.
• Contract Engineering: Inherit ERC2771Context, override _msgSender() for identity recovery.
• Security: Nonce mapping to prevent replay, trusted forwarder address timelocked, permissioned.

Relayer Workflow:

1. Citizen signs tx offline.
2. Tx Payer (forwarder/relayer) pays gas, forwards tx to contracts.
3. Contract authenticates sender and processes.
4. Fees reclaimed/reimbursed via stablecoin from treasury.

• Hierarchical Role Control: Tiered getRoleAdmin() prevents privilege escalation.
• Timelock: All treasury transfers have a 24-hour delay.
• Reentrancy Guards: All sensitive functions (payTax, milestone withdrawal) protected.
• Oracle Integration: Milestone claims use Chainlink proofs if required.
• Gas Relayer Hardening: Nonce + signature checks for anti-replay; relayer address changes require DAO vote.

• Solidity: ^0.8.22
• Hardhat: ^2.16.0
• ethers.js: ^6.15.0
• OpenZeppelin Contracts: AccessControl, ERC-20, ERC-721, UUPS proxies, ERC-2771Context
• Pinata/IPFS: Citizen data, project docs off-chain (see PinataAPI-KEYS.txt)

• Angular PWA: Mobile-first, responsive PWA (no sidebar, all rounded corners).
• Theming: Primary color is linear-gradient(135deg, #a259d9, #5e239d), with dark background.

# Clone the repo
git clone https://github.com/yourusername/UrbanDAO.git
cd UrbanDAO

# Install dependencies
npm install

# Start the Angular App (with proxy if needed)
ng serve --open

# For contracts, enter /contracts and run Hardhat locally:
cd contracts
npm install
npx hardhat compile
npx hardhat test
npx hardhat node

First-Time Setup:

• Populate .env files for Angular and Hardhat.
• Place PinataAPI-KEYS.txt for IPFS key provisioning.

• Index / Home
• Login
• Register
• Registration Status

• Citizens:

  • Dashboard
  • File/check grievances, view project status, KYC/tax module

• Validator:

  • Dashboard
  • Approve citizens, filter grievances, validate feedback

• Tax Collector:

  • Dashboard
  • Assign/read taxes, issue receipts

• Project Manager:

  • Dashboard
  • Project milestones, fund requests

• adminHead:

  • Dashboard
  • Appoint roles, accept/reject grievances, curate projects

• adminGovt:

  • Dashboard
  • Manage zones, funds, all project/tax/citizen records

• Tx Payer & Owner:

  • No UI (fully backend/blockchain roles)

1. Fork the repo; create your branch (git checkout -b my-feature).
2. Commit changes with clear messages.
3. Submit a PR and describe what your changes add/improve.

Please follow Conventional Commits for all commit messages.

UrbanDAO is released under the MIT License.

UrbanDAO brings transparency, efficiency, and inclusivity to smart-city governance—by the people, for the people, on-chain.