# srizzon/git-city architecture

> Architecture diagram of the GitHub repository srizzon/git-city, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/srizzon/git-city
- Repository: https://github.com/srizzon/git-city

## Overview

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: [`src/app/api`](https://github.com/srizzon/git-city/tree/main/src/app/api) (API routes), [`src/lib`](https://github.com/srizzon/git-city/tree/main/src/lib) (Shared logic), [`src/app`](https://github.com/srizzon/git-city/tree/main/src/app) (Next.js app), [`src/app/api/cron`](https://github.com/srizzon/git-city/tree/main/src/app/api/cron) (Cron jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Next.js app"]
  node_webapp["Next.js app<br/>app router"]
  node_middleware["Middleware<br/>edge policy<br/>[middleware.ts]"]
  node_city_ui(("City scene<br/>3D frontend<br/>[CityScene.tsx]"))
  node_game_ui(("Arcade UI<br/>game frontend<br/>[LiveDots.tsx]"))
  node_jobs_ui["Jobs surface<br/>marketplace UI"]
  node_ads_ui["Ads surface<br/>ad platform UI"]
  node_api_routes["API routes<br/>server api"]
  node_cron_jobs["Cron jobs<br/>scheduled tasks"]
end

subgraph group_core["Shared logic"]
  node_shared_lib["Shared logic<br/>domain services"]
  node_github["GitHub layer<br/>identity+data<br/>[github.ts]"]
  node_supabase_clients[("Supabase clients<br/>db clients<br/>[supabase.ts]")]
  node_social_game{{"Progression loop<br/>gamification<br/>[xp.ts]"}}
  node_jobs_core{{"Jobs engine<br/>marketplace rules"}}
  node_ads_core{{"Ads engine<br/>ad operations<br/>[skyAds.ts]"}}
  node_commerce["Payments<br/>billing integrations<br/>[stripe.ts]"]
end

subgraph group_data["Data layer"]
end

subgraph group_realtime["Realtime subsystem"]
  node_realtime_lobby["Party rooms<br/>realtime room<br/>[lobby.ts]"]
  node_arcade_engine["Arcade engine<br/>client engine<br/>[gameLoop.ts]"]
end

subgraph group_extension["VS Code extension"]
  node_vscode_ext["VS Code extension<br/>editor package<br/>[extension.ts]"]
end

subgraph group_assets["Assets and generators"]
  node_content_assets["City assets<br/>media pipeline"]
end

node_webapp -->|"guards"| node_middleware
node_webapp -->|"serves"| node_api_routes
node_webapp -->|"renders"| node_city_ui
node_webapp -->|"renders"| node_game_ui
node_webapp -->|"hosts"| node_jobs_ui
node_webapp -->|"hosts"| node_ads_ui
node_api_routes -->|"uses"| node_shared_lib
node_api_routes -->|"queries"| node_github
node_api_routes -->|"persists"| node_supabase_clients
node_api_routes -->|"drives"| node_social_game
node_api_routes -->|"orchestrates"| node_jobs_core
node_api_routes -->|"orchestrates"| node_ads_core
node_api_routes -->|"charges"| node_commerce
node_cron_jobs -->|"uses"| node_shared_lib
node_cron_jobs -->|"processes"| node_jobs_core
node_cron_jobs -->|"processes"| node_ads_core
node_shared_lib -->|"reads/writes"| node_supabase_clients
node_shared_lib -->|"enriches"| node_github
node_shared_lib -->|"contains"| node_social_game
node_shared_lib -->|"contains"| node_jobs_core
node_shared_lib -->|"contains"| node_ads_core
node_realtime_lobby -->|"syncs"| node_arcade_engine
node_game_ui -->|"connects"| node_realtime_lobby
node_city_ui -->|"uses"| node_content_assets
node_game_ui -->|"uses"| node_content_assets
node_vscode_ext -->|"calls"| node_api_routes

click node_webapp "https://github.com/srizzon/git-city/tree/main/src/app"
click node_middleware "https://github.com/srizzon/git-city/blob/main/src/middleware.ts"
click node_city_ui "https://github.com/srizzon/git-city/blob/main/src/components/CityScene.tsx"
click node_game_ui "https://github.com/srizzon/git-city/blob/main/src/components/LiveDots.tsx"
click node_jobs_ui "https://github.com/srizzon/git-city/tree/main/src/app/jobs"
click node_ads_ui "https://github.com/srizzon/git-city/tree/main/src/app/ads"
click node_api_routes "https://github.com/srizzon/git-city/tree/main/src/app/api"
click node_cron_jobs "https://github.com/srizzon/git-city/tree/main/src/app/api/cron"
click node_shared_lib "https://github.com/srizzon/git-city/tree/main/src/lib"
click node_github "https://github.com/srizzon/git-city/blob/main/src/lib/github.ts"
click node_supabase_clients "https://github.com/srizzon/git-city/blob/main/src/lib/supabase.ts"
click node_social_game "https://github.com/srizzon/git-city/blob/main/src/lib/xp.ts"
click node_jobs_core "https://github.com/srizzon/git-city/tree/main/src/lib/jobs"
click node_ads_core "https://github.com/srizzon/git-city/blob/main/src/lib/skyAds.ts"
click node_commerce "https://github.com/srizzon/git-city/blob/main/src/lib/stripe.ts"
click node_realtime_lobby "https://github.com/srizzon/git-city/blob/main/party/lobby.ts"
click node_arcade_engine "https://github.com/srizzon/git-city/blob/main/src/lib/arcade/engine/gameLoop.ts"
click node_vscode_ext "https://github.com/srizzon/git-city/blob/main/packages/vscode-extension/src/extension.ts"
click node_content_assets "https://github.com/srizzon/git-city/tree/main/public/models"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_middleware,node_city_ui,node_game_ui,node_jobs_ui,node_ads_ui,node_api_routes,node_cron_jobs toneBlue
class node_shared_lib,node_github,node_supabase_clients,node_social_game,node_jobs_core,node_ads_core,node_commerce toneAmber
class node_realtime_lobby,node_arcade_engine toneRose
class node_vscode_ext toneIndigo
class node_content_assets toneTeal
```

## Components

### Next.js app

Main web app, API routes, and page surfaces.

- [Next.js app](https://github.com/srizzon/git-city/tree/main/src/app): app router · Primary public site with pages, API routes, cron endpoints, and admin consoles. · `src/app`
- [Middleware](https://github.com/srizzon/git-city/blob/main/src/middleware.ts): edge policy · Request-level routing and auth/session gating before app routes. · `src/middleware.ts`
- [City scene](https://github.com/srizzon/git-city/blob/main/src/components/CityScene.tsx): 3D frontend · Interactive 3D city and profile visualization layer for GitHub identities. · `src/components/CityScene.tsx`
- [Arcade UI](https://github.com/srizzon/git-city/blob/main/src/components/LiveDots.tsx): game frontend · Browser-side arcade visuals, overlays, and controls for the multiplayer experience. · `src/components/LiveDots.tsx`
- [Jobs surface](https://github.com/srizzon/git-city/tree/main/src/app/jobs): marketplace UI · Public jobs pages, dashboards, and candidate workflows. · `src/app/jobs`
- [Ads surface](https://github.com/srizzon/git-city/tree/main/src/app/ads): ad platform UI · Advertiser dashboard, purchase flow, and admin moderation views. · `src/app/ads`
- [API routes](https://github.com/srizzon/git-city/tree/main/src/app/api): server api · Large transactional surface for auth, profile data, jobs, ads, pixels, raids, cron, and webhooks. · `src/app/api`
- [Cron jobs](https://github.com/srizzon/git-city/tree/main/src/app/api/cron): scheduled tasks · 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](https://github.com/srizzon/git-city/tree/main/src/lib): domain services · Common business logic and service clients used by pages, APIs, and jobs. · `src/lib`
- [GitHub layer](https://github.com/srizzon/git-city/blob/main/src/lib/github.ts): identity+data · OAuth and API access for identity, contribution data, profile stats, and cards. · `src/lib/github.ts`
- [Supabase clients](https://github.com/srizzon/git-city/blob/main/src/lib/supabase.ts): db clients · Browser and server Supabase access with auth-bound and service-role boundaries. · `src/lib/supabase.ts`
- [Progression loop](https://github.com/srizzon/git-city/blob/main/src/lib/xp.ts): gamification · Achievements, XP, dailies, items, streaks, pixels, zones, and notifications. · `src/lib/xp.ts`
- [Jobs engine](https://github.com/srizzon/git-city/tree/main/src/lib/jobs): marketplace rules · Validation, scoring, emails, payouts, notifications, and job lifecycle logic. · `src/lib/jobs`
- [Ads engine](https://github.com/srizzon/git-city/blob/main/src/lib/skyAds.ts): ad operations · Advertiser auth, moderation, plans, billing, reporting, and ad delivery logic. · `src/lib/skyAds.ts`
- [Payments](https://github.com/srizzon/git-city/blob/main/src/lib/stripe.ts): billing integrations · Stripe, AbacatePay, and NowPayments checkout and webhook integration layer. · `src/lib/stripe.ts`

### Realtime subsystem

PartyKit-powered multiplayer arcade runtime.

- [Party rooms](https://github.com/srizzon/git-city/blob/main/party/lobby.ts): realtime room · PartyKit room/state model for lobby and arcade multiplayer sessions. · `party/lobby.ts`
- [Arcade engine](https://github.com/srizzon/git-city/blob/main/src/lib/arcade/engine/gameLoop.ts): client 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](https://github.com/srizzon/git-city/blob/main/packages/vscode-extension/src/extension.ts): editor package · 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](https://github.com/srizzon/git-city/tree/main/public/models): media pipeline · Models, sprites, maps, audio, and generation scripts used by the city and arcade. · `public/models`

## Connections

- 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.
