Git City

Overview

Git City reimagines every GitHub profile as a distinctive, three‑dimensional pixel art building within a sprawling, interactive city. The taller your contribution story, the higher your tower climbs, turning your activity into a tangible skyline that others can explore and compare.
The city is designed as a living, navigable playground where users can fly between buildings with smooth camera controls, discovering developers from around the world as they pass through the virtual streets and airways. It blends data-driven profiles with game-like exploration to celebrate software craftsmanship in a visually engaging format.
The project envisions a seamless blend of social features, personal progression, and creative customization, offering both public visibility of achievements and private, playful interactions that encourage continued participation in the ecosystem.
The public-facing identity is anchored by visuals and language that emphasize construction, growth, and community—an artistic metaphor for code as a city-building activity that scales with collaboration, contribution, and sharing.

Visual Identity and Imagery

The Git City concept centers on a bold visual metaphor: your GitHub contributions build a skyline, where height, width, window glow, and patterns compose a unique silhouette. This design language invites exploration and friendly comparison between developers.
The main promotional and social image is represented in the project assets as “Git City — Where Code Builds Cities,” providing a striking banner for previews, posts, and links. This visual anchor helps users quickly grasp the idea of code-driven urban growth.
An emphasized foreground image is available via the embedded og image (public/og-image.png), intended for social previews and open graph sharing. The image reinforces the sense of scale, color, and the pixel-art aesthetic that defines the city.
The site itself (thegitcity.com) serves as the central hub where users can see live examples, browse profiles, and imagine their own building rising among a global skyline of developers.

Core Concepts and Features

3D Pixel Art Buildings: Each GitHub user becomes a pixel-based structure whose height encodes contributions, width reflects the number of repositories, and lit windows trace activity. The resulting skyline forms a dynamic, scalable cityscape that visually communicates coding activity at a glance.
Free Flight Mode: A reversal of the conventional browsing experience, flight mode lets you glide through the city with fluid camera controls, enabling you to approach any building, inspect its details up close, and enjoy an uninterrupted, exploratory perspective of the skyline.
Profile Pages: Dedicated developer pages consolidate stats, achievements, and top repositories. These pages act as self-contained exhibits that celebrate milestones and provide a clear portrait of a user’s coding footprint.
Achievement System: An unlockable layer of gamification recognizes milestones across contributions, stars, repositories, referrals, and more. Achievements attract attention, motivate continued activity, and give users targets to pursue.
Building Customization: Builders can claim ownership of their building and personalize it with items from an in-game shop. Customization options include crowns, auras, roof effects, and face decorations, enabling users to express personality and style while maintaining data-driven representation.
Social Features: A social layer supports kudos, gifting items, and friend referrals, plus a live activity feed. This creates a sense of community and ongoing interaction, making the city feel alive and responsive to real-time activity.
Compare Mode: A side-by-side comparison tool lets you place two developers next to each other to inspect and contrast their buildings and stats, offering a direct, visual way to evaluate differences in contributions, repos, and engagement.
Share Cards: Downloadable shareable images—formatted for both landscape and stories—let users broadcast their Git City profile on social networks or in personal communications, extending the city’s reach beyond the app.

How Buildings Work: Visual Mechanics

Buildings are rendered as instanced meshes, enabling efficient rendering of potentially thousands of structures within the city. This approach keeps the city performant as it scales with user participation.
A Level of Detail (LOD) system ensures high performance: close-by buildings display full geometry and dynamic windows, while distant structures simplify geometry to reduce rendering costs without sacrificing the overall silhouette.
The height of each building corresponds to a user’s contributions (for example, 1,000 commits yield a taller tower than a baseline). This direct mapping makes the relationship between activity and skyline immediately legible.
The base width of a building expands with the number of public repositories, giving wider bases to developers with more projects and creating a visually balanced city layout.
Window brightness correlates with the number of stars or endorsements, so more stars result in brighter, more illuminated windows, contributing to the city’s night-time aesthetic.
Recent activity produces distinctive glow patterns on windows, producing unique silhouettes that can be read as a timelapse of engagement. The pattern of light and shadow reflect current momentum and momentum shifts.
The combination of height, width, brightness, and glow patterns yields a rich, readable portrait of a developer’s activity, while maintaining a cohesive and scalable architectural style across the city.

Rendering Technology and Performance

The city is built using a modern 3D stack designed for high performance and smooth interactivity. Instanced meshes reduce draw calls, enabling thousands of buildings to render efficiently.
A Level of Detail (LOD) system automatically simplifies geometry for distant buildings, preserving visual clarity while minimizing GPU workload during broad city traversals.
Animated windows and subtle lighting contribute to a lively atmosphere without overwhelming the rendering pipeline. The city remains responsive even as it grows in size and complexity.
The combination of instanced rendering, LOD, and careful asset management yields a scalable, accessible experience that remains functional on a broad range of devices while maintaining a striking visual identity.

Technology Stack

Framework: Next.js version 16 with App Router and Turbopack for optimized development and production builds.
3D Engine: Three.js powered by React Three Fiber (@react-three/fiber) with the Drei collection for helpful abstractions and components.
Database and Authentication: Supabase (PostgreSQL) with GitHub OAuth and Row Level Security to manage access and data isolation.
Payments: Stripe for in-app transactions and potential shop-based purchases or feature unlocks.
Styling: Tailwind CSS v4, complemented by the Silkscreen pixel font to reinforce the retro-pixel aesthetic.
Hosting: Vercel provides hosting and deployment, taking advantage of its optimized delivery and serverless capabilities.

Getting Started: Quick Start Guide

Clone the repository to your local machine, using the command: git clone https://github.com/srizzon/git-city.git
Change into the project directory: cd git-city
Install the necessary dependencies: npm install
Prepare environment variables by copying the example: Linux/macOS: cp .env.example .env.local
Windows (Command Prompt): copy .env.example .env.local
Windows (PowerShell): Copy-Item .env.example .env.local
Populate the environment with your credentials and keys as described in the Environment Setup section
Start the development server: npm run dev
Open your browser and navigate to http://localhost:3001 to see the city come to life

Environment Setup: Required Variables

NEXTPUBLICSUPABASE_URL: the URL of your Supabase project
NEXTPUBLICSUPABASEANONKEY: the public anonymous key for client access
SUPABASESERVICEROLE_KEY: the service role key for server-side administration
GITHUB_TOKEN: a GitHub personal access token with appropriate scope for login and data access
ADMINGITHUBLOGINS: a list of GitHub logins authorized for admin access to /admin/ads (optional, depending on deployment)
After copying .env.local, fill in these values accurately to enable authentication, data operations, and integrations

Where to Find the Supabase Values

Open your Supabase project dashboard.
Navigate to Project Settings -> API to locate:
NEXTPUBLICSUPABASE_URL: your project URL
NEXTPUBLICSUPABASEANONKEY: the public anon key
SUPABASESERVICEROLE_KEY: the service role key for server-side administration
For local GitHub login, configure the GitHub OAuth provider within Supabase and, if required, adjust your callback URL to match your local environment setup
These settings are essential for client-side authentication, secure data access, and admin operations

GitHub Token: Access and Best Practices

Open GitHub and go to Settings -> Developer settings -> Personal access tokens to create a token.
Prefer Fine-grained tokens if you want to grant the minimum required repository and profile access. Fine-grained tokens provide scoped permissions with tighter control.
Classic tokens also work if your setup aligns better with them.
Create a token, copy it once, and place it into GITHUB_TOKEN inside .env.local.
Treat tokens as sensitive credentials; rotate them periodically and revoke access if a token is no longer needed.

Licensing and Usage Rights

License: AGPL-3.0
You are free to use and modify Git City under the terms of the AGPL-3.0 license.
If you deploy a public instance, you must share the source code in accordance with the license, promoting transparency and community collaboration.

Deployment and Hosting Considerations

Git City is designed with a modern, serverless-friendly hosting approach in mind, leveraging Vercel for deployment and hosting.
The architecture emphasizes performance, security, and ease of setup for local development and for public deployments, balancing interactivity with practical data access controls.
When sharing or showcasing profiles, the city scale and its visual uniqueness tend to attract interest, making clear attribution to the project and its creators important for community engagement.

Community, Interactions, and Growth

Social interactions are built into the core experience: users can send kudos, gift items, and invite friends to join the city, expanding the social graph beyond individual profiles.
The live activity feed provides a sense of immediacy and community momentum, allowing users to see ongoing contributions and events as they happen in real time.
Compare Mode fosters healthy competition and curiosity by letting users place two developers side by side to examine both buildings and their underlying metrics.
Share Cards enable users to broadcast their profiles and achievements across social networks, increasing visibility and inviting others to explore the city.

Developer Experience and Contributions

The project embodies a blend of game design, data visualization, and social networking, inviting developers to contribute not only code but ideas for new features, customization items, and community events.
The combination of Next.js, Three.js, Supabase, Stripe, Tailwind, and Vercel is chosen to provide a cohesive, modern stack with clear paths for extension and collaboration.
The Git City project showcases how a profiling concept can be transformed into an engaging, interactive experience that respects user data, while enabling creative expression and social sharing.

Summary: What Git City Represents

Git City is a bold attempt to translate developer activity into a tangible, immersive cityscape where pixels become buildings and milestones become skyline features.
It invites exploration, comparison, and collaboration, turning contributions into a visible narrative that communities can experience together.
By combining a data-driven backbone with a playful, customizable, social environment, Git City aims to celebrate software development as both craft and culture—one skyline at a time.

Attribution and Contact

Built by @samuelrizzondev, the project credit reflects the creator’s vision and ongoing work to expand the city’s reach and capabilities.
For additional information, updates, or community discussions, refer to the project’s repository and official site, which together document the city’s growth and the evolving ecosystem around it.

Git City

Enjoying this project?

GitHub - srizzon/git-city: Git City

Stay Updated

Product

Learn

Company

Legal

Stay Updated

Browse by Category