Platform Features

Foundation includes three major platform capabilities beyond the core identity and voting system.

1. Admin Testing Panel

An interactive developer tool for exercising all 25 Cloud Function callables plus Firestore inspection.

Capabilities

• Callable browser: Browse callables grouped by domain (Governance, PoH, AI, Messaging, Auth, Legal). Each shows expected payload shape, auth requirements, and return type.
• Request builder: Invoke any callable with a custom JSON payload, view formatted response with timing.
• Firestore stats: Live counts of each collection, document sampling, schema-validator integration via @plantagoai/db.
• Seed runners: Demo data seeders and reset flows for dev/test populations.

Access

Admin Panel → Testing tab (requires ring ≤ 1).

Tech Stack

• React components with recharts for visualization
• Firebase httpsCallable client, App Check attached automatically
• Request timing and status tracking

2. Governance State Machine (XState v5)

Replaces hardcoded proposal lifecycle logic with per-proposal XState v5 state machines. Communities can customize governance flows.

State Flow

Round 0 (gathering support)
  → SUPPORT events increment supportCount
  → SUPPORT_THRESHOLD_MET triggers transition to Active

Active (voting open)
  → VOTING_ENDED triggers transition based on results
  → ADMIN_DISCARD transitions to Discarded

Terminal states: Passed, Rejected, Discarded, Closed

Architecture

• proposalMachine.ts: Core XState v5 machine definition with states, events, guards, and actions
• machineFactory.ts: Factory function createGovernanceMachine(config) builds community-customizable machines
• machinePersistence.ts: Firestore persistence using getPersistedSnapshot() / createActor({ snapshot })
• useProposalMachine.ts: React hook providing { state, send, canSupport, canVote, timeRemaining }

Community Configuration

Each community can define:

• Number and type of rounds
• Support thresholds per round
• Voting durations
• Custom guard conditions

Default configuration produces the standard Round 0 → Active → Result flow.

3. AI Constitutional Review

Communities define constitutional principles. Proposals are evaluated by Claude AI against those principles before submission.

Design Principles

• Advisory, not censorship: AI flags concerns but never blocks submission
• Transparency: AI reasoning is visible to all community members
• Community-defined: Each community writes its own constitution
• Appeals via democracy: Flagged proposals can still gain support and pass

Constitution Structure

• Preamble: Community mission statement
• Principles: Each has a title, description, category, and weight
  • Categories: rights, governance, ethics, procedural
  • Weights: core, important, advisory
• 12 default principles provided as a starting template

AI Evaluation

• Powered by Claude (claude-sonnet-4-20250514) via Firebase Cloud Functions
• Returns: overall score (0-100), status (compliant/concern/violation), list of violations with severity and suggested edits
• Results cached by proposal text hash
• Evaluation displayed in proposal submission flow and proposal detail view
• Warning badges shown on proposal cards for flagged proposals

Admin

Navigate to /admin/constitution to manage community principles.

Tech Stack

• Anthropic Claude API (@anthropic-ai/sdk)
• Firebase Cloud Functions v2 (onCall)
• Firestore for constitution storage
• React components for evaluation display