CodeNavigator/docs/ARCHITECTURE.md

Architecture

browser ──HTTP/SSE──▶ Go server (main.go, github.go) ──▶ indexer (indexer.go) ──▶ temp workspace
   │                        │
   │                        └── GitHub (OAuth token exchange, alerts API, git clone)
   └── WebGL2 frontend (web/): app.js · renderer.js · city.js · camera.js · labels.js

Server

One Go binary using only the standard library. The frontend is embedded with go:embed and served from the same origin as the API.

Indexing (indexer.go)

1. Walk the checkout in lexical order. Skip .git, node_modules, target, dist, build and .next, honour .ignore files everywhere and .gitignore inside git checkouts. Only regular files count (no symlinks).
2. Parse files in parallel (one worker per CPU). Binary files (a NUL byte in the first 4 KB) and files over 8 MB are skipped. For each file it records lines, bytes, a complexity score (branching tokens), the first 60 lines as a preview, definitions (class/struct/function patterns) and import targets (from/import/require/#include/use/using patterns). Each regex has a cheap literal prefilter, which made indexing about 3× faster than regex alone.
3. Link imports to files: relative paths first (known), then module-style names resolved by path suffix or file stem (inferred). Ambiguous names are never guessed.
4. Classify each file's language (by extension) and layer (test, vendor, generated, platform, library, docs or application) by path.

Sessions, jobs and snapshots (main.go)

• Sessions: a random cookie identifies each browser, and jobs, snapshots and GitHub tokens are owned by it.
• Jobs: a job is a GitHub clone or a local upload, reporting progress over SSE.
• Snapshots: each session keeps only its latest snapshot. Snapshots idle for an hour are expired, at most 8 are held (least recently used evicted), and at most 2 indexes run at once.
• Delivery: once the scene is sent, previews are released, and each source file is deleted after every line of it has been fetched.
• Workspace cleanup: only paths inside the workspace directory are ever deleted.

GitHub (github.go)

• Sign-in: the GitHub App user-authorisation flow. A single-use state is bound to the session, and the resulting user token is held in memory only (8-hour expiry).
• Clones pass the token as an HTTP header through GIT_CONFIG_* environment variables, never in arguments or URLs, with host git config and credential helpers disabled.
• Security alerts are fetched per request with the viewer's token, following pagination only on the API host.

Frontend (web/)

Plain ES modules, no framework, no build step.

Module	Responsibility
app.js	UI, input, data loading, 2D overlay canvas, city orchestration (signs, routes, residents, tour, links, alerts)
renderer.js	All WebGL2 drawing: instanced boxes, sign quads, route ribbons, particles, sprites
camera.js	Matrix maths: perspective, lookAt, inverse, orbit pose
city.js	Pure city logic, unit tested: layout, collision, navigation grid and routing, sign placement, tape, walls, posters, residents, place links
labels.js	Text atlas for signs (shelf-packed canvas) and the poster atlas
people.js	Residents' identities, generated deterministically from the repository name and resident index, plus the ID card portrait
api.mjs	fetch wrapper and SSE-over-fetch parser

Views

• 2D: squarified treemap in a 1000×680 world, orthographic. Source text is painted into an overview canvas when zoomed out, and into per-tile textures (LRU, 192 MB budget) when zoomed in.
• 3D: the same instances extruded, rendered through a perspective orbit camera. Roofs sample the overview canvas as a GPU texture, and only nearby roofs get sharp per-file textures.
• City: layoutCity lays the directory tree out in metres. Folders shrink by half a road on each side (18 m avenues between districts, narrower streets deeper down). Files become buildings, with footprint ≈ 1.1 m² per line and height 6 m + 10 m × log₂(1 + complexity).

City rendering passes (in order)

1. Floor: ground and folder pavements in nesting order, depth test off, top faces only (so nested pavements a few centimetres apart can't z-fight).
2. Buildings and wall: instanced boxes. The city shader adds procedural windows (lit share from definition count), neon edges, a concrete wall and exponential fog.
3. Effects: additive and never occluding. Search beacons, fire and smoke particles (stateless, animated in the vertex shader), residents (procedural stick-figure sprites), street routes (mitred ribbons with chevrons or pulsing dashes, kept in right-hand lanes) and import arcs.
4. Signs: textured quads from the label atlas, depth-tested but not depth-writing. A shader test discards any quad face that would read mirrored, which is how two-faced blade signs work.

Routing

• Grid: a 3 m occupancy grid blocks buildings (grown by 0.5 m) and the city wall, and makes pavements slightly dearer than roads.
• Search: one Dijkstra run from the selected building's doors reaches every import and dependent (paths cost the same both ways). It uses float64 distances and a settled set.
• Shaping: routes are straightened by line-of-sight, extended into both buildings, and boxed-in targets fall back to the nearest reachable street.