Valocracy Platform

PoC for Ipê Village 2026. Rarity Calculator pipeline (5 AI agents + peer review + on-chain mint) extending the existing Ipê Platform.

Status: Sprint 0 — initial scaffold. See docs/roadmap.md for sprint plan.

Spec: valocracy-platform-architecture.html (v0.5) Ground truth: findings-from-xlsx.html

---

Stack

Layer	Pick
Frontend	Next.js 16 · TypeScript · shadcn/ui · Tailwind
Wallet	Privy (reused from Ipê Platform)
Identity	ENS subdomains *.ipecity.eth
Database	Postgres 16 + pgvector (Docker local · Vercel Postgres prod)
ORM	Drizzle
AI	Claude Sonnet 4.6 + Vercel AI SDK
Queue	QStash + Inngest
Storage	IPFS via Pinata
Contracts	Foundry · Solidity 0.8.x · ERC-5114
Chain	Base Sepolia (PoC) → Base mainnet (post-approval)
Indexer	Ponder.sh

---

Repository structure

valocracy-platform/
├── apps/
│   └── web/                 # Next.js app (TODO Sprint 1)
├── contracts/               # Foundry workspace (TODO Sprint 3)
│   └── src/
├── packages/
│   ├── db/                  # Drizzle schema, migrations, seeds (TODO Sprint 0.2)
│   ├── ai/                  # Agent prompts + orchestration (TODO Sprint 2)
│   └── shared/              # Shared types, schemas (Zod), utilities
├── data/                    # Seed data (43 historical contributions from xlsx)
├── scripts/                 # DB init, deploy, migration helpers
├── docker-compose.yml       # Postgres 16 + pgvector local
├── package.json             # pnpm workspaces root
├── pnpm-workspace.yaml
├── turbo.json               # Turborepo task orchestration
├── tsconfig.base.json       # Shared TS config
├── biome.json               # Lint + format
└── .env.example             # Required env vars

---

Prerequisites

Tool	Version	Why
Node.js	20+	Runtime
pnpm	9+	Package manager (workspaces)
Docker	24+	Postgres + pgvector locally
Foundry	latest	Smart contracts (Sprint 3+)
Git	any	VCS

Install pnpm if missing:

npm install -g pnpm@9

Install Foundry (when starting Sprint 3):

curl -L https://foundry.paradigm.xyz | bash
foundryup

---

Initial setup

# 1. Clone (when repo lives on GitHub)
git clone git@github.com:deegalabs/valocracy-platform.git
cd valocracy-platform

# 2. Copy env file
cp .env.example .env
# Edit .env and fill in real keys (Anthropic, Privy, Pinata, RPC)

# 3. Install dependencies
pnpm install

# 4. Start Postgres locally
pnpm db:up

# 5. Verify Postgres is healthy
docker compose ps
# Should show valocracy-postgres as "healthy"

# 6. (Sprint 0.2+) Apply Drizzle migrations
pnpm db:migrate

# 7. (Sprint 0.2+) Seed 43 historical contributions
pnpm db:seed

# 8. (Sprint 1+) Run dev server
pnpm dev

---

Common commands

Database

pnpm db:up              # Start Postgres container
pnpm db:down            # Stop containers
pnpm db:reset           # Drop volume and restart (clean DB)
pnpm db:logs            # Follow Postgres logs
pnpm db:migrate         # Apply Drizzle migrations
pnpm db:seed            # Seed 43 historical contributions
pnpm db:studio          # Open Drizzle Studio (DB UI)

# Optional: pgAdmin web UI on http://localhost:5050
docker compose --profile with-admin up -d

Smart contracts

pnpm contracts:build              # Compile contracts
pnpm contracts:test               # Run Foundry tests
pnpm contracts:deploy:sepolia     # Deploy to Base Sepolia

App

pnpm dev                # Run all apps in dev mode (turbo)
pnpm build              # Build everything
pnpm test               # Run all tests
pnpm typecheck          # Type-check all packages
pnpm lint               # Biome lint
pnpm format             # Biome format

---

Sprint plan (10 weeks to PoC)

Sprint	Duration	Deliverable
0	1 week	Scaffold + decisions ratified — current
1	2 weeks	Onboarding + Submission flow (Privy + chat/form)
2	2 weeks	5 AI agents + peer review (off-chain signatures first)
3	2 weeks	Smart contracts on Base Sepolia (RaritySBT, Treasury, $IPE-test)
4	1 week	Dashboard + Ponder indexer
5	1 week	Migration of 43 historical contributions + property test
6	1 week	Demo ready for Jean (public URL + pre-funded wallets)

After PoC approval (R1–R5): minimal audit → Base mainnet → Bonfire memory → multi-modal.

---

Open decisions (Sprint 0 — Jean review)

Two questions remain open in the spec for Jean to decide:

1. Self-rate flow: mandatory, optional, or absent?
2. Prompt governance: committee composition; long-term DAO transition.

See Decisions section of the architecture doc.

---

License

Private repository. UNLICENSED until project goes public.

---

Team

• DeegaLabs — engineering (Daniel Gorgonha + Dayane Gorgonha)
• Peerbase / Ipê — product owner (Jean Hansen)
• Methodology — Anna Bida (original Rarity Calculator design, 2025)