What the demo proves

In the demo	What it means for your repositories
traffic, stars, forks, clones, and activity shape the architecture	people can understand your portfolio signals without opening a dashboard
Gitber searches in natural language, then drives to the result	repository discovery becomes an interaction rather than another list
?user=<login> rebuilds the town from any public GitHub account	you can try the same engine with your work before cloning or configuring anything

Fastest proof: open Build my city and enter your login or one owner/repo. A username builds the public town; a repository opens that project first. No token, account connection, or fork is required.

If you find this useful for presenting repositories, star Repolis. Your star helps other developers discover the template.

Your city, as a card

Make yours in the city gallery: type a login, walk the city, and copy the card into a profile README. A shared …/u/<login> link previews as that person's city card in chat apps and social posts. Being listed in the gallery is opt-in: the account itself asks through an issue, and removal needs no reason.

From preview to your own city

Goal	What to do	Result
preview my public repos	use the live username field	a shareable town built from metadata in seconds
share one repository as an experience	paste owner/repo or a GitHub repository URL, then use Copy Repo Portal in its Atelier	a canonical confirmation link, plus ?repo=owner/repo&view=atelier&lang=en when the exhibition should be the first screen
hand another developer the best path I found	add 2–3 opened repo cards to Repo Route, then follow or share it	one ordered deep link that guides the recipient through those real houses before the earned Star invitation
find a current open-source task	choose Find something to contribute in Wayfinding (Open Source Quests), then explicitly search	three current public issues ranked for approachability, each connected to its real repo house and exact GitHub issue
introduce who built the town	visit Town Creator Hall or open Meet the town creator in the city menu	public bio, followers, GitHub tenure, top languages, badges, and signature projects tied to the current town owner
retrace what I did on this visit	open the Passport and choose Journey	the houses I opened in order, the paths I chose, and the shares or issues I left, kept on this page only (nothing stored or sent)
watch my open-source history unfold	open Town Growth Replay from Wayfinding, the Passport, or my completed public-town preview	a creation-date timeline where repo houses rise year by year, with a shareable year link and era postcard
connect with another developer	click Connect with a friend after a preview, or open Twin Towns in the city menu	a two-person link that opens both towns and their shared languages or topics
keep my town on my GitHub profile	click Put this town on my GitHub profile when the preview is ready, or use Town Postcard Studio	a 600px portal that always opens my personalized town
get my city card without opening the 3D town	type a login in the city gallery	the card, its share link, the README snippet, and an opt-in request to be listed
publish my own Repolis	use the template, enable Actions + Pages, run Refresh Repolis data once	your fork owner's public repos become the default town; no PAT required
grow buildings from real traffic	optionally add the GH_PAT Actions secret	cumulative views, visitors, and clones enrich the city each day

Forks automatically infer <owner>.github.io as the town owner and do not call the upstream AI or realtime Workers. For a custom domain, set one value in repolis.config.js.

How repository data becomes a city

Repolis maps public GitHub metadata and cumulative traffic onto a walkable town.

Signal	What it becomes
unique visitors	building height
forks	lot and building width
clones	banners and gold trim
views	garden and fence size
stars	roof ornaments
recent activity	window glow at night

Repositories are grouped into topic districts with roads, signs, hubs, and a world map. The owner's town refreshes daily from committed traffic history and the GitHub API. ?user=<login> builds a lighter public town with that user's own World Tree record and bounded local residents, while ?repo=<owner>/<repo> loads one project first through the same projection. GitHub does not publish visitor, view, or clone traffic for those public API modes, so their buildings use stars, forks, and update recency without inventing traffic. At ordinary walking distances, a one-draw architectural LOD keeps each repo house's textured walls and roof while preserving its plot, hedge, path, real window panes, shutters, sills, flower boxes, gutters, and tier-specific porch, balcony, or portico.

A village that lives

• Your city comes first. The canonical first screen asks for a GitHub login before offering the sample town. A public town's first entry plays its Growth Replay once (8–24 seconds, or only the present frame with reduced motion) and ends on a deterministic city plaque such as Python Lab City of you. A dismissible card then asks what brought you: understand one repository, explore the town, or find something to contribute. Exploring takes Gitber's taxi to three houses chosen from the catalog — the tallest, the oldest (or quietest), and a surprising one — and each district's resident guide says why, using only catalog numbers. Wayfinding is grouped into Go, Look, and Share; Look opens after one visited house and Share after two. Nothing new is requested or stored beyond one session-scoped list of towns that already played.
• Names stay readable when you walk closer. Nearby nameplates have a screen-size limit and do not overlap; the person you are talking to takes priority. Choose someone nearby in Wayfinding keeps names and roles available even when a world label is hidden. Repository cards keep their close button in view, and Escape closes the active panel without also leaving the exhibition.
• Residents follow daily routines. Named townspeople wander their districts with changing moods, visit cherished haunts, recognize friends, stroll or sit together, gather around the campfire, and sometimes celebrate a recent repository release. At night, they return to warm windows and porch seats. In the morning, they head back to work in their districts. Their cottages form Starlight Row on the north-east edge, with resident-coloured gardens, three roof silhouettes, shutters, transoms, selected window boxes, canopies, chimneys, and roof finials. A shared flower bed, lanterns, hedges, broadleaf trees, and cypresses fill the common spaces. Pairs also choose short Shared Joy excursions to real flower patches, visible stars at night, or a real repository house, all without a player prompt or AI call. When asked a specialist question, residents introduce the right scholar instead of pretending to know the answer. Follow the compass to find that scholar in the world.
• A public town lives from its own record. The one existing public-repository load deterministically supplies its era, season, Silence Ledger, archived Roots, and up to six desktop/four phone-or-LOW_END residents with local jobs, greetings, and real repo-home bindings. Traffic, owner residents, Shared/Bound memories, realtime, and grounded services stay unknown or off; no second API request or model call is made.
• The owner World Tree keeps a small factual history. Its Thirty-day Sap Ledger retains up to 30 actual UTC daily entries of public repo, star, fork, recent-activity, season, and Silence aggregates. Same-day refreshes replace instead of duplicate, missing days stay missing, and foreign towns explicitly receive no owner ledger.
• The roots open into a walkable archive. The Undercroft turns the current town's archived public repositories into deterministic shelves and plaques beneath the World Tree. Approach one to read its existing Roots text, active years, and available last public activity, then open the repository in a new tab. The Chronicle stays available as the accessible summary; empty and foreign towns keep their own truthful record without borrowing owner history.
• Exploration continues across visits. The Explorer Passport records houses and landmarks, district progress shows what remains, and the daily Village Chronicle links one resident and their cherished haunt to a repository or district with a real connection.
• The city points outward to real work. Open Source Quests makes one anonymous public GitHub search only when the visitor asks, ranks up to three current good first issue, help wanted, or open issues, and leads through the actual repository house before the exact issue handoff. After that repository's Blueprint is explicitly loaded, Issue-to-Code Scout can compare only the selected issue's title and labels with actual path metadata and offer up to five candidate paths to inspect first. It makes no file relationship or modification claim, adds no request, and returns no guess when lexical evidence is weak. Results stay in the tab; no login, token, issue tracking, or new backend is involved. The existing earned Star invitation can appear only after the visitor chooses to open an issue.
• A visitor can hand off the route that proved the town's value. After opening a repository house, Repo Route can save it to an ordered 2–3 stop walk. The recipient's link confirms the stops before entry, points to each real house in sequence, and offers the existing earned Star invitation only after completion. The draft is session-only; the URL contains public repo names and adds no backend, account, storage key, or render asset.
• Your repository history becomes a moving city story. Town Growth Replay reads the public creation date already carried by every repo house, then raises the town through its real repo-birth years from the first house to the present. The scrubber, play/pause controls, deep link, and era postcard work for the owner and every ?user= public town. The timeline covers repos still public today; house appearance and language labels stay explicitly marked as today’s metadata. Replay adds no mesh, texture, light, backend, account, or stored history.
• A repository can be the front door. Repo Portal accepts owner/repo or a GitHub URL, loads that one public target before the owner catalog, and takes the visitor into its Repository Atelier after one entry click. A strict ?repo=owner/repo&view=atelier&lang=en campaign link instead holds a short portal transition over initialization and opens the same exhibition directly, without flashing the exterior town or covering it with chat. Direct links default to English; use lang=ko for Korean. The Atelier can copy the canonical confirmation address, open GitHub, or expand into the owner's full town. A 15-minute, 512 KiB local cache and stale fallback keep the path bounded; unavailable traffic remains unknown.
• Every repo house opens into one finished exhibition. The reusable Repository Atelier puts the exact owner/repo and its public description in front of you; the Core, statistics, and history remain supporting exhibits. README getting started reads that public repository's README only when chosen, then shows original headings, conditions, copyable code, source lines, branch/ref, document blob SHA, and read time. These are bounded excerpts, not generated instructions or a verified complete setup guide; missing guidance stays missing. No model call, image download, or command execution is involved. Homepage, GitHub, and optional Ask Gitber remain explicit choices. Repository Blueprint still waits for Scan public source map, makes one exact public GitHub Tree request, and projects a bounded DOM/3D file-and-folder map. Its Blueprint Deep Link confirms the exact repo/path before loading, never guesses missing paths, and represents a source tree—not a call graph or runtime architecture. Gitber retains an isolated thread with up to five backend calls per visit, counting every started request; no other repository is substituted. Entry and document reading do not start a question.
• Returning visitors can see what changed. The Passport's Town Gazette compares the current public repository snapshot with the last one this browser marked as read. It then highlights new repositories, release tags when available, pushes, and positive metric growth. The comparison is entirely local and costs nothing.
• Repository connections are visible. The Stargazer's Observatory finds a genuine connection among three repositories that share topics or languages and draws it as a nighttime Constellation Trail.
• Every town introduces its creator. Town Creator Hall belongs to the active town owner—canonical, fork, or ?user= visitor—and combines an explicitly loaded public GitHub profile with the repositories already rendered in town. The hall highlights truthful stats, languages, earned badges, and three signature projects before crediting the upstream Repolis engine.
• Two developers can connect their towns. Twin Towns compares public repo metadata, finds shared languages or topics, and creates a recipient-specific link that can be followed in either direction—without login or a backend.
• Quiet maintenance gets its own light. The Observatory's Maintainers' Night Watch selects three recently maintained, low-star repositories from public metadata and asks visitors to light their lanterns. The Watch recognizes care regardless of popularity.
• Landmarks carry the project story. The Contribution Library archives papers, talks, open-source work, and awards. Chronopolis hosts the Council of Time. The plaza, observatory, park, and fairground make the city worth walking. At Petite-Venise, a boardable, low-profile ferry follows the real canal curve beneath the flower bridges for one scenic tour of the town.
• The World Tree anchors the skyline. It is a deterministic, code-native Three.js sculpture created with the threejs-sculpt-dna Copilot plugin, with rooted foliage, living motion, and tree-isolated bloom.

Ask the city

Guide	What to ask	How it answers
Gitber · POLARIS	“Take me to an AI agent repo” or “most cloned”	uses local indexed search by default, then drives to the selected house
VEGA · Archivist	Azure, .NET, Copilot, Microsoft products	grounded Microsoft Learn search with references
RIGEL · Cartographer	how a public repository works	grounded DeepWiki exploration
MIRA · Timekeeper	current library APIs and version-specific examples	direct Context7 lookup; roams the Library district
LYRA · Forgemaster	public models, datasets, and ML papers	direct Hugging Face search; roams the AI district
Council of Time	a technical trade-off or disputed claim	curated, deterministic verdicts, plus an optional live debate clearly marked as unverified

The town works without a backend. Local search is instant and keyless. WebLLM provides optional in-browser inference. The live demo adds grounded answers and official public MCP lookups through a Cloudflare Worker. If those services are unavailable, the town falls back to Local search or solo play.

Run in 60 seconds

git clone https://github.com/hyeonsangjeon/Repolis
cd Repolis
python3 -m http.server 8000 --protocol HTTP/1.1   # HTTP/1.1 keeps the burst of module loads from being reset
# open http://localhost:8000

No installation or build step is required. Three.js is loaded from a CDN import map, while local data and modules are served as static files.

To rebuild the owner's city from GitHub data and collected traffic history:

gh auth login
GTM_DIR=data python3 scripts/build_repos.py

repos.json is generated. Edit the builder instead of changing the generated JSON by hand.

Build your own city

The quickest preview requires no fork. Open Build my city, share https://hyeonsangjeon.github.io/Repolis/?user=<login>, enter the English owner plaza with ?view=plaza&lang=en, point one project at https://hyeonsangjeon.github.io/Repolis/?repo=<owner>/<repo>&ref=repo-portal, or enter its exhibition directly with ?repo=<owner>/<repo>&view=atelier&lang=en.

To publish a persistent city built from repository metadata:

1. Click Use this template.
2. Enable Actions, then configure GitHub Pages to publish from the root of main.
3. Run Refresh Repolis data once. The workflow uses github.token to build the city from the template owner's public repositories and then runs daily.
4. Optionally, add an Actions secret named GH_PAT to collect cumulative traffic. Without it, stars, forks, recency, language, topics, and releases still shape the city.

Only public repositories are rendered. Unmodified mirror forks are filtered out, and private repository names never enter the public data.

Architecture

traffic history + GitHub API
             │
             ▼
 scripts/build_repos.py ──▶ repos.json
                                │
                                ▼
                    index.html + local modules
                         Three.js town
                         ├─ Local search
                         ├─ optional grounded AI Worker
                         └─ optional realtime Worker

Repolis remains a zero-build static web app. Its main runtime lives in index.html. Specialized local files contain generated data, the scholar roster, the World Tree factory, and deterministic Council logic.

Path	Purpose
index.html	3D world, UI, navigation, residents, exploration, i18n
repolis.config.js	fork owner inference and safe optional-service defaults
repos.json	generated repository and traffic data
scholars.js	scholar roster
assets/repo-portal.js	strict target parsing, public projection, and canonical repository links
assets/town-growth.js	deterministic repo-birth timeline, year snapshots, and share links
assets/world-tree/	procedural World Tree factory
cloudflare-taxi/	grounded AI and optional resident dialogue Worker
cloudflare/	realtime presence Worker
council/	deterministic Council engine and guards
scripts/	data builders and regression checks

Optional services

Capability	Setup
Grounded taxi and scholars	cloudflare-taxi/README.md
Realtime visitors and counters	cloudflare/README.md
Vercel taxi alternatives	api/ and .env.example
Copy-paste integrations	examples/

Controls

Input	Action
W A S D, arrows, or left touch stick	walk
mouse drag or right touch stick	look and turn
wheel	zoom
Enter, click, or the mobile door button	open the nearby place
taxi button	ask Gitber
menu / map / passport buttons	navigate, track exploration, and replay the town's growth
language and sun/moon buttons	switch language and time of day

Documentation

• AGENTS.md — contributor and agent operating contract
• docs/domain-model.md — repository data and feature model
• docs/repo-portal-change-guide.md — Repo Portal URL, data, cache, privacy, and maintenance contract
• docs/known-limitations.md — intentional constraints
• SCHOLARS.md — scholar roster and grounding roles
• COUNCIL_PATTERN.md — the debate-to-judge pattern
• CHANGELOG.md — recent releases and archive links
• repolis.yaml / llms.txt — machine-readable project entry points

License

MIT © Hyeonsang Jeon. Data collection credit: github-traffic-monitor.