🚀 Deconstruct.ai

Understand any codebase visually, interactively, and intelligently.

Deconstruct.ai is an AI-powered reverse engineering platform that transforms unfamiliar codebases into an interactive learning experience. Instead of spending hours navigating thousands of lines of legacy code, simply upload a project ZIP and let Deconstruct automatically analyze, visualize, and explain the architecture step by step.

The platform parses the project structure, identifies execution entry points, analyzes application flow using the Google Gemini API, and generates synchronized architectural diagrams, interactive presentations, and contextual quizzes—all alongside the actual source code.

✨ Features

⚡ Fast Project Ingestion

Drag-and-drop project ZIP upload (up to 500MB via Vercel Blob)
Automatic extraction using adm-zip
Smart filtering of unnecessary directories:
- node_modules
- .git
- dist
- build
- .next
- other generated artifacts

🧠 AI-Powered Architecture Analysis

Generate a complete understanding of any codebase with Gemini.

Project overview
Folder hierarchy analysis
Execution flow detection
Entry point identification
Module relationships
Data flow explanation
Component dependency mapping
Predictable structured JSON outputs

💻 Dual-Panel Interactive Workspace

A synchronized learning environment.

Left Panel

VS Code–style file explorer
Read-only Monaco Editor
Syntax highlighting
File navigation
Line highlighting

Right Panel

Interactive React slides explaining:

Overall architecture
Individual modules
Function breakdowns
Component relationships
Business logic
Data flow
API interactions

🔄 Sync-to-Code Navigation

Every explanation is connected directly to the source.

Clicking a slide automatically:

Opens the correct file
Scrolls Monaco Editor
Highlights the responsible lines
Keeps explanation and code synchronized

🎓 AI-Generated Learning Quizzes

Improve understanding with automatically generated quizzes.

Features include:

Multiple choice questions
Architecture-based questions
Code comprehension challenges
Immediate feedback
Concept reinforcement

🛠 Tech Stack

Technology	Purpose
Next.js 15 (App Router)	Frontend & Backend Framework
React 19	User Interface
Tailwind CSS	Styling
shadcn/ui	UI Components
Monaco Editor	VS Code Editing Experience
Google Gemini API	AI Architecture Analysis
Vercel Blob	Object Storage (500MB+ uploads)
adm-zip	ZIP Extraction
TypeScript	Type Safety

📂 Project Workflow

Project ZIP
      │
      ▼
 ZIP Extraction
      │
      ▼
 File Filtering
      │
      ▼
 Codebase Parsing
      │
      ▼
 Gemini Architecture Analysis
      │
      ▼
 Structured JSON
      │
      ├─────────────┐
      ▼             ▼
 Monaco Editor   Interactive Slides
      │             │
      └──────┬──────┘
             ▼
     Sync-to-Line Navigation
             │
             ▼
      Learning Quizzes

🚀 Getting Started

Prerequisites

Before running the project, you'll need:

Node.js 18+
npm
Google Gemini API Key
Vercel Account (for Blob storage - auto-configured on deploy)

Get your API key from:

https://aistudio.google.com/app/apikey

📦 Installation

1. Clone the repository

git clone https://github.com/your-username/deconstruct-ai.git

cd deconstruct-ai

2. Install dependencies

npm install

3. Configure environment variables

Create a file named:

.env.local

Add:

# Required: Google Gemini API
GEMINI_API_KEY=your_actual_api_key_here

# Required for >4MB uploads: Vercel Blob
# Auto-created when you add Blob Storage in Vercel Dashboard
BLOB_READ_WRITE_TOKEN=vercel_blob_rw_xxx

Setting up Vercel Blob (Local Development)

Go to Vercel Dashboard → Storage → Create Database → Blob
Name it (e.g., deconstruct-uploads)
Copy the Read/Write Token (starts with vercel_blob_rw_)
Add to .env.local as BLOB_READ_WRITE_TOKEN

On Vercel Deploy

Blob Storage is auto-linked when you create it in the same Vercel project - no env vars needed.

4. Run the development server

npm run dev

5. Open the application

Visit:

http://localhost:3000

📁 Recommended Project Structure

deconstruct-ai/

├── app/
├── components/
├── lib/
├── services/
├── hooks/
├── utils/
├── public/
├── styles/
├── types/
├── .env.local
├── package.json
└── README.md

🎯 MVP Goals

Upload any codebase
Understand architecture instantly
Navigate visually
Learn module-by-module
Reduce onboarding time
Improve developer productivity

🔮 Future Roadmap

GitHub Repository Import

Analyze repositories directly from GitHub URLs.

Live Repository Sync

Automatically refresh analyses when repositories change.

AST Visualization

Interactive Abstract Syntax Tree exploration for multiple languages.

Dependency Graphs

Visualize imports, exports, and module relationships.

Call Graph Explorer

Understand function execution paths across the application.

AI Chat Assistant

Ask questions such as:

"How does authentication work?"

"Explain this API."

"Where is this state updated?"

"What calls this function?"

Custom Monaco Themes

Dark themes
Light themes
VS Code themes
Custom syntax colors

Multi-Language Support

Support for:

JavaScript
TypeScript
Python
Java
Go
Rust
C++
C#
PHP

🤝 Contributing

Deconstruct.ai is currently in active MVP development.

Once the initial release is completed, external contributions will be welcomed.

Future contributors will be able to work on:

New language parsers
Improved AI prompts
UI enhancements
Performance optimizations
Visualization tools
Documentation

📄 License

This project is licensed under the MIT License.

See the LICENSE file for details.

💡 Why Deconstruct.ai?

Every developer has experienced the frustration of opening an unfamiliar repository and wondering:

Where does the application start?
Which files matter?
How are modules connected?
Where does the data flow?
How do components communicate?

Deconstruct.ai answers these questions automatically, transforming complex codebases into an interactive learning experience that is visual, intuitive, and AI-powered.

⭐ If you find this project useful, consider giving it a star!

It helps support development and motivates future improvements.

Built with ❤️ using Next.js, Monaco Editor, Tailwind CSS, shadcn/ui, Google Gemini AI, and Vercel Blob.

One-click Deploy

Other Platforms

The app works on any Node.js hosting (Railway, Render, Fly.io, etc.) - set GEMINI_API_KEY and BLOB_READ_WRITE_TOKEN (from Vercel Blob or compatible S3).

Name		Name	Last commit message	Last commit date
app		app
components		components
lib		lib
scripts		scripts
types		types
utils		utils
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
components.json		components.json
drizzle.config.ts		drizzle.config.ts
middleware.ts		middleware.ts
neon.ts		neon.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation