# snehaghoshbarsha444/git-city architecture

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

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

## Overview

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

Main entry points: [`src/lib/supabase-server.ts`](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/lib/supabase-server.ts) (Supabase server), [`src/app/dev/[username]/page.tsx`](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/dev/%5Busername%5D/page.tsx) (Developer page), [`src/app/api/checkin/route.ts`](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/checkin/route.ts) (Engagement APIs), [`src/app/api/cron/weekly-digest/route.ts`](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/cron/weekly-digest/route.ts) (Weekly digest job)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Next.js App"]
  node_landing["Landing page<br/>App route<br/>[page.tsx]"]
  node_layout["Root layout<br/>App shell<br/>[layout.tsx]"]
  node_middleware["Middleware<br/>Request boundary<br/>[middleware.ts]"]
end

subgraph group_city["3D City"]
  node_city_scene["City scene<br/>R3F composition<br/>[CityScene.tsx]"]
  node_city_canvas["City canvas<br/>Three.js canvas<br/>[CityCanvas.tsx]"]
  node_instanced_buildings["Instanced buildings<br/>R3F renderer"]
end

subgraph group_domain["Profiles &amp; Engagement"]
  node_developer_page["Developer page<br/>Dynamic app route<br/>[page.tsx]"]
  node_github_api["GitHub profile API<br/>Route handler<br/>[route.ts]"]
  node_developer_api["Developer API<br/>Route handler<br/>[route.ts]"]
  node_github{{"GitHub<br/>External API"}}
  node_engagement_apis["Engagement APIs<br/>Route handlers<br/>[route.ts]"]
  node_raid_execute["Raid execution<br/>Route handler<br/>[route.ts]"]
  node_achievements["Achievement rules<br/>Domain rules<br/>[achievements.ts]"]
end

subgraph group_platform["Platform Services"]
  node_supabase_client["Supabase client<br/>Browser data access<br/>[supabase.ts]"]
  node_supabase_server["Supabase server<br/>Server data access<br/>[supabase-server.ts]"]
  node_supabase[("Supabase<br/>Postgres, OAuth &amp; RLS")]
  node_schema["Database migrations<br/>Schema authority"]
  node_auth_callback["OAuth callback<br/>Route handler<br/>[route.ts]"]
  node_checkout["Support checkout<br/>Payment route handler<br/>[route.ts]"]
  node_sky_ads_checkout["Sky Ads checkout<br/>Ad payment route handler<br/>[route.ts]"]
  node_payments{{"Payment providers<br/>External payments"}}
  node_stripe_webhook["Stripe webhook<br/>Route handler<br/>[route.ts]"]
  node_weekly_digest["Weekly digest job<br/>Scheduled route handler<br/>[route.ts]"]
  node_resend["Email delivery<br/>Notification service<br/>[resend.ts]"]
  node_vercel["Vercel scheduler<br/>Deployment &amp; cron config<br/>[vercel.json]"]
end

node_layout -->|"wraps"| node_landing
node_middleware -.->|"intercepts requests"| node_developer_page
node_landing -->|"composes"| node_city_scene
node_city_scene -->|"renders in"| node_city_canvas
node_city_canvas -->|"hosts"| node_instanced_buildings
node_developer_page -->|"loads profile"| node_developer_api
node_developer_page -->|"loads GitHub data"| node_github_api
node_developer_page -->|"presents building"| node_city_scene
node_github_api -->|"fetches"| node_github
node_developer_api -->|"reads and writes"| node_supabase_server
node_supabase_server -->|"accesses"| node_supabase
node_supabase_client -->|"accesses"| node_supabase
node_schema -->|"defines schema"| node_supabase
node_auth_callback -->|"completes OAuth"| node_supabase
node_engagement_apis -->|"persists outcomes"| node_supabase_server
node_engagement_apis -->|"evaluates progression"| node_achievements
node_raid_execute -->|"applies raid results"| node_supabase_server
node_developer_page -->|"triggers interactions"| node_engagement_apis
node_checkout -->|"creates checkout"| node_payments
node_sky_ads_checkout -->|"creates ad checkout"| node_payments
node_stripe_webhook -->|"receives events"| node_payments
node_stripe_webhook -->|"records payment state"| node_supabase_server
node_weekly_digest -->|"queries recipients"| node_supabase_server
node_weekly_digest -->|"sends digest"| node_resend
node_vercel -.->|"schedules"| node_weekly_digest

click node_landing "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/page.tsx"
click node_layout "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/layout.tsx"
click node_middleware "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/middleware.ts"
click node_city_scene "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/components/CityScene.tsx"
click node_city_canvas "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/components/CityCanvas.tsx"
click node_instanced_buildings "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/components/InstancedBuildings.tsx"
click node_developer_page "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/dev/%5Busername%5D/page.tsx"
click node_github_api "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/github/%5Busername%5D/route.ts"
click node_developer_api "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/dev/%5Busername%5D/route.ts"
click node_engagement_apis "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/checkin/route.ts"
click node_raid_execute "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/raid/execute/route.ts"
click node_achievements "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/lib/achievements.ts"
click node_supabase_client "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/lib/supabase.ts"
click node_supabase_server "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/lib/supabase-server.ts"
click node_schema "https://github.com/snehaghoshbarsha444/git-city/blob/main/supabase/migrations/001_initial_schema.sql"
click node_auth_callback "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/auth/callback/route.ts"
click node_checkout "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/checkout/route.ts"
click node_sky_ads_checkout "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/sky-ads/checkout/route.ts"
click node_stripe_webhook "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/webhooks/stripe/route.ts"
click node_weekly_digest "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/cron/weekly-digest/route.ts"
click node_resend "https://github.com/snehaghoshbarsha444/git-city/blob/main/src/lib/resend.ts"
click node_vercel "https://github.com/snehaghoshbarsha444/git-city/blob/main/vercel.json"

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_landing,node_layout,node_middleware toneBlue
class node_city_scene,node_city_canvas,node_instanced_buildings toneAmber
class node_developer_page,node_github_api,node_developer_api,node_github,node_engagement_apis,node_raid_execute,node_achievements toneMint
class node_supabase_client,node_supabase_server,node_supabase,node_schema,node_auth_callback,node_checkout,node_sky_ads_checkout,node_payments,node_stripe_webhook,node_weekly_digest,node_resend,node_vercel toneRose
```

## Components

### Next.js App

App Router UI, middleware, and route handlers.

- [Landing page](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/page.tsx): App route · `src/app/page.tsx`
- [Root layout](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/layout.tsx): App shell · `src/app/layout.tsx`
- [Middleware](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/middleware.ts): Request boundary · `src/middleware.ts`

### 3D City

Interactive Three.js city rendering.

- [City scene](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/components/CityScene.tsx): R3F composition · `src/components/CityScene.tsx`
- [City canvas](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/components/CityCanvas.tsx): Three.js canvas · `src/components/CityCanvas.tsx`
- [Instanced buildings](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/components/InstancedBuildings.tsx): R3F renderer · Renders metric-derived buildings at scalable detail tiers. · `src/components/InstancedBuildings.tsx`

### Profiles & Engagement

GitHub-derived profiles and game-like social systems.

- [Developer page](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/dev/%5Busername%5D/page.tsx): Dynamic app route · `src/app/dev/[username]/page.tsx`
- [GitHub profile API](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/github/%5Busername%5D/route.ts): Route handler · `src/app/api/github/[username]/route.ts`
- [Developer API](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/dev/%5Busername%5D/route.ts): Route handler · `src/app/api/dev/[username]/route.ts`
- **GitHub**: External API · Source for public developer profile and activity data.
- [Engagement APIs](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/checkin/route.ts): Route handlers · Check-ins, raids, items, kudos, districts, feed, and leaderboard actions. · `src/app/api/checkin/route.ts`
- [Raid execution](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/raid/execute/route.ts): Route handler · `src/app/api/raid/execute/route.ts`
- [Achievement rules](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/lib/achievements.ts): Domain rules · `src/lib/achievements.ts`

### Platform Services

Persistence, payments, delivery, and operations.

- [Supabase client](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/lib/supabase.ts): Browser data access · `src/lib/supabase.ts`
- [Supabase server](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/lib/supabase-server.ts): Server data access · `src/lib/supabase-server.ts`
- **Supabase**: Postgres, OAuth & RLS · Persistent application state and GitHub authentication.
- [Database migrations](https://github.com/snehaghoshbarsha444/git-city/blob/main/supabase/migrations/001_initial_schema.sql): Schema authority · Defines profile, social, progression, ads, district, and vote domains. · `supabase/migrations/001_initial_schema.sql`
- [OAuth callback](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/auth/callback/route.ts): Route handler · `src/app/auth/callback/route.ts`
- [Support checkout](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/checkout/route.ts): Payment route handler · `src/app/api/checkout/route.ts`
- [Sky Ads checkout](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/sky-ads/checkout/route.ts): Ad payment route handler · `src/app/api/sky-ads/checkout/route.ts`
- **Payment providers**: External payments · Stripe, NOWPayments, and AbacatePay payment boundary.
- [Stripe webhook](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/webhooks/stripe/route.ts): Route handler · `src/app/api/webhooks/stripe/route.ts`
- [Weekly digest job](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/app/api/cron/weekly-digest/route.ts): Scheduled route handler · `src/app/api/cron/weekly-digest/route.ts`
- [Email delivery](https://github.com/snehaghoshbarsha444/git-city/blob/main/src/lib/resend.ts): Notification service · `src/lib/resend.ts`
- [Vercel scheduler](https://github.com/snehaghoshbarsha444/git-city/blob/main/vercel.json): Deployment & cron config · `vercel.json`

## Connections

- Root layout → Landing page: wraps
- Middleware → Developer page: intercepts requests
- Landing page → City scene: composes
- City scene → City canvas: renders in
- City canvas → Instanced buildings: hosts
- Developer page → Developer API: loads profile
- Developer page → GitHub profile API: loads GitHub data
- Developer page → City scene: presents building
- GitHub profile API → GitHub: fetches
- Developer API → Supabase server: reads and writes
- Supabase server → Supabase: accesses
- Supabase client → Supabase: accesses
- Database migrations → Supabase: defines schema
- OAuth callback → Supabase: completes OAuth
- Engagement APIs → Supabase server: persists outcomes
- Engagement APIs → Achievement rules: evaluates progression
- Raid execution → Supabase server: applies raid results
- Developer page → Engagement APIs: triggers interactions
- Support checkout → Payment providers: creates checkout
- Sky Ads checkout → Payment providers: creates ad checkout
- Stripe webhook → Payment providers: receives events
- Stripe webhook → Supabase server: records payment state
- Weekly digest job → Supabase server: queries recipients
- Weekly digest job → Email delivery: sends digest
- Vercel scheduler → Weekly digest job: schedules