Repository map
Documentation
This page is a README-style overview of the Panorama-named repositories: what each codebase is responsible for, which folders matter, and how the market stack ties ingestion, proofs, verification, and settlement together. For field-level API detail, use the linked repo files (LOCAL_STACK.md, SERVICES_API.md).
What "Panorama Protocol" means in these repos
Public messaging (this landing site) describes a privacy-oriented programmable ad network: permissionless participation, verifiable impressions, and settlement-friendly attribution. The implementation spine for that story today lives primarily in panorama-protocol-market-main: a Next.js marketplace UI, a Node market-api, workers for proofs and settlement, a verifier, optional RISC Zero proving, a publisher SDK, and shared types so the same event shapes flow from ingestion through to settlement records.
panorama-protocol-dash-main is the companion operator / campaign surface (legacy React subtree). panorama-protocol-saas-main is a Next.js starter intended to grow into customer-facing SaaS (auth, dashboards, integrations) — it is not yet the full product by itself. The two public site repos (this Next app and Expo panorama-website-main) can diverge in copy; treat production panoramaprotocol.com as canonical for external messaging unless you intentionally unify Expo content.
How the pieces work together
At a high level, traffic and data move from publishers and users into the market API, through a proof pipeline, into verification and settlement intents, while humans use the marketplace UI or dashboard to configure campaigns and inspect outcomes.
Correlation IDs are propagated across ingestion → proof → verifier → settlement → attribution so a single user-visible action can be traced in logs and SQLite rows (LOCAL_STACK.md in the market repo documents this explicitly).
Typical roles
- Publisher / integrator uses
packages/publisher-sdkto emit signedimpression/clickevents tomarket-apiingestion routes. - Trader / participant uses the marketplace app (
PANORAMA-market-develop/) with wallet auth (JWT from nonce/verify) to read public offers and write authenticated state when not in dev bypass mode. - Operator uses the dashboard app for higher-level campaign or ops workflows aligned with the same protocol concepts (separate repo, same org).
- Automation:
optimizer-agentperiodically posts optimizer actions derived from active campaigns and pacing rules.
Repository quick reference
- panorama-protocol-market-main — Full local stack: UI +
market-api+ proof worker + verifier + settlement + optimizer + SDK + shared types. - panorama-protocol-dash-main — Operator dashboard (React + CRA in
PANORAMA-dash-develop/). - panorama-protocol-saas-main — Next.js 14 SaaS shell; roadmap for auth and productized dashboards.
- panorama-protocol-landing — This marketing + docs site (Next.js App Router).
- panorama-website-main — Expo / React Native Web alternative public site; verify messaging before linking it from campaigns.
Marketing & public sites
| Repository | Summary |
|---|---|
| panorama-protocol-landing | Role: Canonical marketing story for Panorama (hero, pillars, long-term outlook) plus this documentation page and global nav. Stack: Next.js 14, static-friendly routes (/, /docs). Deploy: point production domain here when panoramaprotocol.com should match this tree. Together with market: explains the protocol; does not run ingestion or proofs — it links readers to GitHub and to the market repo for implementation detail. |
| panorama-website-main | Role: Separate public site built with Expo for web. Run: npm run web; static export to web-build per README. Together with landing: may use different headline and body copy (storage / DID framing vs ad-network framing). Reconcile deliberately if both remain public. |
panorama-protocol-market-main (core stack)
Repository: panorama-protocol-market-main. This is the richest Panorama repo: it implements the loop from wallet auth and offers through event ingestion, proof generation, cryptographic verification, and settlement intents, with SQLite as the default persistence layer.
Layout (where to look first)
PANORAMA-market-develop/— Primary Next.js + web3 marketplace UI. Vercel build is rooted here via repovercel.json.services/market-api/— HTTP API for accounts, offers, ingestion, proof state, settlement intents, campaigns, optimizer hooks, and data-union primitives.services/proof-worker/,services/verifier-api/,services/risc0-prover/,services/settlement/,services/optimizer-agent/— Background pipeline and automation.packages/publisher-sdk/,packages/shared-types/— Client SDK and shared schemas.scripts/dev-stack.ps1,scripts/smoke-test.ps1,scripts/demo-sdk.js,scripts/seed-data.ps1— Local orchestration and demos (see README).
Services (ports & responsibilities)
- market-api (
4010) — Nonce/verify for wallet sessions, public and authenticated offer routes, event ingestion, proof queue state, settlement intent records, campaign and optimizer action endpoints, and data-union schema / contribution / payout endpoints. Persists todata.sqlite(with one-time migration from legacydata.json). - verifier-api (
4011) — Validates proof artifacts: deterministic hash checks and RISC Zero receipt paths (risc0/risc0-sim), with image allowlist env documented inLOCAL_STACK.md. - risc0-prover (
4020) — Rust service:devmode for deterministic envelopes vsexecmode delegating toRISC0_PROVER_CMDwhen you wire real proving. - proof-worker — Polls market-api for work, generates proofs (
deterministicorrisc0), calls verifier-api, marks proofs verified, and creates settlement intents. - settlement — Consumes intents through a pluggable chain adapter; default driver is
dryRunso local demos complete without a live chain. - optimizer-agent — Rule-based agent that writes campaign pacing / budget actions back through market-api surfaces.
Packages
- publisher-sdk — JavaScript SDK to sign and send
impressionandclickevents into ingestion; use this when simulating a publisher or integrating a test site. - shared-types — Canonical shapes for PoI-style events, proof envelopes, and attribution records shared between services and tooling.
Local development
Full stack (recommended): from repo root, .\scripts\dev-stack.ps1 (Windows) or docker compose up then run the frontend from PANORAMA-market-develop as described in LOCAL_STACK.md. Expect marketplace at http://localhost:3000 and API at http://localhost:4010.
Frontend without full auth loop: set NEXT_PUBLIC_DEV_BYPASS_AUTH=true per README so nonce/verify is bypassed for UI work; protected offer calls are stubbed in that mode.
Authoritative docs in repo: README.md (structure and quick commands), LOCAL_STACK.md (architecture, env vars, E2E demo sequence), SERVICES_API.md (HTTP surface reference).
Dashboard & SaaS
| Repository | Summary |
|---|---|
| panorama-protocol-dash-main | Role: Web dashboard for operators working alongside the marketplace — campaign, reporting, or internal tooling angles (see in-app routes). Code: PANORAMA-dash-develop/ is Create React App + React; root is a thin Next wrapper. Run: cd PANORAMA-dash-develop, npm install, npm run start:local. Together with market: same protocol domain, different UX surface; typically talks to the same or related APIs depending on how you wire environments in your deployment. |
| panorama-protocol-saas-main | Role: Future-facing SaaS portal starter (Next.js 14, React 18, TypeScript). README states auth, dashboards, and integrations are expected to evolve — use it as the shell for customer onboarding, billing UI, or multi-tenant protocol management once you define those flows. Together with market: not a substitute for market-api; it would orchestrate or present data that ultimately still flows through the market stack or chain adapters you configure. |
Minimal end-to-end sequence (from LOCAL_STACK)
When everything is running locally, the market repo documents this happy path to validate wiring:
- Connect wallet in the marketplace UI.
- Sign the nonce challenge; local verify issues a JWT (skipped in dev bypass mode).
- Create an offer via authenticated API routes.
- Emit an SDK impression event (e.g. demo script) into ingestion.
- Proof worker completes verification and creates a settlement intent.
- Settlement service marks the intent settled via the configured adapter (
dryRunby default). - Optimizer agent writes campaign actions for active campaigns.
- Confirm correlation IDs line up across event, proof, and settlement records.
Other COMMENTZRUS products (Streamy, Comment Protocol, shared contracts) live in their own repositories; they are intentionally out of scope on this Panorama-focused page — see their READMEs for cross-ecosystem bridges.