CODE//CITY

Spatial Code Intelligence — Software Architecture Translated into Modular Voxel Brutalism.

CODE//CITY turns any public GitHub repository into an interactive, explorable 3D voxel city. Software architecture is materialized into physical, computational matter—combining data visualization, static AST dependency analysis, and high-performance WebGL rendering.

---

🏛️ 1. Conceptual Mapping: Code Has Mass

Repository             →  Voxel World
Top-Level Directory    →  District Platform
Nested Subfolder       →  Neighborhood Block
Source File            →  Voxel Mass / Building
Lines of Code (LOC)    →  Vertical Voxel Units (Logarithmic Normalized)
File Size / Weight     →  Base Footprint (1x1 to 4x4 Voxel Grid)
Centrality / Hub       →  Structural Prominence
Imports / Graph Edges  →  3D Quadratic Bézier Transit Arcs
Blast Radius           →  Staggered Reverse-Dependency Wave Propagation

---

🏗️ 2. Procedural Voxel Archetypes

Every file is analyzed and deterministically assigned one of six procedural voxel brutalist archetypes:

Archetype	Description	Deterministic Trigger
TOWER	Stepped landmark skyscraper with recessed crown and illuminated technical aperture slots	Entry points (index.ts, main.go), high centrality ($\ge 5$ connections)
STEPPED	3-tier ziggurat pyramid terraces with modular inset levels	High complexity ($>20$) or large code volume ($>250$ LOC)
MONOLITH	Dense concrete slab with vertical channel recesses and massive solid volume	Core runtime, compilers, servers, and backend engines
STACK	Modular cantilevered tiers with offset upper blocks	UI components, React/Vue modules (*.tsx, *.jsx)
TERRACE	Stepped horizontal terraces with tiered floor plates	Page routers, navigation layouts, and controller modules
PLINTH	Low technical utility base with recessed rooftop plate	Configuration files (package.json), type definitions (*.d.ts), tests

---

⚡ 3. Key Capabilities & Architecture

graph TD
    A[Universal GitHub URL Parser] --> B[Tree & Metadata Streamer]
    B --> C[Static AST & Import Alias Resolver]
    C --> D[Directed Architecture Graph & Cycle Detector]
    D --> E[Deterministic Voxel Layout Synthesizer]
    E --> F[Zustand Central Store]
    
    subgraph WebGL 3D Canvas
        F --> G1[GPU InstancedMesh Voxel Renderer with Micro-Gaps]
        F --> G2[3D Transit Rails with Sparse Animated Signals]
        F --> G3[Parabolic Camera Controller & Fly-To Arc]
        F --> G4[LOD Distance Labels & District Platforms]
    end

    subgraph Intelligence HUD
        F --> H1[Editorial Spec Sheet & Mobile Bottom Sheet]
        F --> H2[Ranked Spotlight Search ⌘K]
        F --> H3[Blast Radius Propagation Engine]
        F --> H4[In-App Repository Switcher Modal]
        F --> H5[Presentation & Screenshot Mode]
    end

Loading

🔍 Static AST & Alias Resolution

• Extracts static ES import, CommonJS require(), dynamic import(), re-exports (export * from ...), and CSS @import/@use.
• Resolves module aliases seamlessly: @/*, ~/*, @components/*, @lib/*, @app/*, @core/*.
• Automatically guesses extensions (.ts, .tsx, .js, .jsx, .mjs, .json) and resolves directory index files.

🌐 Graph Builder & Tarjan Cycle Detection

• Constructs directed multi-graph tracking fan-in, fan-out, and betweenness centrality.
• Employs Tarjan's / DFS cycle detection to identify circular dependency loops across the architecture.

🔥 Mathematical Blast Radius Engine

• Performs Breadth-First Search (BFS) over the transposed import graph (following importedBy incoming edges).
• Computes impact reach percentage, affected districts, and architectural risk score (0–100).
• Illuminates impacted modules in staggered propagation waves ($T_0 \to T_1 \to T_2 \to T_3$) while dimming unaffected concrete masses.

🚀 High-Performance GPU Instancing

• Uses a unified GPU InstancedMesh with $0.96\times$ micro-gap scaling, producing authentic brutalist block seams with single-draw-call performance ($60\text{ FPS}$).
• $O(1)$ instance-to-building raycasting picking for instant hover (120–180ms) and click selection.

🎥 Parabolic Camera Controller

• Transitions elevate vertically midway through travel ($y(t) = \text{lerp}(y_0, y_1, t) + \sin(\pi t) \times h_{arc}$) before smoothly settling at the destination.
• Focus distance dynamically adapts to target building height and bounding box.
• Multi-stage ESC keyboard navigation:
  • 1st ESC: Deselect active building.
  • 2nd ESC: Reset district focus and return to macro city overview.
  • 3rd ESC: Reset camera position.

---

🕹️ 4. Navigation & Shortcuts

Key / Action	Function
Click Building	Select building, trigger single-shot ring pulse, open Spec Sheet Inspector
⌘K or /	Open Spotlight Command Palette with ranked fuzzy search
ESC	Multi-stage escape (Deselect building $\to$ Overview $\to$ Reset camera)
Left Click + Drag	Orbit camera around city
Right Click + Drag	Pan camera
Scroll Wheel / Pinch	Zoom in / out (bounded to prevent ground clipping)
Camera Icon	Toggle Presentation / Screenshot mode (hides HUD)

---

📦 5. Getting Started

Prerequisites

• Node.js 18.x or 20.x
• npm, pnpm, or yarn

Installation

# Clone repository
git clone https://github.com/ajdohaxhia/citycode.git
cd citycode

# Install dependencies
npm install

# Run automated verification test suite
npm test

# Run TypeScript type check
npm run typecheck

# Start local development server
npm run dev

Open http://localhost:3000 in your browser.

---

🧪 6. Curated Benchmark Models

CODE//CITY includes zero-latency bundled benchmark datasets:

• Next.js (vercel/next.js): http://localhost:3000/repo/vercel/next.js
• React (facebook/react): http://localhost:3000/repo/facebook/react
• React Three Fiber (pmndrs/react-three-fiber): http://localhost:3000/repo/pmndrs/react-three-fiber
• CODE//CITY (Recursive Self-Model): http://localhost:3000/repo/codecity/codecity

---

🛠️ 7. Tech Stack

• Framework: Next.js 14 (App Router, Server Components & Dynamic API Routes)
• UI Engine: React 18.3.1
• 3D & WebGL: Three.js, @react-three/fiber, @react-three/drei, @react-three/postprocessing
• State Management: Zustand 5
• Styling: Tailwind CSS 3.4
• Icons: Lucide React
• Testing: TSX Test Runner

☁️ 8. Cloudflare Pages Deployment

CODE//CITY is fully configured for zero-configuration Edge deployment on Cloudflare Pages.

One-Click Cloudflare Pages Setup:

1. Connect your GitHub repository (https://github.com/ajdohaxhia/citycode.git) in the Cloudflare Dashboard.
2. Select Pages → Create a project → Connect to Git.
3. Set the build configuration:
   • Framework preset: None or Next.js
   • Build command: npm run pages:build (or npx @cloudflare/next-on-pages)
   • Build output directory: .vercel/output/static
   • Node.js Compatibility Flag: nodejs_compat
4. Deploy!

Local Cloudflare Preview:

# Build Cloudflare Pages edge worker output
npm run pages:build

# Preview with local Wrangler
npm run preview

---

📄 9. License

MIT License © 2026 CODE//CITY