Foundation — Verified Human Governance on Solana

A decentralized governance platform that answers "who is a real human?" before "what do they want?". Foundation combines passport-backed Proof-of-Humanity, anonymous Semaphore voting, and on-chain Solana auditability. It's the first of three pillars in the PlantagoAI ecosystem — Your Voice (governance), Your Share (UBI distribution), Your Market (collective commerce) — all riding the same identity and voting rails.

Status: working prototype on Solana devnet.

• Live app: https://foundation-global.com
• Docs: https://docs.foundation-global.com
• Partners: https://partners.foundation-global.com (invite-only review surface)

Table of contents

• Architecture
• Directory layout
• Shared @plantagoai/* packages
• Cloud Functions surface
• Local development
• Testing
• Deployment
• Security posture
• Docs map
• License

Architecture

┌──────────────────────────────────────────────────────────────┐
│  React + TypeScript + Vite          — evoting-frontend/      │
│  Firebase Auth (email-link invite-only)                      │
│  Firestore reads (tenant-scoped helpers)                     │
│  httpsCallable → Cloud Functions (App Check enforced)        │
└──────────────────────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│  Firebase Cloud Functions (Node 22, ESM) — functions/        │
│  25 callables + 9 triggers, App Check helper applied         │
│  Braintree payments · Claude AI w/ prompt caching · Resend   │
│  Semaphore group management · Self Protocol ZK verifier      │
└──────────────────────────────────────────────────────────────┘
               │                               │
               ▼                               ▼
┌────────────────────────────┐    ┌────────────────────────────┐
│  Firestore + RTDB          │    │  Anchor program (Rust)     │
│  Tenant-isolated           │    │  evoting-backend/programs  │
│  Firestore rules (locked)  │    │  Deployed to Solana devnet │
└────────────────────────────┘    └────────────────────────────┘

Phase 4/5 cutover (2026-04-19): the prior REST gateway tier was retired. Writes now go through httpsCallable onto Cloud Functions; reads are Firestore-direct via helpers from @plantagoai/firebase-core. The on-chain Anchor program lives in evoting-backend/programs/fresh-evoting/. Retired code lives under archive/rocket-retirement-2026-04-19/.

Directory layout

evoting-frontend/        React + Vite frontend (the app users see)
  e2e/                   Playwright E2E specs
evoting-backend/         Anchor on-chain program — no server here
  programs/fresh-evoting/  Rust source for the deployed Solana program
functions/               Firebase Cloud Functions — the backend
  index.js               25 callables + 9 triggers
  account-deletion.js    GDPR delete/export/request/cancel
  legal.js               Privacy policy, ToS, consent
  admin-status.js        Admin-ring diagnostic endpoint
  idl/                   Synced from evoting-backend/target/idl/
  lib/solana.js          Anchor TS client used by write Functions
  lib/user-wallet.js     Per-user keypair custody (KMS envelope encryption)
  lib/app-check.js       callable() helper — wraps every Function with App Check
docs/                    Architecture, phase plans, security reviews, grant apps
docs-site/               Static HTML docs builder (marked → HTML)
yc-site/                 React SPA for the partners review surface
                         (partners.foundation-global.com — historical name)
scripts/                 Deploy, IDL sync, bootstrap
  deploy-functions.sh    Cloud Functions deploy (bundles @plantagoai/* pkgs)
  sync-idl.sh            Copies Anchor IDL into functions/idl/
  seed-admin-invite.mjs  One-shot bootstrap for the invite flow
  deploy-programs.sh     Anchor program deploy (Solana devnet)
  install-toolchain.sh   Rust + Solana + Anchor toolchain installer
tools/                   Admin/dev tooling (vote simulation, etc.)
archive/                 Historical code — see rocket-retirement-2026-04-19/README.md

Shared @plantagoai/* packages

All 12 live under /Users/dagan/dev/shared/packages/. Prefer them over raw SDK calls — check docs/packages-overview.md and docs/pkg-*.md for APIs.

Import pattern (Cloud Functions / frontend):

"@plantagoai/auth": "file:../../shared/packages/auth"

Cloud Functions surface

25 httpsCallable callables + 9 triggers / onRequest endpoints, all wrapped by functions/lib/app-check.js::callable() which enforces App Check when ENFORCE_APP_CHECK=true. Grouped by domain:

Governance (Solana write path)

• createVoterAccount · createProposal · castVote · submitSupport
• activateProposal · solanaClientSmokeTest

Proof-of-Humanity

• verifyPassportProof (Self Protocol ZK) · attachSemaphoreCommitment
• rebuildSemaphoreGroups (trigger) · getSemaphoreGroup · verifyAnonymousVote
• approveManualReview · flagUserAbuse · unflagUserAbuse

AI

• evaluateProposal (Claude constitutional review with prompt caching)
• lookupPopulation (AI-assisted population lookup, trigger-driven)

Messaging

• sendMail (trigger) · sendNotification · sendInviteEmail (trigger)

Auth / access

• checkInviteOnSignup (beforeUserCreated trigger)
• approveAccessRequest · rejectAccessRequest · inviteDirect
• setAllowSelfRequest · requestSelfAccess
• adminStatus (onRequest) — admin-ring diagnostic

Legal + GDPR

• getPrivacyPolicy · getTermsOfService · recordTosAcceptance
• checkTosAcceptance · deleteMyAccount · exportMyData
• requestAccountDeletion · cancelAccountDeletion

See functions/index.js, functions/account-deletion.js, functions/legal.js, functions/admin-status.js for implementations.

Local development

Prerequisites

• Node.js 22+ (Cloud Functions runtime)
• Firebase CLI (npm i -g firebase-tools)
• Rust + Anchor CLI 0.31.1 + Solana CLI 1.18.26+ (only if touching the program — see scripts/install-toolchain.sh)

Frontend

cd evoting-frontend
npm install
npm run dev              # http://localhost:5173

Copy .env.example → .env.local and fill in devnet keys + reCAPTCHA site key. The frontend talks to Firestore directly and invokes Cloud Functions via httpsCallable — no intermediate API server.

Cloud Functions emulator

cd functions
npm install
npm run serve            # Firebase emulator suite

Anchor program

cd evoting-backend
anchor build             # produces target/idl/fresh_evoting.json
../scripts/sync-idl.sh   # copies IDL into functions/idl/

See docs/architecture_backend-consolidation-2026-04-18.md for the full current-state architecture description.

Testing

Deployment

Two Firebase projects: prod (solanavote-devnet) and staging (foundation-staging-69917). Project aliases live in .firebaserc.

Each prod target has a corresponding staging target with the same name suffixed by -foundation-staging-69917.web.app.

# Auto-deploy: every push to main runs .github/workflows/deploy.yml,
# which deploys hosting + functions to STAGING.

# Manual prod deploy: tag a release; the same workflow's deploy-prod
# job handles it (gated by the GitHub `production` environment).
git tag prod-2026-05-05 && git push --tags

# Local equivalents (when CI is unavailable):
./scripts/deploy-staging.sh hosting       # or `functions`, or both
./scripts/deploy-prod.sh hosting          # asks confirmation, requires CI=1 to skip
./scripts/deploy-functions.sh --project staging|prod   # the underlying functions deployer

scripts/deploy-functions.sh handles the @plantagoai/* monorepo bundle step before invoking firebase deploy. See docs/release-process.md for the canonical dev → staging → prod flow, and docs/dev-stage-prod-plan.md for the full design.

After rebuilding the on-chain program:

cd evoting-backend && anchor build
./scripts/sync-idl.sh    # fails loudly if target/idl/fresh_evoting.json is missing

Security posture

April 2026 brought a focused security sprint. See docs/security-hardening-2026-04.md for the full write-up. Highlights:

• App Check enforced on every callable via functions/lib/app-check.js (commit b997a66c, 2026-04-20)
• Governance client writes locked behind Zod schemas + auth (commits 9d8e23ca, 5e4792ab)
• CSP now allows reCAPTCHA Enterprise telemetry in both connect-src and script-src/frame-src (commits 52ee1cb4, a726374f)
• identity_proofs locked to server-only writes; manual-review photos moved from Firestore to Cloud Storage (commits 6a641d82, ed6381bf)
• Threat model + abuse registry shipped as part of PoH Phase 4 (commit 2f5ccd5b)

For the current threat model and remediation backlog see docs/poh-threat-model.md and docs/security-fix-plan-2026-04-20.md.

Docs map

See docs/INDEX.md for a categorized index of every doc. Quick links:

License

See LICENSE.