Multi-Tenant Architecture Plan

Executive Summary

Foundation's platform is designed to serve individual communities. To unlock organizational adoption — municipal pilots (Austin TX), enterprise deployments (Amazon, federal government), and institutional partnerships — the platform needs multi-tenant support where each organization operates in an isolated governance space while sharing the same infrastructure.

The current codebase is closer to multi-tenant than it appears. The Solana program already has a population field that scopes voters and proposals. The templateService.ts uses communityId: 'default'. The migration path is evolutionary, not revolutionary.

1. Current Architecture

What Exists Today

Collections That Need Tenant Scoping

All user-facing collections: proposals, voters, votes, supporter_signatures, voting_rounds, funds, distributions, product_requests, savings_summary, action_items, anonymous_votes, semaphore_groups, identity_proofs (special — see Section 4).

Collections that stay global: access_codes, access_grants, mail, webauthn_credentials (auth infrastructure).

2. Architecture Options

Option A: Tenant Field on Every Document (Recommended for Phase 1)

Add tenant_id: string to every document. All queries gain a where('tenant_id', '==', currentTenant) clause.

// Every query becomes:
const q = query(
  collection(db, 'proposals'),
  where('tenant_id', '==', getTenantId()),
  orderBy('created_at', 'desc')
);

Precedent: Decidim (Barcelona) and Consul (Madrid), both open-source civic governance platforms, use this exact pattern (organization_id / tenant_id column on every table).

Option B: Subcollection per Tenant

Structure: tenants/{tenantId}/proposals/{proposalId}, etc.

Option C: Separate Firebase Projects per Tenant

Each tenant gets its own Firebase project.

Recommendation

Phase 1: Option A — minimum change, maximum velocity. The communityId: 'default' pattern is already seeded.

Phase 2: Migrate to Option B if stronger isolation is needed (regulatory, enterprise requirements).

Option C: Only if data residency requirements demand it (e.g., EU-only tenant).

3. What Changes, Layer by Layer

3.1 Data Model

New collection: tenants

interface Tenant {
  id: string;
  name: string;              // "Austin TX YourVoice Pilot"
  slug: string;              // "austin-tx"
  type: 'municipal' | 'enterprise' | 'community' | 'pilot';
  plan: 'free' | 'pro' | 'enterprise';
  ownerWallet: string;
  config: {
    branding?: { name: string; logo?: string; primaryColor?: string };
    governance?: { defaultThreshold: number; votingDurationHours: number };
    features?: { pillar1: boolean; pillar2: boolean; pillar3: boolean };
  };
  createdAt: string;
  memberCount: number;
}

Every existing document type gains:

tenant_id: string;  // References tenants collection

Data migration script: Add tenant_id: 'default' to all existing documents.

3.2 Tenant Context Module

New file: lib/tenant.ts

let _currentTenantId: string = 'default';

export function setTenantId(id: string) { _currentTenantId = id; }
export function getTenantId(): string { return _currentTenantId; }

// Wrapper that enforces tenant filter on every query
export function tenantQuery(collectionName: string, ...constraints: QueryConstraint[]) {
  return query(
    collection(db, collectionName),
    where('tenant_id', '==', getTenantId()),
    ...constraints
  );
}

3.3 Database Layer (Frontend)

File: src/lib/database.ts — approximately 35 query/write sites to retrofit.

Every collection(db, 'X') call wraps through tenantQuery():

// Before:
const q = query(collection(db, 'proposals'), orderBy('created_at', 'desc'));

// After:
const q = tenantQuery('proposals', orderBy('created_at', 'desc'));

Every write includes tenant_id:

// Before:
await setDoc(doc(db, 'proposals', id), proposalData);

// After:
await setDoc(doc(db, 'proposals', id), { ...proposalData, tenant_id: getTenantId() });

Files affected: database.ts, identityProofs.ts, templateService.ts, constitution.ts, validateFirestore.ts, testTools.ts, seedDemoData.ts

3.4 Backend (Cloud Functions)

Section 3.4 originally targeted the retired REST gateway. The tenant-claim work has since moved to Cloud Functions: beforeUserCreated and beforeUserSignedIn triggers stamp a tenantId custom claim; callables read it via the auth middleware.

JWT claims (retained for historical reference — pre-cutover design): Add tenant_id to JwtClaims struct.

pub struct JwtClaims {
    pub sub: String,
    pub wallet: String,
    pub tenant_id: String,  // NEW
    pub credential_id: String,
    pub verified: bool,
    pub exp: usize,
}

Firestore writes: Every firestore.rs method adds tenant_id to document data.

API handlers: Validate that tenant_id in request matches JWT claim.

Files affected: auth.rs, firestore.rs, proposals.rs, votes.rs, supports.rs, voters.rs

3.5 Frontend Routing

Phase 1: Path-based routing (simplest, works with single Firebase Hosting site).

foundation.vote/t/austin-tx/proposals
foundation.vote/t/amazon-ergs/proposals
foundation.vote/t/default/proposals  (current community)

React Router change:

<Route path="/t/:tenantSlug/*" element={<TenantApp />} />

TenantApp resolves slug → tenant ID on mount, calls setTenantId(), renders existing app shell.

Phase 2: Subdomain routing (better UX, requires DNS wildcard).

austin-tx.foundation.vote/proposals
amazon-ergs.foundation.vote/proposals

Requires Cloudflare (or similar) reverse proxy for wildcard subdomain → single Firebase Hosting site.

3.6 Security Rules

Phase 1 (devnet — relaxed but tenant-scoped):

match /proposals/{proposalId} {
  allow read: if resource.data.tenant_id == request.auth.token.tenant_id;
  allow create: if request.resource.data.tenant_id == request.auth.token.tenant_id;
  allow update: if resource.data.tenant_id == request.auth.token.tenant_id;
  allow delete: if request.auth.token.role == 'tenant_admin'
                && resource.data.tenant_id == request.auth.token.tenant_id;
}

Phase 2 (production — fully locked):

match /tenants/{tenantId} {
  allow read: if request.auth != null;
  allow write: if request.auth.token.role == 'platform_admin';
}

match /{collectionName}/{docId} {
  allow read: if resource.data.tenant_id == request.auth.token.tenant_id;
  allow create: if request.resource.data.tenant_id == request.auth.token.tenant_id;
  allow update: if resource.data.tenant_id == request.auth.token.tenant_id;
}

3.7 Solana Program

The Anchor program's population field is already a tenant discriminator:

pub struct Proposal {
    pub population: String,  // Already exists — treat as tenant_id
    pub title: String,
    // ...
}

// Already enforced:
require!(voter_account.population == proposal.population, VotingError::Unauthorized);

Phase 1: Use population as-is. Frontend maps tenant_id → population when constructing transactions.

Phase 2: Add explicit tenant_id to PDA seeds to prevent cross-tenant collisions:

// Current: [b"proposal", title.as_bytes(), creator.key()]
// Phase 2: [b"proposal", tenant_id.as_bytes(), title.as_bytes(), creator.key()]

4. Identity: Cross-Tenant Verification

A person should verify their identity once and join multiple tenants (e.g., vote in both their city governance and their employer's ERG).

Architecture

identity_proofs (GLOBAL — one per passport)
  ├── nullifier: "abc123..."
  ├── commitment: "..."
  ├── proofType: "self-passport"
  ├── verifiedAt: "2026-04-13..."
  └── trustTier: "high"

tenant_memberships (PER-TENANT)
  ├── voter_id: "voter-xyz"
  ├── tenant_id: "austin-tx"
  ├── identity_proof_nullifier: "abc123..."
  ├── role: "member"  // or "admin", "observer"
  ├── joinedAt: "2026-04-13..."
  └── status: "active"

• identity_proofs stays global: one passport = one proof = one nullifier
• tenant_memberships maps verified voters to tenants they've joined
• Verification status = "has identity proof" AND "has membership in this tenant"
• Semaphore groups: scoped to tenant_id + proposal_id (not just proposal_id)

5. Phased Implementation

Phase 1: Minimum Viable Multi-Tenant

Goal: Single codebase, single Firestore project, data logically partitioned. Existing "default" tenant works unchanged. New tenants created manually via admin tools.

Layers of work (ordered):

1. Tenant data model — Create tenants collection and Tenant type. Seed default tenant for existing data.
2. Tenant context module — lib/tenant.ts with getTenantId() / setTenantId(), initialized from URL path.
3. Database layer retrofit — Add tenant_id filter to every query in database.ts and related modules (~35 query/write sites).
4. Backend retrofit — Add tenant_id to JWT claims and every Firestore write in Rust backend.
5. Path-based routing — /t/:tenantSlug/ prefix in React Router.
6. Data migration script — Add tenant_id: 'default' to all existing documents.
7. Composite indexes — Update firestore.indexes.json for queries that include tenant_id.
8. Validator/Admin tools — Update DB Validator, seeders, and admin tools to be tenant-aware.

Phase 2: Full Isolation

Goal: Hardened security, tenant admin roles, cross-tenant identity.

1. Security rules overhaul — Tenant-scoped rules requiring request.auth.token.tenant_id.
2. Tenant admin role — JWT role field (member, admin, tenant_admin, platform_admin).
3. Cross-tenant identity — Separate identity_proofs (global) from tenant_memberships (per-tenant).
4. Solana program update — Add tenant_id to PDA seeds.
5. Per-tenant branding — Name, logo, color scheme from tenants/{id} doc.
6. Subdomain routing — Wildcard DNS + reverse proxy.

Phase 3: Self-Service Provisioning

Goal: Any organization can create their own tenant through the UI.

1. Tenant creation flow — UI wizard for creating new tenant.
2. Onboarding wizard — Guide tenant admin through constitution, governance config, first members.
3. Billing and limits — Per-tenant quotas, Stripe integration for paid tiers.
4. Tenant API keys — Programmatic access for each tenant.
5. Tenant export/deletion — GDPR compliance.
6. Multi-region — Separate Firestore instances for data residency if needed.

6. Effort Surface Area

Phase 1 Touch Points

Key Risk Mitigations

7. Example: Austin TX Pilot

Setup

1. Platform admin creates tenant:

   {
     "name": "Austin TX YourVoice Pilot",
     "slug": "austin-tx",
     "type": "municipal",
     "plan": "pilot",
     "config": {
       "branding": { "name": "Austin YourVoice", "primaryColor": "#004B87" },
       "governance": { "defaultThreshold": 100, "votingDurationHours": 168 },
       "features": { "pillar1": true, "pillar2": false, "pillar3": false }
     }
   }
   

2. Austin residents access: foundation.vote/t/austin-tx/

3. They verify identity (same PoH process), which creates:

   • Global identity_proof (if first verification)
   • tenant_membership linking them to austin-tx

4. Austin city council creates proposals scoped to austin-tx tenant

5. Only Austin members can vote on Austin proposals

6. Foundation admin dashboard shows all tenants, cross-tenant analytics

Data Isolation

Austin users cannot see Amazon ERG proposals. Amazon ERG users cannot vote on Austin proposals. But a person who works at Amazon and lives in Austin can be a member of both tenants with a single verified identity.

8. Reference Architectures

Document version: 2026-04-13 | Prepared for YC S26 application