• 

  03_2d_architecture_graph

• 

  02_holographic_3d_twin

• 

  04_ast_symbol_explorer

• 

  01_landing_page

• 

  06_patch_and_sandbox

• 

  07_institutional_audit_report

• 

  05_ai_investigation_studio

• 

  07_institutional_audit_report

🌌 BlackBox — AI Repository Decompiler & Neural Link Context Engine

Translating complex codebases into interactive 3D digital twins and persistent neural memory for AI coding agents.

💡 Inspiration

Every software engineer knows the steep cognitive penalty of landing on an unfamiliar, massive codebase: endless directory trees, hidden inter-module dependencies, undocumented architectural patterns, and fragmented mental models.

Even worse, today's AI coding assistants suffer from severe context amnesia. Every time a developer starts a task in Cursor, Windsurf, Claude Code, or Antigravity, they are forced to manually spoon-feed file paths, explain conventions, and reconstruct the architecture. If a task spans multiple agents, the context is lost completely.

We asked ourselves:

What if an AI could decompile any public Git repository or local codebase into an interactive 3D topological twin, perform deep AST-grounded architectural audits, and compile persistent, zero-loss memory packs (AGENTS.md) directly tailored for AI coding agents?

That vision became BlackBox.

🚀 What BlackBox Does

BlackBox solves the two most critical pain points in modern software engineering:

1. Instant Codebase Comprehension (Human-in-the-Loop)

   • Holographic 3D Digital Twin: Projects the entire codebase as a 3D spherical, cluster-aware topological universe where node size represents symbol complexity and edges visualize real import/call relationships.
   • 2D Dynamic Architecture Graph: Interactive dependency mapping with hierarchical module layout, live node filtering, and AST symbol navigation.
   • Live Change Impact Analysis: Evaluates the structural blast radius before a single line of code is edited, calculating risk scores: $$\text{Impact Score} = \min\left(100, 18 \cdot N_{\text{upstream}} + 5 \cdot N_{\text{downstream}}\right)$$
   • Institutional Audit Engine: Generates comprehensive 0–100 health grades, security findings, and exportable standalone HTML/JSON/Markdown reports.

2. Neural Link: Persistent Project Memory (Agent-in-the-Loop)

   • Zero-Loss Context Compiler: Synthesizes verified architectural summaries, conventions, test guidelines, and constraints into token-budgeted context packs.
   • Deterministic SHA-256 Fingerprinting: Detects codebase drift and warns agents when context is stale.
   • Multi-Agent Exporter: Exports standardized AGENTS.md compatible with Antigravity, Cursor, Windsurf, Codex, and Claude Code with a single click.

3. Autonomous AI Investigations & Sandboxed Patch Verification

   • Grounded reasoning powered by NVIDIA open models on Nebius Token Factory (nvidia/Nemotron-3-Ultra-550b-a55b and nvidia/Nemotron-3_5-Lightning).
   • Generates structured unified diff patches and executes safe verification in an isolated sandbox with strict command allowlists.

🛠️ How We Built It

We designed BlackBox as a high-performance, modular monolith engineered for maximum resilience and security:

• Inference Layer: Direct integration with Nebius Token Factory targeting state-of-the-art NVIDIA open models (nvidia/Nemotron-3-Ultra-550b-a55b and meta-llama/Meta-Llama-3.1-70B-Instruct), utilizing structured Pydantic response schemas and strict concurrency semaphores.
• Frontend: Next.js 16 (App Router) with React 19, TypeScript strict mode, Tailwind CSS v4, Lucide React, and interactive 3D rendering with Canvas/Three.js.
• Backend: FastAPI with asynchronous concurrency (uvicorn + asyncio), Pydantic v2 schemas, and Python AST / Tree-Sitter multi-language symbol parsers.
• Storage & Database:
  • Dual-mode database layer: Neon Managed PostgreSQL (asyncpg) for production and SQLite with automated schema migrations.
  • Storage factory supporting Cloudflare R2 (S3-compatible API) with strict boundary guards and safe temporary directory fallbacks.
• Task Pipeline: Dual-engine background worker using Upstash Serverless Redis task queues with instant, resilient in-process local fallback.
• Security & SSRF Hardening: Strict URL hostname validation blocking private network subnets (RFC 1918) and cloud metadata endpoints (169.254.169.254), path traversal shields, and archive bomb limits.

🥊 Challenges We Faced

1. Safe Multi-Language AST Parsing: Extracting meaningful call edges and symbol signatures without executing arbitrary user code required building an isolated static scanner that inspects Python and TypeScript/JavaScript ASTs deterministically.
2. Linux Container Permission Boundaries on Render: When cloning repositories on Linux container environments without root access, write permissions on /app failed. We engineered an adaptive filesystem fallback that automatically detects read-only roots and safely diverts to the system's globally writable temp directory (/tmp/blackbox_workspace).
3. Structured Model Enforcement Across High-Param LLMs: Ensuring NVIDIA open models reliably returned valid JSON with line-accurate unified diffs required strict system prompt composition, JSON schema mode enforcement, and recursive markdown fence sanitizers.
4. 3D Topological Clustering at Scale: Positioning hundreds of interconnected nodes in 3D space without visual clutter required implementing spherical multi-cluster orbital algorithms that group files by root module packages.

🏆 Accomplishments That We're Proud Of

• 29/29 Passing Backend Tests: Rigorous test suite covering AI mock adapters, SSRF security, AST parsers, Cloudflare R2 bounds, and 3D topology math.
• Flawless End-to-End Real Codebase Demo: Cloned, parsed, indexed, and investigated live public GitHub repositories (including real full-stack web applications) in under 30 seconds.
• Production-Grade Resilience: Built self-healing database enum migrations, dual-mode storage adapters, and zero-downtime container configuration.
• Aesthetic & Developer Experience: A futuristic cyberpunk dark-mode interface with holographic 3D physics, particle grids, and live impact indicators that developers actually enjoy using.

📚 What We Learned

• NVIDIA Open Models on Nebius provide exceptional inference speed and reasoning depth, matching or exceeding proprietary models when guided with grounded AST context.
• Code understanding is not just about LLM context size — structured topological indexing and call-graph evidence drastically reduce hallucinations and token waste.
• Standardized agent context handoff (AGENTS.md) is the future of collaborative software engineering.

🔮 What's Next for BlackBox

• Live Git Webhook Sync: Continuous incremental indexing whenever a GitHub pull request or commit lands.
• Multi-Repo Mesh Intelligence: Cross-repository reverse engineering for microservice ecosystems and monorepos.
• VS Code & JetBrains IDE Extension: Direct IDE sidebar showing real-time 3D call graphs and instant Neural Link context generation.
• Automated Regression Test Synthesis: Leveraging NVIDIA models to generate self-contained pytest and Vitest suites for proposed patches before sandbox execution.

Built With

• ai
• ast
• cloudflare-r2
• docker
• fastapi
• llama-3
• llm
• machine-learning
• nebius
• nemotron
• neon
• next.js
• nvidia
• postgresql
• python
• react
• redis
• reverse-engineering
• security
• tailwindcss
• three.js
• typescript
• upstash