snehaghoshbarsha444/git-city

Purpose and Runtime

Git City is a Next.js 16 App Router application that turns GitHub profiles into customizable 3D buildings in an explorable city. It runs React/TypeScript on Vercel, renders Three.js through React Three Fiber, and serves both UI routes and server API route handlers. Primary entry points are src/app/page.tsx, src/app/layout.tsx, and src/middleware.ts.

City Rendering and Exploration

The landing experience composes a 3D city scene, instanced building rendering, effects, navigation, and activity-driven overlays. City geometry maps GitHub-derived developer metrics into building dimensions and visual properties; rendering uses detail tiers for scale. Core paths: src/components/CityScene.tsx, src/components/CityCanvas.tsx, src/components/InstancedBuildings.tsx.

Developer Profile and GitHub Ingestion

Developer pages resolve a username, obtain developer/GitHub data through APIs, and present the generated building, stats, achievements, sharing, and interaction affordances. GitHub is an external source boundary; Supabase persists application state and profile-related data. Core paths: src/app/dev/[username]/page.tsx, src/app/api/github/[username]/route.ts, src/app/api/dev/[username]/route.ts.

Persistence, Authentication, and Domain Rules

Supabase provides PostgreSQL, GitHub OAuth, and RLS-backed storage. Database migrations define the evolving domain: developer claims, customizations/items, social feed and achievements, ads, streaks, raids, districts, notifications, themes, and votes. Server/client database access is separated in src/lib/supabase-server.ts and src/lib/supabase.ts; OAuth returns through src/app/auth/callback/route.ts. Schema authority is supabase/migrations/001_initial_schema.sql through supabase/migrations/025_fly_scores.sql.

Engagement Systems

The application’s progression and social layer includes check-ins/streaks, achievements, items/loadouts, kudos and profile visits, districts, a live feed, leaderboard placement, raids, and rabbit/flying activities. UI/game sequences call narrowly scoped API handlers, which apply domain logic and persist results. Core paths: src/app/api/checkin/route.ts, src/app/api/raid/execute/route.ts, src/lib/achievements.ts.

Commerce and Advertising

Two monetization flows exist: user support/item purchasing and self-service “Sky Ads.” Checkout and provider webhooks form the payment boundary; ad setup, delivery/tracking, analytics, expiration, and administration are separate from the city renderer. Stripe, NOWPayments, and AbacatePay integrations are present. Core paths: src/app/api/checkout/route.ts, src/app/api/sky-ads/checkout/route.ts, src/app/api/webhooks/stripe/route.ts.

Background Delivery and Operations

Scheduled API endpoints handle ad expiry, batch flushing, digests, re-engagement, and streak reminders; Vercel configuration is the likely scheduler/deployment integration point. Email delivery is abstracted behind Resend and notification sender modules. Operational scripts seed data, backfill achievements, and report analytics. Core paths: src/app/api/cron/weekly-digest/route.ts, src/lib/resend.ts, vercel.json.