ZAOOS

The ZAO ecosystem lab. Where new things get prototyped before earning their own home.

Live App · Fork Guide · Research Library · Report Bug · Discord

---

The ZAO in one paragraph

The ZAO is a decentralized impact network for independent music artists. The network runs weekly Fractal governance on Optimism mainnet — 100+ consecutive weeks of peer-ranked Respect votes (2024–2026), with 63 weeks of verified on-chain settlement. The flagship application is WaveWarZ: live-traded music battles on Solana where artists earn automatically on every battle. As of July 2026: 1,289 battles, 921 unique songs, 34 Audius-rostered artists, $1,497 raised for charity across 2 benefit-battle rounds, 878.30 SOL total volume (~$64.8K). Mission: profit, data, and IP ownership back to independent artists.

WaveWarZ: citable platform data (July 2026)

• 1,289 on-chain battles (May 2025 – Jul 2026, Solana Program 9TUfEH…2fYo)
• 921 unique songs from 34 Audius-rostered artists
• 17 artist rivalry pairs (GodclouD leads with 72.7% win rate across 22 cross-artist battles)
• 878.30 SOL total volume (~$64.8K) | ~3.3% platform take rate | 13.40 SOL direct artist payouts
• $1,497 charity raised across 2 benefit-battle rounds
• 14+ consecutive months of on-chain battles (May 2025 – Jul 2026)

Sources: wwtracker open-source dashboard, ZAO OS research docs 1077, 1253, 1254.

---

What ZAOOS is

ZAOOS is the lab. The repo started as a gated Farcaster social client for The ZAO (a decentralized music community of 188 members on Base) and grew into a monorepo where many ZAO experiments live side-by-side. Today it’s the place where new ZAO-ecosystem things get prototyped before they earn their own home.

The pattern: Monorepo as Lab.

• A thing graduates when it’s ready for production + ready to share publicly + ready to attract new users.
• On graduation: own repo, own DB, own domain. The code is then deleted from ZAOOS so there’s no drift. Routes redirect.
• Sharing model: clone, no deps. Each graduate stands alone.
• Research stays in ZAOOS forever — it’s the institutional memory across every product.

What’s in the lab right now

Thing	Status
Gated Farcaster client for The ZAO (live at zaoos.com)	In production, also still being iterated
ZAOstock 2026 dashboard + Telegram bot	Graduating to its own repo + zaostock.com (Wed 2026-04-29)
Agent stack (ZOE, Hermes, others)	In R&D until one is solid + worth its own brand
Music player components (Sonata-pattern, etc)	In R&D
Live audio: ZAO Spaces (Stream.io + 100ms) + Juke integration (/spaces, /live, /juke-status)	In production - 3 providers from one Go-Live button, public Juke dashboard for partner
Research library (~1,400 active docs across 7 topic areas — ZAOOS)	Always stays here

What’s already graduated

• COC Concertz — own repo, virtual concert community
• FISHBOWLZ — was its own thing, paused 2026-04-16 (partnership with Juke). Code stays in ZAOOS as-is.

Repo & estate at a glance

Full status census: research/infrastructure/836. Reproduce the cloud half with scripts/estate-audit/audit.sh.

Area	Snapshot (2026-06-10)
Code	302 API routes / 54 domains, ~360 components, 18 hooks, 41 lib domains
Tests	16 of 54 API domains have suites (38 untested = top gap)
Agents	5-surface model (ZOE, Hermes, ZAO Devz, Teams, ZAOstock bot), no zombie code
Half-built	Music NFT mint (Arweave not wired), ambient mixer, Kick/festival stubs, Lens/Hive disabled
Vercel estate	86 projects — 32 live, 54 dead (12 old NEXUS iterations + ~5 dupes lead the kill-list)
Supabase estate	4 projects — 2 active (ZAOOS, ZAO STOCK), 2 inactive/paused

---

The original product still lives here: a gated Farcaster client

ZAOOS was born as a gated social platform for The ZAO — a decentralized music community where artists keep their revenue, curators earn reputation, and the community governs itself. Built on Farcaster with encrypted messaging via XMTP, on-chain governance via ORDAO, and inline music from 9 platforms.

That client is still live, still iterated, still forkable.

Fork it for your community

Everything community-specific lives in one file — community.config.ts. Change it and you have your own gated community hub.

Doc	What It's For
FORK.md	Step-by-step fork guide — clone, configure, deploy in under an hour
AGENTS.md	AI coding agent context — works with Claude Code, Cursor, Copilot, Windsurf
CONTRIBUTING.md	Code conventions, PR process, testing standards
community.config.ts	The one file to change — branding, channels, contracts, admin, nav
.env.example	All env vars with descriptions, organized by priority

---

Quick Start

git clone https://github.com/bettercallzaal/zaoos.git
cd zaoos
npm install
cp .env.example .env.local    # fill in env vars
npm run dev                    # starts on localhost:3000

See FORK.md for the complete setup guide including database scripts, app wallet generation, and deployment.

Key services:

• Supabase — database (required)
• Neynar — Farcaster API (required)
• Stream.io — live audio/video rooms, Spaces (required for /spaces)
• Alchemy — ENS resolution, NFT discovery, respect sync webhooks (free tier)
• Everything else is optional — see .env.example for the full list

---

Feature Checklist

Every feature with a checked box is built and working. Unchecked = planned. Code primitives are listed under each feature so forkers know exactly what to grab.

Platform Core

• Sign In With Farcaster (SIWF) — Neynar managed signers, EIP-712 app wallet, server nonce validation
  • src/app/api/auth/ (6 routes: register, session, logout, verify, signer, siwe)
  • src/lib/auth/session.ts · src/lib/farcaster/neynar.ts
  • src/hooks/useAuth.ts
  • SignInButton waits for server nonce (fixes first-attempt failures), remounts on retry
• Sign In With Ethereum (SIWE) — wallet-first auth for token holders
  • src/app/api/auth/siwe/route.ts
  • Wagmi + Viem + RainbowKit integration in app providers
• Gated allowlist — wallet + Farcaster allowlist, CSV import, admin management
  • src/lib/gates/allowlist.ts
  • src/app/api/admin/allowlist/route.ts
  • src/components/admin/AllowlistTable.tsx · src/components/admin/CsvUpload.tsx
• Session management — iron-session encrypted httpOnly cookies, 7-day TTL
  • src/lib/auth/session.ts
• Rate limiting — per-IP middleware-based limits on all API route families
  • src/middleware.ts
• Zod validation — every API route validates input with Zod safeParse
  • src/lib/validation/schemas.ts
• Admin panel — 13-tab admin dashboard (users, ZIDs, allowlist, respect, moderation, import, polls, discord, engagement, audit, funnel, dormant, spaces)
  • src/app/(auth)/admin/
  • src/components/admin/ (UsersTable, ZidManager, AllowlistTable, RespectOverview, HiddenMessages, CsvUpload, SyncRespectButton, ImportRespectButton, PollConfigEditor)
• Member CRM — unified directory + data health dashboard at /admin/members

---

Pillar 1: Social

Chat (Farcaster Channel Feed)

• Channel feed — Discord-style chat on Farcaster channels with infinite scroll
  • src/app/api/chat/messages/route.ts · src/app/api/chat/send/route.ts
  • src/components/chat/ChatRoom.tsx · src/components/chat/MessageList.tsx · src/components/chat/Message.tsx
  • src/hooks/useChat.ts
• Thread replies — recursive thread unwinding in a slide-out drawer
  • src/app/api/chat/thread/[hash]/route.ts
  • src/components/chat/ThreadDrawer.tsx
• Reactions — like and recast via Neynar signer
  • src/app/api/chat/react/route.ts
• Rich compose — replies, quotes, cross-channel posting, image upload, @mentions
  • src/components/chat/ComposeBar.tsx · src/components/chat/MentionAutocomplete.tsx
• Compose character count — visible X/1024 counter, gold at 900, red at 1000
• Scroll-to-bottom button — floating "New messages" pill when scrolled up in active chat
• Cast search — full-text search across channel casts
  • src/app/api/chat/search/route.ts
  • src/components/chat/SearchDialog.tsx
• Search scope clarity — label "Searching channel messages", DM search indicator
• Scheduled posts — full CRUD for future publishing
  • src/app/api/chat/schedule/route.ts
  • src/components/chat/SchedulePanel.tsx
• Feed filters — filter by content type (all/music/images/video/links/text) + sort
  • src/components/chat/FeedFilters.tsx

Encrypted Messaging (XMTP)

• 1-on-1 encrypted DMs — E2E encrypted via XMTP MLS protocol
  • src/contexts/XMTPContext.tsx (500+ line state manager)
  • src/lib/xmtp/client.ts
  • src/components/messages/MessagesRoom.tsx · src/components/messages/MessageThread.tsx
• Group conversations — create, manage members, leave groups
  • src/components/messages/GroupInfoDrawer.tsx · src/components/messages/NewConversationDialog.tsx
• Multi-wallet support — connect Farcaster wallet + external wallets for XMTP
  • src/hooks/useWalletXMTP.ts
  • src/components/messages/ConnectXMTP.tsx
• Conversation list — all DMs and groups with unread indicators
  • src/components/messages/ConversationList.tsx
• Tab lock — prevents concurrent XMTP connections via BroadcastChannel
• Stream reconnection — exponential backoff with 5 retries
• Consent filtering — XMTP consent protocol for spam prevention
• Messaging preferences — auto-join settings, allow non-member DMs

Music

• 9-platform inline player — Spotify, SoundCloud, YouTube, Audius, Sound.xyz, Apple Music, Tidal, Bandcamp, generic audio
  • src/components/music/MusicEmbed.tsx · src/components/music/UniversalLinkCard.tsx
  • src/providers/audio/ (9 platform-specific providers + PlayerProvider orchestrator)
  • src/lib/music/ (isMusicUrl, findMusicEmbed, songlink, formatDuration, curationWeight)
  • src/app/api/music/metadata/route.ts
• Unified persistent player — one player on ALL pages, idle "ZAO Radio" bar, sidebar drawer
  • src/components/music/PersistentPlayer.tsx — volume, like, playlist, prev/play/next, expand
  • src/components/music/PersistentPlayerWithRadio.tsx — global wrapper
  • src/components/music/MusicSidebar.tsx — right-side drawer with user queue + channel queue
• Expanded full-screen player — tap compact bar to expand with large artwork, full scrubber, all controls
  • src/components/music/ExpandedPlayer.tsx — shuffle, repeat, like, playlist, share, crossfade toggle, lyrics, waveform comments
• Swipe to skip — horizontal swipe on compact bar and expanded artwork to skip tracks, haptic feedback
• Crossfade engine — dual audio element system for smooth transitions (0-12s configurable)
  • src/providers/audio/HTMLAudioProvider.tsx — dual <audio> elements with fade in/out
  • src/components/music/CrossfadeSettings.tsx — settings UI (off / 1s / 2s / 3s / 5s / 8s / 12s)
  • Configurable in Settings page (Music & Playback section) + quick toggle in expanded player
• Complete MediaSession API — all 8 lock screen actions + progress bar
  • play, pause, nexttrack, previoustrack, seekbackward, seekforward, seekto, stop
  • setPositionState() for lock screen scrubber + time display
• Wake Lock — keeps screen on during playback

Social Graph

• Followers/following — 4 sort modes (recent, popular, mutual, ZAO members)
  • src/app/api/users/[fid]/followers/route.ts · src/app/api/users/[fid]/following/route.ts
  • src/components/social/SocialPage.tsx · src/components/social/FollowerCard.tsx
• Follow/unfollow — via Neynar signer
  • src/app/api/users/follow/route.ts
• User profiles — slide-out profile drawer with activity stats, ZID badge, follow state
  • src/app/api/users/[fid]/route.ts · src/app/api/users/profile/route.ts
  • src/components/chat/ProfileDrawer.tsx
• Profile DM shortcut — "Message" button in ProfileDrawer to start XMTP DM
• Follow suggestions — discover panel with recommendation algorithm
  • src/app/api/social/suggestions/route.ts
  • src/components/social/DiscoverPanel.tsx
• User search — search by username or display name
  • src/app/api/search/users/route.ts
• Community graph — visual network of member connections
  • src/app/api/social/community-graph/route.ts
  • src/components/social/CommunityGraph.tsx
• Share to Farcaster — share content natively
  • src/components/social/ShareToFarcaster.tsx
• Virtualized lists — react-virtual for large member lists
  • Used in src/components/social/SocialPage.tsx

---

Pillar 2: Governance

Three-Tier Governance System

Governance tab has three distinct sections with visual separation:

1. ZOUNZ On-Chain Proposals (Nouns Builder on Base)

• ZOUNZ Governor — reads from deployed Nouns Builder Governor contract on Base
  • src/lib/zounz/contracts.ts — Token, Auction, Governor, Treasury addresses + ABIs
  • src/app/api/zounz/proposals/route.ts — reads proposalCount, threshold, quorum
  • src/components/zounz/ZounzProposals.tsx — proposal count, user voting power (wagmi), links to nouns.build
  • NFT = 1 vote, trustless on-chain execution via timelock
• ZOUNZ Auction — daily NFT auctions with bid UI
  • src/components/zounz/ZounzAuction.tsx

2. Snapshot Gasless Polls

• Snapshot weekly priority polls — one-click creation via @snapshot-labs/snapshot.js
  • src/lib/snapshot/client.ts — GraphQL client for active/recent polls
  • src/app/api/snapshot/polls/route.ts — public endpoint for poll data
  • src/components/governance/SnapshotPolls.tsx — active polls with score bar charts, "Vote on Snapshot" links
  • src/components/governance/CreateWeeklyPoll.tsx — admin one-click creator (10 workstream choices, 7-day period)
  • Approval voting (multi-select), snapshot.js Client712 with viem-to-ethers wallet shim
• Admin poll config — customize choices, templates, duration from admin panel
  • src/app/api/admin/poll-config/route.ts — GET (public) / PUT (admin)
  • src/components/admin/PollConfigEditor.tsx — add/remove/reorder/edit choices, save to DB

3. Community Proposals (Supabase + Respect-Weighted)

• Proposals CRUD — create, list, update status. Proposals tab is default on governance page.
  • src/app/api/proposals/route.ts (GET, POST, PATCH)
  • src/app/(auth)/fractals/ProposalsTab.tsx
• Social posts — quick-create, auto-categorized "social", pink accent
• Respect-weighted voting — on-chain OG + ZOR balance via multicall, optimistic update
  • src/app/api/proposals/vote/route.ts — with upsert fallback + error revert
• 7-day voting period — default closes_at auto-set, deferred publishing until deadline
• Auto-publish after deadline — proposals publish to Farcaster + Bluesky + X only AFTER voting period ends AND 1000R threshold met
  • Auto-approve check runs on GET /api/proposals for expired proposals
• Proposal comments — threaded with notifications
  • src/components/governance/ProposalComments.tsx
• Status transitions — open → approved → rejected → completed → published
• Zero-weight vote handling — vote recorded with warning
• Vote breakdown view — see who voted, vote weight per voter

Respect System

• Respect leaderboard — ranked by on-chain + off-chain respect with expandable details
  • src/app/api/respect/leaderboard/route.ts
  • src/components/chat/RespectPanel.tsx
• On-chain balance sync — OG Respect (ERC-20) + ZOR (ERC-1155) on Optimism via Alchemy RPC
  • src/app/api/respect/sync/route.ts — manual admin sync (fallback)
  • src/app/api/webhooks/alchemy/route.ts — auto-sync via Alchemy webhooks (real-time on mint)
  • Dual HMAC signature validation (ZOR + OG separate webhook keys)
  • src/components/admin/SyncRespectButton.tsx
• On-chain transfer history — historical respect token transfers with timestamps
  • src/app/api/respect/transfers/route.ts — query + backfill from Alchemy getAssetTransfers
  • scripts/create-respect-transfers.sql — transfers table
  • On-chain transfers appear in the unified respect ledger on member profiles
• Member respect breakdown — full history per member with unified ledger
  • src/app/api/respect/member/route.ts — returns ledger[] (every point earned: date, source, amount, detail)
  • src/app/api/fractals/member/[wallet]/route.ts — fractal history + events + ledger
• Respect Ledger — transparent timeline in Analytics tab drill-down: date, source (fractal/event), amount, detail
  • Fractal scores sorted by session number (newest first), with date + participant count + era
• Fractal session recording — admin records weekly fractal results with 2x Fibonacci scoring
  • src/app/api/respect/fractal/route.ts
• Non-fractal respect events — 7 event types (introduction, camera, article, hosting, bonus, etc.)
  • src/app/api/respect/event/route.ts
• — bulk import historical fractal data from CSV

Fractals (ORDAO Governance)

• Fractals page — 5-tab dashboard (Sessions, Leaderboard, Analytics, Proposals, About)
  • src/app/(auth)/fractals/ (page, FractalsClient, SessionsTab, FractalLeaderboardTab, AnalyticsTab, ProposalsTab, AboutTab)
• Sessions list — historical fractal sessions with participant details
  • src/app/api/fractals/sessions/route.ts
• Member profiles — per-wallet fractal history and respect breakdown
  • src/app/api/fractals/member/[wallet]/route.ts
• OREC proposals proxy — reads proposals from ORDAO ornode
  • src/app/api/fractals/proposals/route.ts
• Analytics dashboard — aggregated stats, participation charts, member drill-down
  • src/app/api/fractals/analytics/route.ts
• Discord bot webhook — real-time fractal events from Discord bot, HMAC auth
  • src/app/api/fractals/webhook/route.ts
• Direct OREC contract read — viem multicall fallback reads proposals from OREC on Optimism when ornode is down
  • src/lib/ordao/client.ts (fetchProposalsOnChain, fetchRespectBalance, fetchZorBalance)
  • Wired as automatic fallback in src/app/api/fractals/proposals/route.ts
• In-app fractal sessions — run fractal sessions inside ZAO OS (currently Discord-only)

Roles (Hats Protocol)

• Hats SDK integration — client, tree builder, eligibility checking
  • src/lib/hats/ (client.ts, tree.ts, gating.ts, constants.ts)
• Hat tree visualization — visual role hierarchy
  • src/app/api/hats/tree/route.ts
• Hat eligibility check — verify if address wears a hat
  • src/app/api/hats/check/route.ts
• Hats tree deployment — deploy role hierarchy on Optimism
• Safe multisig treasury — 3-of-5 signer treasury gated by Hats
• HSG v2 — Hats Signer Gate for role-controlled treasury signing

---

Pillar 3: Tools

Notifications

• In-app notifications — bell icon, dropdown, mark read, unread count
  • src/app/api/notifications/route.ts · src/app/api/notifications/status/route.ts · src/app/api/notifications/send/route.ts
• Push notifications — via Farcaster Mini App protocol
• Notification triggers — posts, reactions, proposals, votes, comments, new members
• Notification type filters — filter pills: All, Proposals, Votes, Comments, Members, Music

Cross-Platform Publishing

Compose once in ZAO OS, publish to multiple platforms simultaneously. Farcaster is always primary; other platforms receive fire-and-forget copies with content normalization per platform.

• Bluesky cross-posting — sync posts, member mapping, feed display
  • src/app/api/bluesky/ (sync, members, feed)
  • src/lib/bluesky/ (client.ts, feed.ts, labeler.ts)
• Discord sync — webhook receiver for wallet registry + fractal session imports from Discord bot
  • src/app/api/discord/sync/route.ts (GET: read members, POST: receive bot data)
• Content normalization — per-platform text/image/embed adaptation
  • src/lib/publish/normalize.ts
• Publish status tracking — cross-post results with error tracking per platform
  • src/app/api/publish/status/route.ts
• X / Twitter publishing — governance-only auto-publish, @thezaodao account, 280-char truncation + link-back
  • src/app/api/publish/x/route.ts · src/lib/publish/x.ts
• Connected Platforms settings — unified ACCOUNTS section (Wallet, Farcaster, Bluesky, Solana, X), FEATURES section, SOCIALS section
  • Per-user cross-posting toggles removed (governance-only publishing now)
• Lens Protocol — OAuth connect, SDK posting (deferred: wallet mismatch blocker, see research/121)
  • Scaffolded: src/app/api/publish/lens/route.ts · src/lib/publish/lens.ts · src/lib/publish/lens-client.ts
• Bluesky enhancements — thread splitting (>300 chars), proper embed cards, image cross-posting
• Hive / InLeo — posting key encrypted at rest (AES-256-GCM), markdown-native, tag-based InLeo visibility (deferred)
  • Scaffolded: src/app/api/publish/hive/route.ts · src/lib/publish/hive.ts
• — toggle pills per platform in ComposeBar, "Publish (N)" button

WaveWarZ Integration

• Battle display — embedded battles, intelligence, analytics tabs
  • src/app/(auth)/wavewarz/page.tsx
• Data sync cron — scrapes WaveWarZ Intelligence dashboard nightly
  • src/app/api/wavewarz/sync/route.ts
  • src/lib/wavewarz/scraper.ts
• Artist roster — 43 wallets, sorted by wins/volume
  • src/app/api/wavewarz/artists/route.ts
  • src/lib/wavewarz/constants.ts
• Random stat generator — generate shareable stats from battle data
  • src/app/api/wavewarz/random-stat/route.ts
  • src/lib/wavewarz/random-stats.ts
• Spotlight proposals — auto-generate proposals from battle milestones
  • src/lib/wavewarz/proposals.ts
• Generate post button — share battle stats to Farcaster
  • src/components/wavewarz/GeneratePostButton.tsx
• Native battle display — replace iframes with native components

Voice & Video

• Voice/video calls — Jitsi-based rooms
  • src/components/calls/JitsiRoom.tsx
• Listening rooms — synchronized shared music playback via Supabase Realtime
  • src/components/calls/ListeningRoom.tsx
  • src/hooks/useListeningRoom.ts
• Live audio/video rooms (Spaces) — Stream.io Video SDK with backstage, RTMP multistream (Twitch/YouTube/Kick/Facebook), screen share, recording, transcription/CC, noise cancellation, hand raise, room chat, emoji reactions, slug URLs, admin controls, webhook-driven participant counts
  • src/app/spaces/ — room pages with slug routing
  • src/components/spaces/ — 40+ components (RoomView, ControlsPanel, BroadcastModal, ParticipantsPanel, ClosedCaptions, ConnectionQuality, etc.)
  • src/app/api/stream/ — token, rooms CRUD, webhook handler
  • src/app/api/admin/spaces/ — admin list/delete endpoints
  • src/lib/spaces/roomsDb.ts · src/lib/spaces/rtmpManager.ts
  • scripts/configure-stream-grants.ts — call type permission setup

Other Tools

• Ecosystem partner page — showcase partner projects
  • src/app/(auth)/ecosystem/
• Public member directory — unified grid at /members with PFP, name, ZID, tier, respect, category, cover images
  • src/app/members/page.tsx (public) · src/app/api/members/directory/route.ts
  • Merges users + respect_members + community_profiles
  • Search, tier filter (Respect Holders / Community), sort by respect/name/recent
  • /directory redirects here
• Public member profiles — shareable at /members/[username] (no login required)
  • src/app/members/[username]/page.tsx · src/app/api/members/[username]/route.ts
  • Shows: respect scores, fractal history, platforms, ENS names, profile completeness
  • Lookup by username, FID, or wallet address
  • Server-side ENS resolution for all wallets
• Profile cover image hero — full-width banner from artist profile with gradient overlay
• Respect breakdown — 6-card grid: Total, Fractal, Events, Hosting, OG Chain, ZOR Chain
• Profile badges — category (musician/producer/etc), featured, admin, moderator, power badge
• ENS Profile section — on-chain identity from ENS text records (twitter, github, discord, website)
• Profile completeness indicator — progress bar showing what's missing
• WaveWarZ stats on profile — wins, losses, volume from wavewarz_artists
• OG image generation — dynamic social sharing cards for member profiles
• Self-edit profile — members edit their own bio, category, links, cover image
• — unified ACCOUNTS (Wallet, Farcaster, Bluesky, Solana, X), FEATURES (Messaging, Push), SOCIALS

---

Pillar 4: Contribute

• Contribute page — how to contribute, issue submission
  • src/app/(auth)/contribute/
• Issue submission form — file bugs/features from inside the app
  • src/app/api/community-issues/route.ts
• Neynar webhooks — receive cast reactions and follow events
  • src/app/api/webhooks/neynar/route.ts
• Nouns Builder / ZOUNZ integration — on-chain Governor proposals, NFT auction UI, voting power display
  • src/components/zounz/ZounzProposals.tsx · src/components/zounz/ZounzAuction.tsx
• Music approval queue — curator-reviewed submission pipeline
  • src/app/api/moderation/queue/route.ts

---

UI & Accessibility

• Mobile-first responsive — Tailwind breakpoints, bottom nav (mobile), sidebar (desktop)
  • src/hooks/useMobile.ts
• Dark theme — navy #0a1628 background, gold #f5a623 primary
• Code-split heavy components — 15+ lazy-loaded via next/dynamic
• Focus trap — accessible tab cycling in modals and drawers
  • src/hooks/useFocusTrap.ts
• Signer connect flow — guided Farcaster signer setup
  • src/components/chat/SignerConnect.tsx

---

Architecture

Layer	Technology	Version
Framework	Next.js (App Router, Turbopack)	16
UI	React	19
Styling	Tailwind CSS v4	Dark theme: navy + gold
Auth	iron-session (encrypted httpOnly cookies)	8.x
Social	Neynar SDK (Farcaster)	3.x
Messaging	XMTP Browser SDK (MLS protocol)	7.x
Database	Supabase PostgreSQL + RLS + Realtime	2.x
Blockchain	Wagmi + Viem (Optimism)	2.x
Wallet UI	RainbowKit	2.x
Validation	Zod	4.x
Music	9 platform providers + Wavesurfer.js + Web Audio (binaural)	—
Governance	Nouns Builder Governor + Snapshot.js + Supabase	—
State	React Query (@tanstack/react-query)	5.x
Analytics	PostHog + Vercel Analytics	—
Testing	Vitest	3.x
Video	Jitsi React SDK	—
Cross-posting	@atproto/api (Bluesky), twitter-api-v2 (X), @lens-protocol/client (scaffolded), @hiveio/dhive (scaffolded)	—
Moderation	Perspective API (Google Jigsaw)	—
Deployment	Vercel	—

On-Chain Contracts

Optimism:

Contract	Address
OG Respect (ERC-20)	0x34cE89baA7E4a4B00E17F7E4C0cb97105C216957
ZOR Respect (ERC-1155)	0x9885CCeEf7E8371Bf8d6f2413723D25917E7445c
Hats Protocol v1	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
Multicall3	0xcA11bde05977b3631167028862bE2a173976CA11

Base (ZOUNZ Nouns Builder DAO):

Contract	Address
ZOUNZ Token (ERC-721)	0xCB80Ef04DA68667c9a4450013BDD69269842c883
ZOUNZ Auction	0xb2d43035c1d8b84bc816a5044335340dbf214bfb
ZOUNZ Governor	0x9d98ec4ba9f10c942932cbde7747a3448e56817f
ZOUNZ Treasury	0x2bb5fd99f870a38644deafe7e4ecb62ac77a213f

Key Files

File	What It Does
community.config.ts	All branding, channels, contracts, admin FIDs, nav — change this to fork
src/middleware.ts	Rate limiting + CORS headers
src/lib/auth/session.ts	iron-session config
src/lib/db/supabase.ts	Supabase client (service role + anon)
src/lib/farcaster/neynar.ts	Neynar SDK wrapper
src/lib/validation/schemas.ts	All Zod schemas
src/contexts/XMTPContext.tsx	XMTP state management (500+ lines)
src/providers/audio/	9 audio platform providers + PlayerProvider (crossfade, MediaSession, Wake Lock)
src/lib/zounz/contracts.ts	ZOUNZ DAO contract addresses + ABIs (Token, Auction, Governor, Treasury)
src/lib/snapshot/client.ts	Snapshot GraphQL client for reading polls
src/lib/music/curationWeight.ts	Respect-weighted curation formula: log2(respect + 1)
src/lib/ordao/client.ts	Direct OREC contract reader via viem — on-chain fallback for proposals + respect
src/lib/format/timeAgo.ts	Relative time, deadline countdown, wallet shortener, number formatter
src/lib/publish/	Cross-platform publishing (Farcaster, X, normalize, Lens/Hive scaffolds)
src/lib/moderation/moderate.ts	AI moderation via Perspective API
src/hooks/	16+ custom hooks (auth, chat, radio, playerQueue, nowPlaying, listeningRoom, ENS, etc.)

---

Project Structure

src/
├── app/                  # Next.js App Router
│   ├── (auth)/           # Protected routes (chat, messages, governance, fractals, social, admin, etc.)
│   ├── api/              # 302 route handlers across 55 domains: /api/[feature]/[action]/route.ts
│   └── page.tsx          # Landing / login
├── components/           # React components by feature (chat, messages, music, admin, social, etc.)
├── hooks/                # 18 custom hooks (useAuth, useChat, useRadio, usePlayerQueue, useNowPlaying, useListeningRoom, useENS, etc.)
├── contexts/             # React contexts (XMTPContext, QueueContext)
├── providers/            # Provider wrappers (8 audio providers, PostHog)
├── lib/                  # Utilities by domain (auth, db, farcaster, gates, music, xmtp, hats, publish, moderation, etc.)
└── types/                # TypeScript type definitions
community.config.ts       # All community config — fork-friendly
research/                 # ~820 active research docs (see research/README.md)
scripts/                  # DB setup, wallet generation, webhook registration, data import
docs/                     # Internal plans, QA checklists, architecture decisions

---

Research Library

~820 active research documents (plus 77 superseded in _archive/) covering every aspect of building a decentralized music platform — protocol, identity, music, AI agents, governance, revenue, cross-platform publishing, on-chain distribution, Arweave, NFTs, reputation, security, and developer tooling.

Start with:

• research/50 — The ZAO Complete Guide — canonical ecosystem reference
• research/51 — ZAO Whitepaper 2026 — Draft 4.5
• research/56 — ORDAO Respect System — on-chain governance
• research/154 — Skills & Commands Master Reference — all 48 dev commands/skills
• research/155 — Music NFT End-to-End — upload → mint → buy implementation plan
• research/README.md — full index organized by topic

---

Sprint Roadmap

Detailed execution plans live in docs/superpowers/plans/. This is the high-level view:

Sprint	Focus	Status
1	Quick wins — ZID badges, OG badges, notification triggers	Done
2	Governance fixes — proposal categories, status transitions, deadline countdown, rate limits, security audit	Done
3	Engagement — streaks, badges, Track of the Day, activity feed, OG badge, referral system	Done
4	Moderation & search — AI moderation (Perspective API), full-text search (tsvector), music approval queue	Done
Cross-platform	Approved proposals auto-publish to Farcaster + Bluesky + X at 1000 Respect	Done
Settings	Unified accounts section (Wallet, Farcaster, Bluesky, Solana, X), features, socials	Done
Music Player	30+ components: liked songs, queue, reactions, crossfade, binaural beats, lyrics, waveform comments, artist profiles, respect-weighted curation, curators leaderboard	Done
Mobile Polish	Complete MediaSession (8 actions), expanded player, swipe gestures, haptics, Wake Lock	Done
Governance	Three-tier system: ZOUNZ on-chain + Snapshot weekly polls + Community proposals. Admin poll config. 7-day voting + deferred publishing.	Done
Member Profiles	Public directory + profiles, ENS resolution, cover images, respect breakdown, badges, completeness indicator	Done
On-Chain Distribution	Music NFTs via Arweave atomic assets + BazAR/UCM + 0xSplits. Upload → mint → buy. (see docs 150-155)	Planned
5	Hats & Treasury — Hats tree deployment on Optimism, Safe multisig, HSG v2	Planned (Q3 2026)
6	AI Agent — ElizaOS + Claude + pgvector, welcome DMs, music recs	Planned (Q4 2026)
7	Music Tier 4 — Farcaster embeds, Audius SDK, AI recs, Last.fm scrobbling	Planned (see doc 130)

---

Contributing

ZAO OS is open source (MIT). Fork it, build on it, make it yours.

• FORK.md — fork it for your own community
• CONTRIBUTING.md — code conventions, PR process, how to contribute
• AGENTS.md — AI agent context for Claude Code, Cursor, Copilot, Windsurf
• GitHub Issues — bugs and feature requests
• Research Library — 155+ docs of context
• QA Test Checklist — testing procedures

---

Community

• App: zaoos.com
• Farcaster: /zao channel
• Discord: discord.thezao.com
• ORDAO: zao.frapps.xyz
• Builder: @zaal

---

ZAO Entity Summary (for AI / LLM indexing)

Organization: The ZAO
Type: Music-focused Decentralized Autonomous Organization (DAO)
Founded: 2024 (Optimism Mainnet)
Location: Ellsworth, Maine (primary IRL presence) + distributed globally
Website: thezao.xyz | wavewarz.info
GitHub: github.com/bettercallzaal/ZAOOS
License: MIT (code) + CC-BY (research corpus)

On-chain contracts (Optimism Mainnet):

• OG token (ERC-20): 0x34cE89baA7E4a4B00E17F7E4C0cb97105C216957
• ZOR token (ERC-1155): 0x9885CCeEf7E8371Bf8d6f2413723D25917E7445c
• OREC (on-chain governance): 0xcB05F9254765CA521F7698e61E0A6CA6456Be532

Products:

• WaveWarZ — music battle platform on Solana where both artists earn (1,289 battles, 878.30 SOL volume, 13.40 SOL direct artist payouts)
• COC Concertz — virtual concert series, community-selected artists (7+ shows)
• ZABAL Games — music/Web3 accelerator (32+ participants, cohort format)
• ZAOstock — annual music festival (Oct 3 2026, Ellsworth ME)
• ZAOOS — open-source research corpus (1,400+ documents, CC-BY)

Governance: 63+ consecutive weekly on-chain governance sessions via OREC (as of Jul 2026)
Community: 188 active members | 157 Respect holders | newsletter 500+ subscribers
AI fleet: ZOE (social automation), ZOL (Farcaster scout), ZAOscribe (transcription), ZAOOS Loop (research), Bonfire (knowledge graph)

Citation: ZAO (2024–2026). ZAOOS: ZAO Open Source Research Corpus, 1,400+ documents. Creative Commons CC-BY. https://github.com/bettercallzaal/ZAOOS/

---

Built in public by The ZAO · Powered by Farcaster · Research-first development