Firestore Database — Schema & Admin Tools

Complete reference for Foundation's Firestore database: collection schemas, validation rules, referential integrity, admin tools, and data management.

Collection Overview

Collection Schemas

proposals

{
  title: string,                    // required, min 1 char
  description: string,
  status: "round0" | "active" | "passed" | "rejected",
  scope: "city" | "regional" | "national" | "global",  // optional
  pillar: "YourVoice" | "YourShare" | "YourMarket",
  support_count: number,            // integer >= 0
  support_threshold: number,        // integer >= 0
  total_votes: number,              // integer >= 0 — AGGREGATE: actual vote count
  options: [
    {
      id: string,
      label: string,
      votes: number                 // integer >= 0 — AGGREGATE: per-option vote count
    }
  ],
  created_at: string,               // ISO 8601 date
  updated_at: string,               // ISO 8601 date
  tenant_id: string
}

Aggregates verified:

• total_votes must equal count of votes docs where proposal_id == this.id
• options[n].votes must equal count of votes docs where proposal_id == this.id && option_id == options[n].id
• support_count must equal count of supporter_signatures docs where proposal_id == this.id

voters

{
  wallet_address: string,           // required, min 1 char
  status: "active" | "suspended" | "pending",
  is_verified: boolean,
  is_biometric_verified: boolean,
  age: number,                      // integer >= 0, optional
  location: string,                 // optional
  geographic_scope: string,         // optional
  registered_at: string,            // ISO 8601 date
  tenant_id: string
}

votes

{
  proposal_id: string,              // required — REFERENCE → proposals
  option_id: string,                // required — must exist in proposal.options
  anonymous_hash: string,           // required — for duplicate detection
  timestamp: string,                // ISO 8601 date
  tenant_id: string
}

Integrity checks:

• proposal_id must reference an existing proposal
• option_id must exist in the referenced proposal's options array
• No two votes with the same anonymous_hash on the same proposal (duplicate detection)

supporter_signatures

{
  proposal_id: string,              // required — REFERENCE → proposals
  anonymous_hash: string,           // required — for duplicate detection
  timestamp: string,
  tenant_id: string
}

Integrity checks:

• proposal_id must reference an existing proposal
• No duplicate anonymous_hash per proposal

voting_rounds

{
  proposal_id: string,              // REFERENCE → proposals
  round_type: "support" | "voting" | "runoff",
  status: "active" | "completed" | "cancelled",
  started_at: string,
  ended_at: string,                 // optional
  tenant_id: string
}

funds

{
  name: string,
  description: string,
  status: "active" | "paused" | "completed" | "draft",
  categories: [
    { name: string, allocation: number }
  ],
  total_balance: number,            // >= 0
  distributed_amount: number,       // >= 0
  participant_count: number,        // integer >= 0
  location: string,
  tenant_id: string
}

distributions

{
  fundId: string,                   // REFERENCE → funds
  status: "pending" | "processing" | "completed" | "failed",
  amount: number,
  recipient_count: number,
  distributed_at: string,
  tenant_id: string
}

product_requests

{
  title: string,
  description: string,
  status: "open" | "bidding" | "fulfilled" | "cancelled",
  proposalId: string,               // optional — REFERENCE → proposals
  bids: [
    {
      vendorId: string,
      price: number,
      description: string,
      submitted_at: string
    }
  ],
  tenant_id: string
}

savings_summary

Singleton document with ID "current":

{
  total_savings: number,
  total_participants: number,
  average_savings: number,
  last_updated: string
}

identity_proofs

{
  voter_id: string,                 // REFERENCE → voters
  proofType: "self_declared" | "social_vouch" | "biometric" | "government_id" | "manual_review",
  trustTier: "basic" | "standard" | "verified" | "certified",
  status: "pending" | "approved" | "rejected",
  submitted_at: string,
  reviewed_at: string,              // optional
  tenant_id: string
}

Integrity checks:

• voter_id must reference an existing voter
• trustTier must be consistent with proofType (e.g., biometric → verified or certified)

Database Validator

The Database Validator (Admin Panel > Testing tab) runs a 3-phase validation:

Phase 1 — Schema Validation

Checks every document in all 10 collections:

• Required fields present
• Field types match (string, number, boolean, array, map)
• Enum values valid (status, scope, round_type, proofType, trustTier)
• Numeric fields non-negative where required
• Array structures correct (options, categories, bids)
• ISO date format validation

Phase 2 — Referential Integrity

Verifies all foreign-key references:

• votes.proposal_id → existing proposal with valid option_id
• supporter_signatures.proposal_id → existing proposal
• voting_rounds.proposal_id → existing proposal
• distributions.fundId → existing fund
• identity_proofs.voter_id → existing voter
• product_requests.proposalId → existing proposal (when set)

Phase 3 — Aggregate Consistency

Cross-validates computed fields:

• proposal.total_votes vs actual vote count
• proposal.options[x].votes vs per-option vote count
• proposal.support_count vs actual supporter signature count
• Duplicate vote detection (same anonymous_hash on same proposal)
• Duplicate support detection (same anonymous_hash on same proposal)

Results Display

• Expandable per-collection sections
• Color-coded severity: red (errors), amber (warnings), green (passes)
• Document count per collection
• Total error/warning counts

Auto-Fix (via @plantagoai/db)

Available fix operations:

Always run with dryRun: true first to preview changes.

Data Seeding Tools

Seed Demo Data

Populates standard demo dataset:

• 7 community funds (Stockton SEED, Jackson, Denver, Austin, Chicago, Newark, LA)
• 3 distribution history records
• ~50 marketplace products with supplier bids and price comparisons
• Savings summary singleton
• Demo governance proposals

Idempotent — detects existing data and skips.

Population Seeder

Creates demo voters at a specific location:

1. Google Places Autocomplete for location picking
2. Configurable count: 100 to 100,000
3. Auto-inferred geographic scope
4. Realistic data: random wallets, ~85% verification rate, ages 18-80, 6-month registration spread
5. Batch-processes 50 at a time with progress bar

Vote Seeder

Generates votes on active proposals:

1. Filter by pillar (YourVoice / YourShare / YourMarket)
2. Select proposal
3. Configure count: 100 to 100,000
4. Distribution modes:
   • Random — even spread
   • Landslide Approve — ~80% on first option
   • Landslide Reject — ~80% on last option
   • Head to Head — top 2 nearly tied (~48% each)
5. Creates voter records for audit trail
6. Atomic tally updates via increment()

Voting Simulation

Quick mode: 20 random votes distributed across all active proposals.

Reset Tools

All resets require confirmation dialog.

Export

Via @plantagoai/db's exportDb():

• JSON format with optional metadata (_exportedAt, _collectionName)
• Tenant-scoped export option
• Configurable document limit per collection

Security Rules Generation

@plantagoai/db's generateRules() produces Firestore security rules from schema definitions:

• Type validation per field
• Tenant isolation (tenant_id scoping)
• Ring-based access control
• Required field enforcement