# dukeabaddon/deepsight architecture

> Architecture diagram of the GitHub repository dukeabaddon/deepsight, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dukeabaddon/deepsight
- Repository: https://github.com/dukeabaddon/deepsight

## Overview

DeepSight is a local-first MCP server and dashboard for turning an application codebase into runnable Playwright tests and actionable reports. Its primary workflow scans routes and code, optionally incorporates a PRD, plans tests, generates specs, runs them against the user’s app, reports failures, and supports repair and reruns. The graph also includes the dashboard shortcut, local analysis state, and optional LLM providers. Tool registration and selected orchestration are evidenced by excerpts and README; unsampled tool internals are represented at their exact source paths, with uncertain calls omitted.

Main entry points: [`src/index.ts`](https://github.com/dukeabaddon/deepsight/blob/main/src/index.ts) (MCP server), [`src/utils/projectScan.ts`](https://github.com/dukeabaddon/deepsight/blob/main/src/utils/projectScan.ts) (Project scan), [`src/utils/scaffoldPipeline.ts`](https://github.com/dukeabaddon/deepsight/blob/main/src/utils/scaffoldPipeline.ts) (Pipeline orchestration), [`src/tools/dashboardApi.ts`](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/dashboardApi.ts) (Dashboard API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_mcp["MCP server<br/>[index.ts]"]
  node_dashboard["Web dashboard<br/>[dashboard.ts]"]
  node_dashboard_api["Dashboard API<br/>[dashboardApi.ts]"]
end

subgraph group_planning["Analysis and planning"]
  node_analysis_tool["Codebase analysis<br/>[analyzeCodebase.ts]"]
  node_project_scan["Project scan<br/>[projectScan.ts]"]
  node_inventory["Project inventory"]
  node_next_routes["Next route discovery<br/>[nextAppRouter.ts]"]
  node_function_analysis["Function entities"]
  node_planning_context["Planning context<br/>[planningContext.ts]"]
  node_prd_parse["PRD parsing<br/>[parsePrd.ts]"]
  node_prd["PRD generation<br/>[prd.ts]"]
  node_test_plan["Test planning"]
  node_frontend_plan["Frontend test plan<br/>[testPlan.ts]"]
  node_code_summary["Code summary<br/>[codeSummary.ts]"]
end

subgraph group_execution["Test execution"]
  node_spec_generation["Spec generation"]
  node_scaffold["Pipeline orchestration"]
  node_test_run["Test execution<br/>[runTests.ts]"]
  node_playwright_runner["Playwright runner"]
  node_report_tool["Test reporting<br/>[getTestReport.ts]"]
  node_report_utils["Report generation<br/>[report.ts]"]
  node_auto_heal["Failure repair<br/>[autoHealTest.ts]"]
end

subgraph group_state["Local state and artifacts"]
  node_analysis_store[("Analysis store<br/>[analysisStore.ts]")]
  node_artifacts["Project artifacts<br/>[artifacts.ts]"]
end

subgraph group_integrations["External integrations"]
  node_llm{{"Configured LLM<br/>[llm.ts]"}}
end

node_ide(("IDE / MCP client"))
node_dashboard_user(("Dashboard user"))
node_app(("User application"))

node_ide -->|"calls tools"| node_mcp
node_mcp -->|"dispatches"| node_analysis_tool
node_mcp -->|"dispatches"| node_prd_parse
node_mcp -->|"dispatches"| node_test_plan
node_mcp -->|"dispatches"| node_spec_generation
node_mcp -->|"dispatches"| node_test_run
node_mcp -->|"dispatches"| node_report_tool
node_mcp -->|"dispatches"| node_auto_heal
node_dashboard_user -->|"uses"| node_dashboard
node_dashboard -->|"routes requests"| node_dashboard_api
node_dashboard_api -->|"runs workflow"| node_scaffold
node_analysis_tool -->|"scans project"| node_project_scan
node_project_scan -->|"lists files"| node_inventory
node_project_scan -->|"discovers routes"| node_next_routes
node_analysis_tool -->|"extracts entities"| node_function_analysis
node_analysis_tool -->|"stores analysis"| node_analysis_store
node_planning_context -->|"loads analysis"| node_analysis_store
node_prd_parse -->|"loads context"| node_planning_context
node_test_plan -->|"loads context"| node_planning_context
node_code_summary -->|"summarizes scan"| node_project_scan
node_prd -->|"uses scan"| node_project_scan
node_test_plan -.->|"generates plan"| node_llm
node_prd -.->|"generates PRD"| node_llm
node_scaffold -->|"scans project"| node_project_scan
node_scaffold -->|"runs tests"| node_playwright_runner
node_scaffold -->|"generates report"| node_report_utils
node_spec_generation -->|"writes specs"| node_artifacts
node_scaffold -->|"writes artifacts"| node_artifacts
node_test_run -->|"runs tests"| node_playwright_runner
node_playwright_runner -->|"sends browser requests"| node_app
node_report_tool -->|"builds report"| node_report_utils
node_auto_heal -->|"uses failures"| node_report_tool
node_auto_heal -->|"patches specs"| node_artifacts
node_dashboard_api -->|"reads and writes"| node_analysis_store
node_dashboard_api -->|"targets endpoint"| node_app

click node_mcp "https://github.com/dukeabaddon/deepsight/blob/main/src/index.ts"
click node_dashboard "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/dashboard.ts"
click node_dashboard_api "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/dashboardApi.ts"
click node_analysis_tool "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/analyzeCodebase.ts"
click node_project_scan "https://github.com/dukeabaddon/deepsight/blob/main/src/utils/projectScan.ts"
click node_inventory "https://github.com/dukeabaddon/deepsight/blob/main/src/utils/projectInventory.ts"
click node_next_routes "https://github.com/dukeabaddon/deepsight/blob/main/src/utils/nextAppRouter.ts"
click node_function_analysis "https://github.com/dukeabaddon/deepsight/blob/main/src/analyzer/functionCountStub.ts"
click node_planning_context "https://github.com/dukeabaddon/deepsight/blob/main/src/lib/planningContext.ts"
click node_prd_parse "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/parsePrd.ts"
click node_prd "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/prd.ts"
click node_test_plan "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/generateTestPlan.ts"
click node_frontend_plan "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/testPlan.ts"
click node_code_summary "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/codeSummary.ts"
click node_spec_generation "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/generateTestCode.ts"
click node_scaffold "https://github.com/dukeabaddon/deepsight/blob/main/src/utils/scaffoldPipeline.ts"
click node_test_run "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/runTests.ts"
click node_playwright_runner "https://github.com/dukeabaddon/deepsight/blob/main/src/utils/playwrightRunner.ts"
click node_report_tool "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/getTestReport.ts"
click node_report_utils "https://github.com/dukeabaddon/deepsight/blob/main/src/utils/report.ts"
click node_auto_heal "https://github.com/dukeabaddon/deepsight/blob/main/src/tools/autoHealTest.ts"
click node_analysis_store "https://github.com/dukeabaddon/deepsight/blob/main/src/db/analysisStore.ts"
click node_artifacts "https://github.com/dukeabaddon/deepsight/blob/main/src/utils/artifacts.ts"
click node_llm "https://github.com/dukeabaddon/deepsight/blob/main/src/llm.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_dashboard,node_dashboard_api,node_ide,node_dashboard_user,node_app toneBlue
class node_analysis_tool,node_project_scan,node_inventory,node_next_routes,node_function_analysis,node_planning_context,node_prd_parse,node_prd,node_test_plan,node_frontend_plan,node_code_summary toneAmber
class node_spec_generation,node_scaffold,node_test_run,node_playwright_runner,node_report_tool,node_report_utils,node_auto_heal toneMint
class node_analysis_store,node_artifacts toneRose
class node_llm toneIndigo
```

## Components

### User interfaces

- [MCP server](https://github.com/dukeabaddon/deepsight/blob/main/src/index.ts): `src/index.ts`
- [Web dashboard](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/dashboard.ts): `src/tools/dashboard.ts`
- [Dashboard API](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/dashboardApi.ts): `src/tools/dashboardApi.ts`

### Analysis and planning

- [Codebase analysis](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/analyzeCodebase.ts): `src/tools/analyzeCodebase.ts`
- [Project scan](https://github.com/dukeabaddon/deepsight/blob/main/src/utils/projectScan.ts): `src/utils/projectScan.ts`
- [Project inventory](https://github.com/dukeabaddon/deepsight/blob/main/src/utils/projectInventory.ts): `src/utils/projectInventory.ts`
- [Next route discovery](https://github.com/dukeabaddon/deepsight/blob/main/src/utils/nextAppRouter.ts): `src/utils/nextAppRouter.ts`
- [Function entities](https://github.com/dukeabaddon/deepsight/blob/main/src/analyzer/functionCountStub.ts): `src/analyzer/functionCountStub.ts`
- [Planning context](https://github.com/dukeabaddon/deepsight/blob/main/src/lib/planningContext.ts): `src/lib/planningContext.ts`
- [PRD parsing](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/parsePrd.ts): `src/tools/parsePrd.ts`
- [PRD generation](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/prd.ts): `src/tools/prd.ts`
- [Test planning](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/generateTestPlan.ts): `src/tools/generateTestPlan.ts`
- [Frontend test plan](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/testPlan.ts): `src/tools/testPlan.ts`
- [Code summary](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/codeSummary.ts): `src/tools/codeSummary.ts`

### Test execution

- [Spec generation](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/generateTestCode.ts): `src/tools/generateTestCode.ts`
- [Pipeline orchestration](https://github.com/dukeabaddon/deepsight/blob/main/src/utils/scaffoldPipeline.ts): `src/utils/scaffoldPipeline.ts`
- [Test execution](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/runTests.ts): `src/tools/runTests.ts`
- [Playwright runner](https://github.com/dukeabaddon/deepsight/blob/main/src/utils/playwrightRunner.ts): `src/utils/playwrightRunner.ts`
- [Test reporting](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/getTestReport.ts): `src/tools/getTestReport.ts`
- [Report generation](https://github.com/dukeabaddon/deepsight/blob/main/src/utils/report.ts): `src/utils/report.ts`
- [Failure repair](https://github.com/dukeabaddon/deepsight/blob/main/src/tools/autoHealTest.ts): `src/tools/autoHealTest.ts`

### Local state and artifacts

- [Analysis store](https://github.com/dukeabaddon/deepsight/blob/main/src/db/analysisStore.ts): `src/db/analysisStore.ts`
- [Project artifacts](https://github.com/dukeabaddon/deepsight/blob/main/src/utils/artifacts.ts): `src/utils/artifacts.ts`

### External integrations

- [Configured LLM](https://github.com/dukeabaddon/deepsight/blob/main/src/llm.ts): `src/llm.ts`

### Other components

- **IDE / MCP client**
- **Dashboard user**
- **User application**

## Connections

- IDE / MCP client → MCP server: calls tools
- MCP server → Codebase analysis: dispatches
- MCP server → PRD parsing: dispatches
- MCP server → Test planning: dispatches
- MCP server → Spec generation: dispatches
- MCP server → Test execution: dispatches
- MCP server → Test reporting: dispatches
- MCP server → Failure repair: dispatches
- Dashboard user → Web dashboard: uses
- Web dashboard → Dashboard API: routes requests
- Dashboard API → Pipeline orchestration: runs workflow
- Codebase analysis → Project scan: scans project
- Project scan → Project inventory: lists files
- Project scan → Next route discovery: discovers routes
- Codebase analysis → Function entities: extracts entities
- Codebase analysis → Analysis store: stores analysis
- Planning context → Analysis store: loads analysis
- PRD parsing → Planning context: loads context
- Test planning → Planning context: loads context
- Code summary → Project scan: summarizes scan
- PRD generation → Project scan: uses scan
- Test planning → Configured LLM: generates plan
- PRD generation → Configured LLM: generates PRD
- Pipeline orchestration → Project scan: scans project
- Pipeline orchestration → Playwright runner: runs tests
- Pipeline orchestration → Report generation: generates report
- Spec generation → Project artifacts: writes specs
- Pipeline orchestration → Project artifacts: writes artifacts
- Test execution → Playwright runner: runs tests
- Playwright runner → User application: sends browser requests
- Test reporting → Report generation: builds report
- Failure repair → Test reporting: uses failures
- Failure repair → Project artifacts: patches specs
- Dashboard API → Analysis store: reads and writes
- Dashboard API → User application: targets endpoint