Skip to content

CLAUDE.md

Latest commit

 

History

History
84 lines (67 loc) · 5.37 KB

CLAUDE.md

File metadata and controls

84 lines (67 loc) · 5.37 KB
Raw

Git City

3D pixel art city built from real GitHub data. Buildings represent developers: height = contributions, width = repos, lit windows = recent activity.

Tech stack

  • Frontend: Next.js App Router, Three.js (instanced rendering), TypeScript
  • Backend: Supabase (Postgres + Auth + Realtime)
  • Payments: Stripe (USD), AbacatePay (BRL/PIX), NOWPayments (crypto)
  • Deployment: Vercel

Project structure

src/
  app/              Next.js pages and API routes
  components/       React + Three.js components
  lib/              Core game logic (raids, dailies, XP, items, etc.)
supabase/
  migrations/       Sequential SQL migrations (001_, 002_, ...)

Code conventions

  • TypeScript everywhere, no any
  • getSupabaseAdmin() for server-side writes (bypasses RLS)
  • createServerSupabase() for auth in API routes (cookie-based)
  • API routes validate auth, then use admin client for DB operations
  • Items use a zone system: crown, roof, aura, faces
  • Loadout stored in developer_customizations table with item_id = "loadout"

Database

  • Migrations in supabase/migrations/, numbered sequentially
  • Never modify existing migrations, always create new ones
  • Run locally with npx supabase db push
  • NEVER run UPDATE or DELETE on production data without explicit user approval
  • NEVER NULL out, drop, or modify columns that contain user data (emails, API keys, etc)
  • When fixing security/permissions issues, ONLY change grants/policies — never touch the data itself
  • Always propose SQL as code for the user to review, never execute destructive SQL directly

Environments

  • Three environments, one-directional flow: local → staging → prod (see ENVIRONMENTS.md)
  • main = production. Any other pushed branch = Vercel preview + staging Supabase
  • Pushing a branch with migration changes triggers deploy-staging-migrations.yml (validate + db push to staging)
  • Merging into main triggers deploy-migrations.yml (validate + db push to prod) — migrations deploy automatically, never push them to prod by hand
  • Vercel Preview-scoped env vars point at the staging Supabase project; Production-scoped at prod
  • Staging is disposable: reset with supabase db reset --linked while linked to staging. Never copy prod data into it

Git

  • Preserve full commit history on merge — NEVER squash PRs (use a merge commit or rebase, keep every commit)
  • Commit message format (ALWAYS follow):
    • emoji + conventional commit: ✨ feat(scope): ..., 🐛 fix(scope): ..., ✏️ docs: ..., ♻️ refactor: ...
    • single line only — no body, no bullet points
    • all lowercase, written in english
    • split work into separate commits by logical part / group of changes (never one giant commit)
  • Never skip hooks or force push to main

Third-party Assets (IMPORTANT)

  • Arcade character sprites (char_0-5) and Lumon furniture: from pixel-agents by Pablo De Lucca (MIT) / MetroCity (CC0). These ARE in the repo under public/sprites/arcade/.
  • Cozy People Asset Pack by shubibubi: purchased under commercial license ($3.99+). Used for the layered avatar (body, hair, clothing, accessories) and pet sprites.
  • Cozy Interior Asset Pack by shubibubi: purchased under commercial license. Used for arcade room furniture and tilesets.
  • License terms: "Can be used in any commercial or non commercial project, may modify. Can't be resold or redistributed even if modified."
  • NEVER commit Cozy assets to the repo — they are NOT covered by AGPL. They live in Supabase Storage and are loaded at runtime via NEXT_PUBLIC_COZY_BASE_URL.
  • NEVER include Cozy PNGs in git add — the public/cozy/ folder is gitignored.
  • Forkers must buy their own license from shubibubi on itch.io and place files in public/cozy/, then seed the arcade-assets Supabase bucket from those files. (The maintainer's upload script lives under the gitignored scripts/ folder and is not shipped — write a small one-off uploader against the arcade-assets bucket.)
  • Original purchase links: https://shubibubi.itch.io/cozy-people and https://shubibubi.itch.io/cozy-interior
  • Kenney models (public/models/trees/*.glb, public/models/props/*.glb): from Kenney Nature Kit / City Kit (CC0 — public domain). Free to use, modify, and redistribute; attribution appreciated but not required. These ARE in the repo. Raw unpacked kit folders stay local (kenney/ is gitignored).
  • San Francisco map (public/maps/sf.json): baked from OpenStreetMap data. OSM data is ODbL — the "© OpenStreetMap contributors" credit MUST stay visible on the SF map (rendered in home-client.tsx). The committed public/maps/sf.json is what ships; the bake script lives under the gitignored scripts/ folder and is not in the repo.

Key files

File What it does
src/components/InstancedBuildings.tsx WebGL instanced rendering for thousands of buildings
src/components/CityCanvas.tsx Main Three.js scene setup
src/lib/raid.ts Raid system (PvP, scoring, limits)
src/lib/items.ts Shop items, equipping, zones
src/lib/xp.ts XP leveling (25 levels, 6 tiers)
src/lib/stripe.ts Stripe checkout sessions
src/app/api/webhooks/stripe/route.ts Stripe webhook handler