🏙️ NexuCity — See the Change Before It Lives in Your Codebase

What I Built

Refactoring is often a slow, anxious job: search through a large repository, guess the blast radius, make a change, run the checks, and hope nothing important was missed.

NexuCity makes that work inspectable before it becomes risky. Connect a GitHub repository, let the deterministic analyzer turn its source into a structural graph, explore that graph as an interactive Twin City, then propose and rehearse a supported change inside an isolated workspace.

The goal is simple: let developers do less guesswork before touching code.

GitHub repository
        │  explicit import; source is parsed, not executed
        ▼
Normalized source graph
        ├── Twin City: explore files, symbols, routes, and relationships
        └── Governed agent: plan a supported change with Gemma + Mastra
                                      │
                                      ▼
                         Temporal approval checkpoint
                                      │
                                      ▼
                         Isolated rehearsal and evidence

The workflow

1. Connect a GitHub account and choose a repository.
2. Index explicit repository files into a normalized graph.
3. Explore relationships in the Twin City and Impact views.
4. Propose a change against a validated graph node.
5. Rehearse supported rename and Prisma scalar type_change operations in a temporary twin.
6. Review the plan, permit, diff, results, and audit records before any governed execution.

NexuCity does not merge, push, deploy, or perform unrestricted remediation. The indexed snapshot is never used as a write target.

Demo

• Repository: github.com/NivritiPandey/Nexucity-omni
• Web client: nexucity-omni.vercel.app
• API health endpoint: nexucity-api.onrender.com/health

The production entrypoint starts empty by design. Sign in with GitHub, import a repository, and then visit:

Route	What it shows
/	Workspace overview and repository summary
/twin	Three.js Twin City for the indexed graph
/impact	Search, relationships, and dependency inspection
/changes	Repository-scoped proposed changes
/rehearsal	Isolated rehearsal lifecycle and results
/agents	Plans, permits, approvals, and governed actions
/evidence	Returned change, rehearsal, and audit records

Code

NexuCity is a TypeScript npm-workspace monorepo:

apps/web/             React/Vite workspace UI and Twin City
packages/analyzer/    deterministic source analysis
packages/graph/       normalized graph models and traversal
packages/storage/     SQLite persistence
packages/api/         Fastify API, rehearsal, and governed execution
scripts/              release verification and runtime checks
ARCHITECTURE.md       package boundaries and safety limits
AUDIT_REPORT.md       audit evidence and operational follow-ups

How I Built It

Deterministic analysis first

The analyzer accepts explicit file content and produces structural data without executing repository code. That graph owns node identity, edges, repository scope, search, and traversal.

Gemma as a proposal, not an authority

The real agent path uses a configured OpenAI-compatible Gemma endpoint through Mastra. Gemma receives the relevant change, graph context, and allowed source context, then returns a structured plan. The model does not decide what it is allowed to touch.

Mastra for the tool boundary

Mastra coordinates the model and typed tools. Permits, protected paths, budgets, validation, and redaction remain application-owned controls.

Temporal for the pause

Agent execution is not a single unreviewable request. Temporal holds the workflow at a human approval checkpoint, then runs only the approved activity through the governed boundary.

A Twin City for lazy exploration

Files become buildings, symbols become towers, routes become gateways, and structural relationships become visible connections. Search and related-only filters let a developer focus on the part of the graph that matters.

Evidence instead of confidence theater

The workspace returns rehearsal results, permits, actions, reviews, rollbacks, and audit records. It does not turn an unavailable provider into a fake success or invent a risk score.

Why Does Open Innovation Matter?

Code is sensitive, and an agent that can edit a repository needs more than a clever prompt. Open models and open-source infrastructure make the important boundaries inspectable and replaceable.

Closed-only automation	NexuCity's open approach
Source must be sent to a vendor-controlled endpoint	Gemma can run locally or behind an endpoint the developer controls
The model's tool boundary is hidden in a product	Mastra tools, permits, path rules, and budgets are visible in the repository
Provider pricing and model availability determine the workflow	The model endpoint can be swapped without changing the graph or governance layers
A failed request can leave an unclear partial state	Temporal and the rehearsal boundary make approval and execution explicit
Trust depends on a polished answer	Source graph, rehearsal output, and audit records can be inspected

Open innovation did not just reduce the model bill. It made it possible to keep the safety-critical parts of this workflow understandable: what the model saw, what it proposed, what it was permitted to do, and what actually happened.

My Agent Session

This repository does not embed a private coding-agent transcript or claim a public session URL. The reproducible artifacts are the source tree, commit history, tests, release checks, architecture notes, and audit report.

The Lazy Payoff

NexuCity is for the developer who would rather inspect once than chase references all afternoon:

• Select a graph node instead of manually tracing every caller.
• See upstream and downstream relationships before editing.
• Rehearse a supported change without mutating the imported snapshot.
• Let Gemma draft a structured plan instead of starting from a blank issue.
• Keep a human approval checkpoint before governed execution.
• Review evidence instead of trusting an agent's claim that everything is fine.

The sloth-inspired principle is slow and steady before the first edit: spend a little time making the change legible, so the eventual implementation is less surprising.

Prize Categories

• 🦥 Slow and Steady: reduce the tiring manual work of code impact analysis and safe change planning.
• 🤖 Open-Source AI Core: Gemma, Mastra, and replaceable open tooling are part of the actual workflow.
• 🛠️ Developer Tools & Infrastructure: deterministic graphing, 3D code visualization, rehearsal, and durable approval orchestration.

Run It Locally

NexuCity uses Node 22.22.0 and npm workspaces:

nvm use 22.22.0
npm ci
npm run build

Start the API in local mode:

PORT=3001 NEXUCITY_API_MODE=local npm run dev

In another terminal, start the web client:

npm run dev:web

Open http://localhost:3000/signin. For real agent planning, configure a Gemma-compatible endpoint and Temporal separately; the local rule-based provider is retained only for isolated tests.

Useful checks:

npm test
npm run test:e2e
npm run build:web
npm run test:web
npm run verify:release

Boundaries

• Production starts without a sample repository; GitHub is the user-facing source connection.
• Sessions are currently process-local and require re-authentication after an API restart.
• Real agent execution requires configured Gemma and Temporal services.
• Rehearsal supports a deliberately narrow set of change types.
• WebGL 2 is required for the 3D view; the graph and inspector remain useful without it.
• This project does not claim unrestricted arbitrary-code sandboxing or production certification for hostile code.

Author

Built by @NivritiPandey for Hacktoberfest 2026 and the DEV Community.