LegacyDecoder 🔍

Turn undocumented spaghetti code into living documentation in 30 seconds.

---

What it does

• Parses any legacy codebase (Python, JS, TS, PHP) using real AST analysis and regex fallback — no LLM required for structure extraction
• Understands every function with SIE (Superlinked Inference Engine): plain-English descriptions, dependency graphs, and risk classification (RED / AMBER / GREEN)
• Searches your codebase semantically — ask "find all payment code" and get vector-ranked results instantly, powered by Mubit persistent embeddings
• Publishes a formatted Notion page automatically via n8n webhook — full README, risk report, and per-file summaries, beautifully structured

---

Architecture

┌────────────────────────────────────────────────────────────────┐
│                        Browser (dashboard.html)                │
│  Upload ZIP / Paste files → Progress bar → Risk Heatmap        │
│  Semantic Search → README viewer → Push to Notion button       │
└──────────────────────┬─────────────────────────────────────────┘
                       │ HTTP (localhost:8000)
┌──────────────────────▼─────────────────────────────────────────┐
│                   FastAPI Backend (main.py)                     │
│                                                                 │
│  /decode ──► code_parser.py (ast + regex)                      │
│           ──► sie_client.py  ──► SIE Endpoint                  │
│                │  extract / embed / rerank / generate           │
│           ──► mubit_client.py ──► Mubit API (persist)          │
│           ◄── DecodeReport                                      │
│                                                                 │
│  /search  ──► sie_client.embed + cosine_similarity             │
│  /push-to-notion ──► N8N_WEBHOOK_URL                           │
└─────────────────────────────────────────────────────────────────┘
           │                              │
┌──────────▼──────────┐       ┌──────────▼──────────────────────┐
│   SIE Endpoint      │       │   n8n Workflow                   │
│  (Superlinked IE)   │       │  Webhook → Format Notion Blocks  │
│  extract / embed /  │       │  → Notion API → Respond          │
│  rerank / generate  │       └─────────────────────────────────┘
└─────────────────────┘
           │
┌──────────▼──────────┐
│   Mubit API         │
│  Persistent vector  │
│  store — instant    │
│  repeat queries     │
└─────────────────────┘

---

Partner Technologies

Partner	How LegacyDecoder uses it
SIE (Superlinked Inference Engine)	Core intelligence layer: extract_function_analysis generates plain-English descriptions + risk classification; embed_description converts descriptions to dense vectors; rerank_by_risk sorts functions by danger; generate_readme and generate_file_summary produce all documentation
n8n	Workflow automation: receives the full DecodeReport JSON via webhook, formats it into rich Notion blocks (callouts, toggles, tables, code blocks), POSTs to the Notion API, and returns the page URL
Aikido	Security scanning on the GitHub repository — connected manually via the Aikido dashboard after repo creation. Catches hardcoded secrets and dependency vulnerabilities in LegacyDecoder's own code
Mubit	Persistent vector memory: stores all function embeddings after first decode so identical codebases are returned instantly (cache hit path); enables cross-session semantic search without re-calling SIE

---

Quick Start

# 1. Clone
git clone https://github.com/your-username/legacydecoder
cd legacydecoder

# 2. Set up env
cp .env.example .env
# Fill in SIE_API_KEY, N8N_WEBHOOK_URL, NOTION_API_KEY, NOTION_PAGE_ID, MUBIT_API_KEY

# 3. Install Python deps
cd backend
python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 4. Start the API
uvicorn main:app --reload --port 8000

# 5. Open the dashboard
open ../frontend/dashboard.html
# Or: python -m http.server 3000 (from frontend/) and open localhost:3000

---

Environment Variables

Variable	Description
SIE_ENDPOINT	SIE inference endpoint URL (pre-filled in .env.example)
SIE_API_KEY	Your Superlinked API key (format: SL-...)
N8N_WEBHOOK_URL	Full URL of your n8n webhook trigger
NOTION_API_KEY	Notion integration token (starts with secret_)
NOTION_PAGE_ID	ID of the parent Notion page to create reports under
MUBIT_API_KEY	Your Mubit API key for persistent embedding storage

---

Try it with sample code

The repo includes three authentically messy legacy files for the live demo:

# Backend must be running (uvicorn main:app --reload --port 8000)

# Option A — via the dashboard
# Click "Load sample legacy code" in the browser → click "Decode Codebase"

# Option B — via curl
curl -X POST http://localhost:8000/decode \
  -H "Content-Type: application/json" \
  -d '{
    "files": {
      "auth.php": "'"$(cat sample_code/legacy_app/auth.php)"'",
      "payments.js": "'"$(cat sample_code/legacy_app/payments.js)"'",
      "utils.py": "'"$(cat sample_code/legacy_app/utils.py)"'"
    }
  }'

The sample code contains deliberately scary security issues (SQL injection, MD5 password hashing, hardcoded API keys, card details in GET requests) to make the risk heatmap dramatic during the demo.

---

How to import the n8n workflow

1. Open your n8n instance → Workflows → Import from File
2. Upload n8n/workflow.json
3. Set environment variables in n8n: NOTION_API_KEY, NOTION_PAGE_ID
4. Activate the workflow — note the Webhook URL it generates
5. Paste that URL into your .env as N8N_WEBHOOK_URL
6. Click Push to Notion in the dashboard — a formatted page appears in Notion

---

Use Cases

• Developer onboarding — a new joiner understands the entire codebase in minutes, not 1-3 days
• Tech debt audits — instantly surface every RED-risk function that needs refactoring before a major release
• Acquisition due diligence — assess the security posture of an acquisition target's codebase in one click
• Security reviews — find all authentication, payment, and data-handling code automatically, no grep required

---

Side Challenges

This project explicitly targets the following hackathon side challenges:

• Superlinked (SIE) Challenge — SIE is the primary intelligence layer for extraction, embedding, reranking, and generation. All four SIE capabilities are used on every decode request.
• n8n Challenge — n8n automates the entire Notion publishing workflow. The imported workflow (n8n/workflow.json) is a complete, production-ready automation with a Webhook trigger, a JavaScript formatting node, an HTTP Request to Notion, and a webhook response.
• Aikido Challenge — Aikido is connected to the GitHub repository to continuously scan LegacyDecoder's own code for vulnerabilities and hardcoded secrets. Setup is manual via the Aikido dashboard (no code changes needed).

---

API Reference

Endpoint	Method	Description
/health	GET	Liveness check
/decode	POST	Decode {"files": {"name": "content"}}
/decode-zip	POST	Decode a .zip file upload
/search	POST	Semantic search over SearchRequest
/push-to-notion	POST	Forward DecodeReport to n8n → Notion

Full OpenAPI docs available at http://localhost:8000/docs after starting the backend.