How srizzon/git-city works
1. Overall shape
- This is a Next.js 16 App Router monorepo centered on a public web app, with a large server API surface, a separate VS Code extension package, and a PartyKit realtime subsystem.
- The product is “Git City”: GitHub identities are rendered as 3D pixel-art buildings inside an interactive city.
2. Primary runtime boundary
- src/app contains both the user-facing pages and the API routes, so the app server is doing most of the orchestration.
- src/lib holds the shared domain logic and service clients that the pages, route handlers, cron jobs, and UI components all reuse.
- src/middleware.ts likely applies request-level routing/auth/session policy at the edge before requests reach pages or APIs.
3. City / 3D experience
- The core experience is in the city and profile visuals: src/components/CityScene.tsx, CityCanvas.tsx, Building3D.tsx, InstancedBuildings.tsx, MiniMap.tsx, and related effects/components.
- The README describes buildings whose height, width, and lighting are derived from contribution/repo/star/activity data, so the 3D scene is a rendering layer over GitHub-backed profile metrics.
- Public assets in public/models, public/sprites, public/maps, public/audio, and public/fonts are part of the visual/audio pipeline, not just decorative static files.
4. Data model and persistence
- Supabase is the main data platform: src/lib/supabase.ts and src/lib/supabase-server.ts separate client-side and server-side access.
- The database schema lives in supabase/migrations, which shows the product is heavily data-driven and evolved through many feature-specific tables/RPCs.
- Row Level Security and server-role access are important architectural boundaries: user-scoped reads/writes happen through the Supabase client, while admin workflows and scheduled jobs use service credentials.
5. GitHub identity and profile layer
- GitHub is a foundational external system via OAuth and API access: src/app/api/auth/github, src/lib/github.ts, src/lib/github-api.ts, and routes such as src/app/api/dev/[username], src/app/api/portfolio/[username], and src/app/api/share-card/[username].
- This layer feeds profile pages, comparison pages, share cards, achievements, and building stats.
- The architecture depends on GitHub being both an auth provider and the source of profile/contribution data.
6. Social, engagement, and game-like systems
- Several feature modules form a “progression loop”: achievements, XP, streaks, dailies, leaderboard, presence, visits, kudos, referrals, items, and customization.
- The corresponding logic is spread across src/lib/achievements.ts, src/lib/xp.ts, src/lib/dailies.ts, src/lib/items.ts, src/lib/raid.ts, src/lib/pixels.ts, src/lib/zones.ts, and many notification senders.
- These systems are mostly event-driven: user actions flow through API routes, update database state, and then trigger notifications, leaderboards, or visual effects in the UI.
7. Monetization and commerce
- There are multiple monetization tracks: ads, jobs, support, pixels, items, and possibly creator drops.
- Payment and checkout integrations are split across src/lib/stripe.ts, src/lib/abacatepay.ts, and src/lib/nowpayments.ts, with webhook endpoints under src/app/api/webhooks/*.
- The ad system is especially mature: it has advertiser dashboards, setup/tracking flows, stats APIs, webhook handling, and admin moderation tools.
8. Jobs marketplace subsystem
- Jobs is a first-class product area, not a side feature: it has public listing pages, employer dashboards, candidate management, alerts, referrals, and admin review tooling.
- Server-side business rules live in src/lib/jobs/*, while the UI is split between public pages under src/app/jobs/* and admin tools under src/app/admin/jobs/*.
- The jobs flow is end-to-end: create/manage jobs, approve/reject, apply, notify candidates, export candidates, and run digests/reports via cron.
9. Advertising platform and admin operations
- Ads has its own internal admin console under src/app/admin/ads and a public advertiser dashboard under src/app/ads/dashboard.
- Supporting libraries such as src/lib/skyAds.ts, src/lib/skyAdPlans.ts, src/lib/ad-moderation.ts, src/lib/ad-emails.ts, and src/lib/advertiser-auth.ts show a distinct business domain with separate auth, billing, moderation, and reporting.
- Admin-only routes under src/app/api/admin/* form a controlled boundary for company, job, drop, and email-monitoring operations.
10. Realtime / multiplayer arcade
- The arcade is a separate interactive subsystem: src/lib/arcade/* contains the client/game engine pieces, while party/arcade.ts and party/lobby.ts implement realtime server rooms.
- partykit.json indicates PartyKit is the deployment/runtime for the multiplayer side, distinct from the main Next.js/Vercel app.
- This boundary matters because arcade state and room presence are managed differently from ordinary request/response pages.
11. Automation and scheduled processing
- A large cron surface exists under src/app/api/cron/* for expiring ads/jobs, sending digests, cleaning sessions, refreshing stats, syncing snapshots, and reminder emails.
- src/lib/cron-monitor.ts and the many notification sender modules indicate background work is a core part of the system, not an afterthought.
- The app depends on scheduled HTTP invocations rather than a separate worker service in the repo.
12. Client-side feature surfaces
- The UI is organized by feature page: profile, compare, jobs, ads, shop, pixels, roadmap, support, privacy, and various preview/POC pages.
- Many pages are “client-heavy” wrappers around server data, with reusable feature components in src/components and feature-local components under each route folder.
- This suggests a hybrid app where Next.js server routes provide data and transactional operations, while the browser handles the rich 3D/animated experience.
13. VS Code extension package
- packages/vscode-extension is an independent distributable package built with its own package.json, TypeScript config, and esbuild pipeline.
- Its modules cover activity tracking, API client/queueing, auth keystore, privacy sanitization, and status bar UI, so it is a companion client to the main platform rather than a library.
- The extension likely talks back to the main app’s APIs and shares auth/data concepts, but it remains a separately built artifact.
14. Asset and content pipeline
- The repo includes generation scripts for lobby maps, tilesets, and analytics reports, which means some content is produced rather than hand-authored.
- Static game/city assets, generated map data, and pixel art sprites are central inputs to the rendering layer.
- This makes the repository part application code and part content pipeline for the city and arcade worlds.
Main entry points: api API routes · lib Shared logic · app Next.js app · cron Cron jobs
Components 19
Next.js app
Main web app, API routes, and page surfaces.
- Next.js app · Primary public site with pages, API routes, cron endpoints, and admin consoles.
src/app - Middleware · Request-level routing and auth/session gating before app routes.
src/middleware.ts - City scene · Interactive 3D city and profile visualization layer for GitHub identities.
src/components/CityScene.tsx - Arcade UI · Browser-side arcade visuals, overlays, and controls for the multiplayer experience.
src/components/LiveDots.tsx - Jobs surface · Public jobs pages, dashboards, and candidate workflows.
src/app/jobs - Ads surface · Advertiser dashboard, purchase flow, and admin moderation views.
src/app/ads - API routes · Large transactional surface for auth, profile data, jobs, ads, pixels, raids, cron, and webhooks.
src/app/api - Cron jobs · HTTP-triggered background jobs for digests, expiry, cleanup, sync, and reminders.
src/app/api/cron
Shared logic
Domain services, clients, and feature rules reused across the app.
- Shared logic · Common business logic and service clients used by pages, APIs, and jobs.
src/lib - GitHub layer · OAuth and API access for identity, contribution data, profile stats, and cards.
src/lib/github.ts - Supabase clients · Browser and server Supabase access with auth-bound and service-role boundaries.
src/lib/supabase.ts - Progression loop · Achievements, XP, dailies, items, streaks, pixels, zones, and notifications.
src/lib/xp.ts - Jobs engine · Validation, scoring, emails, payouts, notifications, and job lifecycle logic.
src/lib/jobs - Ads engine · Advertiser auth, moderation, plans, billing, reporting, and ad delivery logic.
src/lib/skyAds.ts - Payments · Stripe, AbacatePay, and NowPayments checkout and webhook integration layer.
src/lib/stripe.ts
Realtime subsystem
PartyKit-powered multiplayer arcade runtime.
- Party rooms · PartyKit room/state model for lobby and arcade multiplayer sessions.
party/lobby.ts - Arcade engine · Client-side game loop, input, rendering, sprites, and tile-map logic.
src/lib/arcade/engine/gameLoop.ts
VS Code extension
Separate distributable client package.
- VS Code extension · Standalone extension package for activity tracking, auth, privacy, and status-bar UI.
packages/vscode-extension/src/extension.ts
Assets and generators
Static media and scripts that feed the city and arcade experiences.
- City assets · Models, sprites, maps, audio, and generation scripts used by the city and arcade.
public/models
Connections 26
- Next.js app → Middleware: guards · Edge middleware filters and routes requests before the app handles them.
- Next.js app → API routes: serves · Pages and client surfaces call into the app's API surface.
- Next.js app → City scene: renders · The main experience includes the 3D city and profile visualization layer.
- Next.js app → Arcade UI: renders · Arcade pages mount the interactive multiplayer frontend.
- Next.js app → Jobs surface: hosts · Jobs routes and dashboards are delivered from the Next.js app.
- Next.js app → Ads surface: hosts · Ads advertiser and admin surfaces are delivered from the Next.js app.
- API routes → Shared logic: uses · Route handlers rely on shared business logic and clients.
- API routes → GitHub layer: queries · Identity, profile, and card endpoints depend on GitHub data.
- API routes → Supabase clients: persists · Most route handlers read and write through Supabase.
- API routes → Progression loop: drives · Event endpoints update progression systems and notifications.
- API routes → Jobs engine: orchestrates · Jobs endpoints enforce marketplace rules and workflows.
- API routes → Ads engine: orchestrates · Ads endpoints enforce advertiser auth, moderation, and reporting.
- API routes → Payments: charges · Checkout and webhook routes connect payments to product flows.
- Cron jobs → Shared logic: uses · Scheduled endpoints reuse the same domain services as requests.
- Cron jobs → Jobs engine: processes · Job digests, expiry, and notifications are handled by cron.
- Cron jobs → Ads engine: processes · Ad expiry, stats refresh, and reports are handled by cron.
- Shared logic → Supabase clients: reads/writes · Shared logic is built around the Supabase persistence boundary.
- Shared logic → GitHub layer: enriches · Shared services derive profile and contribution data from GitHub.
- Shared logic → Progression loop: contains · Core progression and engagement logic is concentrated here.
- Shared logic → Jobs engine: contains · Jobs business rules, scoring, and emails live in shared modules.
- Shared logic → Ads engine: contains · Ads business rules, auth, moderation, and plans live in shared modules.
- Party rooms → Arcade engine: syncs · Party rooms coordinate state with the client-side arcade engine.
- Arcade UI → Party rooms: connects · The arcade frontend joins multiplayer rooms through PartyKit.
- City scene → City assets: uses · 3D city rendering depends on models, sprites, audio, and generated maps.
- Arcade UI → City assets: uses · Arcade visuals and sounds depend on the shared asset pipeline.
- VS Code extension → API routes: calls · The extension communicates with the main platform APIs.