git-city README

The project's README from github.com/srizzon/git-city. As one markdown file: README.md.

Git City

Your GitHub profile as a 3D pixel art building in an interactive city.

thegitcity.com

Git City — Where Code Builds Cities

What is Git City?

Git City transforms every GitHub profile into a unique pixel art building. The more you contribute, the taller your building grows. Explore an interactive 3D city, fly between buildings, and discover developers from around the world.

Features

How Buildings Work

Metric Affects Example
Contributions Building height 1,000 commits → taller building
Public repos Building width More repos → wider base
Stars Window brightness More stars → more lit windows
Activity Window pattern Recent activity → distinct glow pattern

Buildings are rendered with instanced meshes and a LOD (Level of Detail) system for performance. Close buildings show full detail with animated windows; distant buildings use simplified geometry.

Tech Stack

Getting Started

# Clone the repo
git clone https://github.com/srizzon/git-city.git
cd git-city

# Install dependencies
npm install

# Set up environment variables

# Linux / macOS
cp .env.example .env.local

# Windows (Command Prompt)
copy .env.example .env.local

# Windows (PowerShell)
Copy-Item .env.example .env.local

# Fill in your environment variables

# Run the dev server
npm run dev

Open http://localhost:3001 to see the city.

Local Supabase (no remote project needed)

You can run the whole backend locally — no Supabase account, no GitHub OAuth app.

Prerequisites: a container runtime and the Supabase CLI.

# macOS (Colima is a lightweight, free Docker alternative)
brew install colima docker supabase/tap/supabase
colima start

# ...or use Docker Desktop instead of Colima, then just:
# brew install supabase/tap/supabase

Start the stack (spins up Postgres/Auth/Storage/Studio and applies every migration from scratch):

supabase start          # first run pulls images; prints your local URL + keys
supabase status         # re-print the URL and keys at any time

Point .env.local at the printed local values:

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<Publishable key from `supabase status`>
SUPABASE_SERVICE_ROLE_KEY=<Secret key from `supabase status`>

Then npm run dev. The city renders straight from your local database — no snapshot step needed in local dev.

Logging in (zero config): the GitHub OAuth provider isn't configured for a local stack (it needs a client secret that can't ship in the repo). Instead, clicking Sign in with GitHub locally takes you to a built-in dev login — type any GitHub username and you're in, with a building created from that account. You can also go straight to http://localhost:3001/api/dev/login. This route is automatically disabled in production.

Useful commands:

supabase db reset       # re-apply all migrations on a clean database
supabase stop           # shut the stack down (data is preserved)

Studio (DB browser) runs at http://127.0.0.1:54323.

Environment Setup

After copying .env.example to .env.local, fill in these values:

Where to find the Supabase values

Open your Supabase project dashboard, then go to Project Settings -> API.

For local GitHub login to work, you also need to configure the GitHub OAuth provider in Supabase and add your local callback URL if required by your setup.

Where to find the GitHub token

Open GitHub and go to Settings -> Developer settings -> Personal access tokens.

Create a token, copy it once, and place it in GITHUB_TOKEN inside .env.local.

License

AGPL-3.0 — You can use and modify Git City, but any public deployment must share the source code.

Built by @samuelrizzondev

git-city (srizzon/git-city)

stripe
Searching Database…

5.8K ·GitHub
Git-city
What is this?Git City turns every GitHub profile into a unique 3D pixel art building inside an interactive city — the more you contribute, the taller your building grows.
Is this a hosted app or something I deploy myself?It's primarily a hosted web app you visit and sign into with GitHub, but the full source is open and AGPL-3.0 licensed, so you can run your own instance with your own Supabase and Vercel setup.
How do I run it locally?Spin up a local Supabase stack with a container runtime and the Supabase CLI, point .env.local at the printed local values, then run npm run dev — no Supabase account or GitHub OAuth app is required for local dev.
Do I need a real GitHub OAuth app or Supabase account to try it?Not for local development — a built-in dev login lets you type any GitHub username to generate a test building. For production you need Supabase (Postgres/Auth), a GitHub personal access token, and Stripe for payments.
Does GitHub login work out of the box when running it locally?No — the real GitHub OAuth provider isn't configured for the local stack because it needs a client secret that can't ship in the repo, so local dev falls back to the fake login route, which is automatically disabled in production.
What does the AGPL-3.0 license mean if I run my own instance?You're free to use and modify Git City, but if you deploy a public instance of it, you're legally required to share your source code too.
How is a building's height and width determined?Building height scales with your contribution count and width with your number of public repos, while window brightness and pattern reflect your stars and recent activity.
What else can I do besides just looking at my building?You can fly freely through the city, compare two developers side by side, send kudos and gifts, unlock achievements, customize your building with shop items, and download shareable profile cards.
What's the tech stack behind the 3D city?Next.js 16 with Turbopack for the app, Three.js via @react-three/fiber and drei for rendering, Supabase (Postgres/Auth) for the backend, Stripe for payments, and Tailwind CSS v4 for styling.
Why do far-away buildings look simpler than nearby ones?Git City renders buildings with instanced meshes and a Level-of-Detail (LOD) system — close buildings get full animated detail, while distant ones use simplified geometry to keep performance smooth.
What are similar projects?Hermes3D, petdex, chatbot, human-atlas, gitdiagram, crm, documenso, mike
Which topics is it in?github-profile, pixel-art, supabase, stripe, vercel, full-stack, threejs, webgl, agplv3, visualization, tailwindcss, oauth
Creator
srizzon
Size
32.7 MB
Stars
5.8K
Updated
CommitOct 19
Age
7mo
Commits · 90 Days