PharosVille

PharosVille turns live Pharos stablecoin signals into a desktop-only maritime observatory built with React, Three.js, TypeScript, Vite, and Cloudflare Pages.

Open PharosVille | Changelog | Roadmap | Architecture | Contributing | Security

What It Shows

PharosVille renders a living maritime observatory of Pharos stablecoin market signals:

• stablecoin supply, presence, and identity as ships
• chain presence as harbors and docks
• risk/status water zones around the island
• detail panels and an accessibility ledger that mirror world semantics
• a full instanced fleet, stablecoin and chain identity, region-aware shader water, a checked GLB lighthouse, and checked hero hulls

The app is intentionally desktop-only. Screens too small to chart, and windows too small to chart, must not mount the world runtime or fetch world data; they show a fallback or rotate prompt instead. The window test is a size test, not an orientation test — a tall desktop window is not a phone.

Trust Boundaries

PharosVille is an interpretive data visualization, not financial advice.

It does not provide:

• wallet connection
• trading
• custody
• user accounts
• browser-exposed API credentials

The browser calls same-origin /api/* paths only. functions/api/[[path]].ts proxies the allowlisted PharosVille read endpoints to PHAROS_API_BASE and injects PHAROS_API_KEY server-side. Never expose PHAROS_API_KEY as VITE_*, static JavaScript, HTML, query strings, logs, docs, or fixtures.

Architecture

At a high level:

1. The React route gates unsupported viewports before world data is mounted.
2. The browser requests same-origin /api/* endpoints.
3. Cloudflare Pages Functions proxy only the allowed PharosVille read paths.
4. src/systems/ builds a pure world model from live data.
5. src/three/ renders the Garden Observatory while src/renderer/ owns its thin lifecycle and hit-test boundary.
6. Runtime media is limited to same-origin stablecoin and harbor marks, checked models, and the checked water-normal texture; GPU failure falls back to a DOM signal overview.

For the full implementation map, see Architecture. For agent-facing Three.js guidance (module map, frame contract, disposal, tiers), see Three.js Agent Reference.

Repo Map

• src/ - PharosVille React shell, Three.js runtime, hooks, content, systems, and renderer
• shared/ - runtime-neutral PharosVille API contract and data logic
• functions/ - Cloudflare Pages Function proxy and server-side response hardening
• public/pharosville/models/ - checked runtime GLB models
• public/pharosville/textures/ - checked Three.js textures
• docs/pharosville/ - architecture, testing, operations, visual, and asset-maintenance docs
• .github/workflows/ - deploy, canary, CodeQL, and dependency/security automation
• agents/ - active planning and handoff artifacts
• outputs/ - scratch screenshots, renders, and generated test artifacts

Local Development

Use Node 24:

npm ci
npm run onboard:agent
npm run dev

The maintained local dev server is http://localhost:5173/.

npm run dev proxies same-origin /api/* through functions/api/[[path]].ts, which requires PHAROS_API_KEY server-side. The dev proxy resolves PHAROS_API_KEY in this order:

1. process.env.PHAROS_API_KEY
2. .env.local in the current worktree
3. .env.local in the main worktree, auto-discovered for linked worktrees
4. .git/pharosville.env.local, shared across worktrees

Initialize or update the shared key file:

npm run setup:local-api-key

Smoke the allowlisted Pharos endpoints before debugging missing local data:

npm run smoke:api-local
npm run smoke:dev-proxy

Validation

Use the smallest relevant check while iterating:

npm run validate:changed

Common focused checks:

npm run validate:docs
npm run typecheck
npm test
npm run check:runtime-media
npm run check:pharosville-colors
npm run build
npm run test:visual

Before release-level confidence:

npm run validate:release

For deployed changes:

npm run smoke:live -- --url https://pharosville.pharos.watch

Operations

Cloudflare Pages project: pharosville

Required Pages setup:

wrangler pages project create pharosville --production-branch main
wrangler pages secret put PHAROS_API_KEY --project-name pharosville

PHAROS_API_BASE is set in wrangler.toml as https://api.pharos.watch.

For deployment, smoke, rollback, and credential rotation, see Operations.

Community

• Report bugs and visual/data issues with the GitHub issue forms.
• Read CONTRIBUTING.md before opening a pull request.
• Report vulnerabilities privately through the guidance in SECURITY.md.
• Use SUPPORT.md for support scope and triage expectations.

License

MIT. See LICENSE.