Skip to content

Architecture

Jump to bottom
Manvendra Bhardwaj edited this page May 23, 2026 · 1 revision

Architecture

Services

The project consists of three independently running services:

Frontend — React application served via Vercel. The user interacts with this to upload a ZIP file and enter a debug prompt.

Backend — Node.js + Express server hosted on Render. Handles authentication, file upload, ZIP extraction, and runs the AI agent loop.

MCP Server — A separate Node.js server also hosted on Render. Exposes tools that the AI agent calls during debugging. Communicates with the Backend via SSE (Server-Sent Events).

Request Flow

  1. User uploads a ZIP file and a debug prompt from the frontend.
  2. Multer saves the ZIP to the uploads/ folder.
  3. AdmZip extracts the ZIP into extracted-projects/.
  4. The backend checks for a wrapper folder inside the extracted path and resolves the actual project root.
  5. The AI agent loop starts with the resolved project path and the user's prompt.
  6. Groq AI decides which MCP tool to call based on the prompt and previous results.
  7. The MCP client sends the tool call to the MCP Server via SSE.
  8. The MCP Server executes the tool against the extracted project and returns the result.
  9. The AI receives the result and decides the next action.
  10. Steps 6–9 repeat until the AI has enough information to give a final answer (maximum 20 tool calls).
  11. The final debug report is returned to the frontend and rendered as Markdown.

Key Design Decisions

Why MCP instead of direct tool calls? MCP is a standardized protocol that makes it easy to add, remove, or update tools without changing the agent logic. The agent only needs to know what tools are available — not how they work internally.

Why SSE instead of WebSockets? SSE is simpler and sufficient for this use case. The MCP Server only needs to send tool results back to the Backend — a unidirectional stream is enough.

Why ZIP upload instead of pasting code? Pasting code only gives the AI a fragment. A ZIP gives the AI the full project structure, which allows it to trace bugs across multiple files and understand how modules connect.

Why a 20 tool call limit? Without a limit, the agent could loop indefinitely on complex projects, wasting tokens and time. 20 calls is enough for most debugging tasks.

Why nodemon ignore config? When new files land in extracted-projects/ during a request, nodemon would restart the server mid-request without the ignore config. This caused requests to fail silently.

Clone this wiki locally