# gracker/smartperfetto architecture

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

- Interactive diagram: https://gitdiagram.com/gracker/smartperfetto
- Repository: https://github.com/gracker/smartperfetto
- Video tour (about a minute): https://gitdiagram.com/gracker/smartperfetto/video

## Overview

SmartPerfetto is an AI-assisted Perfetto trace-analysis product with Web, CLI, and HTTP/SSE entry points. Its principal workflow is to submit a trace question, run evidence-oriented agent analysis using trace processing and Skills, and present conclusions and reports. The README also documents capture, code and document knowledge, comparisons, critical-path and flamegraph views, and batch analysis. Edges are limited to relationships shown in excerpts, SOURCE INDEX references, or README statements; several documented capabilities have no sampled implementation details.

Main entry points: [`backend/src/agentRuntime/index.ts`](https://github.com/gracker/smartperfetto/blob/main/backend/src/agentRuntime/index.ts) (Agent runtime), [`backend/src/assistant/application/agentAnalyzeSessionService.ts`](https://github.com/gracker/smartperfetto/blob/main/backend/src/assistant/application/agentAnalyzeSessionService.ts) (Session services), [`backend/src/routes/agentRoutes.ts`](https://github.com/gracker/smartperfetto/blob/main/backend/src/routes/agentRoutes.ts) (Analysis routes), [`frontend/server.js`](https://github.com/gracker/smartperfetto/blob/main/frontend/server.js) (Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_web["Web UI<br/>[server.js]"]
  node_cli["CLI commands<br/>[analyze.ts]"]
  node_api["Analysis routes<br/>[agentRoutes.ts]"]
end

subgraph group_analysis["Trace analysis"]
  node_assistant["Session services"]
  node_runtime["Agent runtime<br/>[index.ts]"]
  node_scene["Scene analysis"]
  node_trace["Trace processor"]
  node_teaching["Rendering analysis"]
end

subgraph group_evidence["Evidence and knowledge"]
  node_skills["Skill registry<br/>[skillLoader.ts]"]
  node_code["Codebase lookup"]
  node_documents["Document knowledge"]
  node_kernel["Kernel ingestion"]
  node_rag[("RAG storage<br/>[ragStore.ts]")]
end

subgraph group_results["Results and exploration"]
  node_snapshot["Analysis snapshots"]
  node_comparison["Trace comparison"]
  node_critical["Critical path"]
  node_flamegraph["Flamegraph analysis<br/>[main.rs]"]
end

subgraph group_operations["Capture and administration"]
  node_ragadmin["Knowledge admin<br/>[ragAdminRoutes.ts]"]
  node_capture["Device capture<br/>[androidCapture.ts]"]
  node_batch["Batch analysis"]
end

node_users(("Analyst"))

node_users -->|"uses"| node_web
node_users -->|"uses"| node_cli
node_users -->|"integrates"| node_api
node_web -.->|"requests analysis"| node_api
node_cli -.->|"requests analysis"| node_api
node_api -->|"dispatches runs"| node_assistant
node_assistant -->|"invokes runtime"| node_runtime
node_assistant -->|"uses processor"| node_trace
node_runtime -.->|"analyzes scenes"| node_scene
node_runtime -.->|"uses Skills"| node_skills
node_skills -->|"generates detection Skill"| node_teaching
node_teaching -->|"queries trace"| node_trace
node_runtime -.->|"looks up source"| node_code
node_runtime -.->|"searches knowledge"| node_documents
node_kernel -->|"stores chunks"| node_rag
node_ragadmin -.->|"manages index"| node_rag
node_assistant -.->|"persists results"| node_snapshot
node_users -.->|"compares traces"| node_comparison
node_users -.->|"opens wait chain"| node_critical
node_users -.->|"views hotspots"| node_flamegraph
node_users -.->|"captures trace"| node_capture
node_users -.->|"analyzes batch"| node_batch

click node_web "https://github.com/gracker/smartperfetto/blob/main/frontend/server.js"
click node_cli "https://github.com/gracker/smartperfetto/blob/main/backend/src/cli-user/commands/analyze.ts"
click node_api "https://github.com/gracker/smartperfetto/blob/main/backend/src/routes/agentRoutes.ts"
click node_assistant "https://github.com/gracker/smartperfetto/blob/main/backend/src/assistant/application/agentAnalyzeSessionService.ts"
click node_runtime "https://github.com/gracker/smartperfetto/blob/main/backend/src/agentRuntime/index.ts"
click node_scene "https://github.com/gracker/smartperfetto/blob/main/backend/src/agent/scene/sceneStage1Runner.ts"
click node_trace "https://github.com/gracker/smartperfetto/blob/main/backend/src/services/traceProcessorService.ts"
click node_skills "https://github.com/gracker/smartperfetto/blob/main/backend/src/services/skillEngine/skillLoader.ts"
click node_teaching "https://github.com/gracker/smartperfetto/blob/main/backend/src/services/renderingPipelineTeachingService.ts"
click node_code "https://github.com/gracker/smartperfetto/blob/main/backend/src/services/codebase/onDemandSourceAccess.ts"
click node_documents "https://github.com/gracker/smartperfetto/blob/main/backend/src/services/knowledge/documentCollectionIngester.ts"
click node_kernel "https://github.com/gracker/smartperfetto/blob/main/backend/src/services/rag/kernelSourceIngester.ts"
click node_rag "https://github.com/gracker/smartperfetto/blob/main/backend/src/services/ragStore.ts"
click node_ragadmin "https://github.com/gracker/smartperfetto/blob/main/backend/src/routes/ragAdminRoutes.ts"
click node_snapshot "https://github.com/gracker/smartperfetto/blob/main/backend/src/services/analysisResultSnapshotPipeline.ts"
click node_comparison "https://github.com/gracker/smartperfetto/blob/main/backend/src/services/comparisonResultService.ts"
click node_critical "https://github.com/gracker/smartperfetto/blob/main/backend/src/services/criticalPathAnalyzer.ts"
click node_flamegraph "https://github.com/gracker/smartperfetto/blob/main/rust/flamegraph-analyzer/src/main.rs"
click node_capture "https://github.com/gracker/smartperfetto/blob/main/backend/src/cli-user/services/androidCapture.ts"
click node_batch "https://github.com/gracker/smartperfetto/blob/main/backend/src/services/batchTrace/batchTraceRunner.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_web,node_cli,node_api toneBlue
class node_assistant,node_runtime,node_scene,node_trace,node_teaching toneAmber
class node_skills,node_code,node_documents,node_kernel,node_rag toneMint
class node_snapshot,node_comparison,node_critical,node_flamegraph toneRose
class node_ragadmin,node_capture,node_batch,node_users toneIndigo
```

## Components

### User interfaces

- [Web UI](https://github.com/gracker/smartperfetto/blob/main/frontend/server.js): `frontend/server.js`
- [CLI commands](https://github.com/gracker/smartperfetto/blob/main/backend/src/cli-user/commands/analyze.ts): `backend/src/cli-user/commands/analyze.ts`
- [Analysis routes](https://github.com/gracker/smartperfetto/blob/main/backend/src/routes/agentRoutes.ts): `backend/src/routes/agentRoutes.ts`

### Trace analysis

- [Session services](https://github.com/gracker/smartperfetto/blob/main/backend/src/assistant/application/agentAnalyzeSessionService.ts): `backend/src/assistant/application/agentAnalyzeSessionService.ts`
- [Agent runtime](https://github.com/gracker/smartperfetto/blob/main/backend/src/agentRuntime/index.ts): `backend/src/agentRuntime/index.ts`
- [Scene analysis](https://github.com/gracker/smartperfetto/blob/main/backend/src/agent/scene/sceneStage1Runner.ts): `backend/src/agent/scene/sceneStage1Runner.ts`
- [Trace processor](https://github.com/gracker/smartperfetto/blob/main/backend/src/services/traceProcessorService.ts): `backend/src/services/traceProcessorService.ts`
- [Rendering analysis](https://github.com/gracker/smartperfetto/blob/main/backend/src/services/renderingPipelineTeachingService.ts): `backend/src/services/renderingPipelineTeachingService.ts`

### Evidence and knowledge

- [Skill registry](https://github.com/gracker/smartperfetto/blob/main/backend/src/services/skillEngine/skillLoader.ts): `backend/src/services/skillEngine/skillLoader.ts`
- [Codebase lookup](https://github.com/gracker/smartperfetto/blob/main/backend/src/services/codebase/onDemandSourceAccess.ts): `backend/src/services/codebase/onDemandSourceAccess.ts`
- [Document knowledge](https://github.com/gracker/smartperfetto/blob/main/backend/src/services/knowledge/documentCollectionIngester.ts): `backend/src/services/knowledge/documentCollectionIngester.ts`
- [Kernel ingestion](https://github.com/gracker/smartperfetto/blob/main/backend/src/services/rag/kernelSourceIngester.ts): `backend/src/services/rag/kernelSourceIngester.ts`
- [RAG storage](https://github.com/gracker/smartperfetto/blob/main/backend/src/services/ragStore.ts): `backend/src/services/ragStore.ts`

### Results and exploration

- [Analysis snapshots](https://github.com/gracker/smartperfetto/blob/main/backend/src/services/analysisResultSnapshotPipeline.ts): `backend/src/services/analysisResultSnapshotPipeline.ts`
- [Trace comparison](https://github.com/gracker/smartperfetto/blob/main/backend/src/services/comparisonResultService.ts): `backend/src/services/comparisonResultService.ts`
- [Critical path](https://github.com/gracker/smartperfetto/blob/main/backend/src/services/criticalPathAnalyzer.ts): `backend/src/services/criticalPathAnalyzer.ts`
- [Flamegraph analysis](https://github.com/gracker/smartperfetto/blob/main/rust/flamegraph-analyzer/src/main.rs): `rust/flamegraph-analyzer/src/main.rs`

### Capture and administration

- [Knowledge admin](https://github.com/gracker/smartperfetto/blob/main/backend/src/routes/ragAdminRoutes.ts): `backend/src/routes/ragAdminRoutes.ts`
- [Device capture](https://github.com/gracker/smartperfetto/blob/main/backend/src/cli-user/services/androidCapture.ts): `backend/src/cli-user/services/androidCapture.ts`
- [Batch analysis](https://github.com/gracker/smartperfetto/blob/main/backend/src/services/batchTrace/batchTraceRunner.ts): `backend/src/services/batchTrace/batchTraceRunner.ts`

### Other components

- **Analyst**

## Connections

- Analyst → Web UI: uses (evidence: `README.md`)
- Analyst → CLI commands: uses (evidence: `README.md`)
- Analyst → Analysis routes: integrates (evidence: `README.md`)
- Web UI → Analysis routes: requests analysis
- CLI commands → Analysis routes: requests analysis
- Analysis routes → Session services: dispatches runs (evidence: `backend/src/routes/agentRoutes.ts`)
- Session services → Agent runtime: invokes runtime (evidence: `backend/src/assistant/application/agentAnalyzeSessionService.ts`)
- Session services → Trace processor: uses processor (evidence: `backend/src/assistant/application/agentAnalyzeSessionService.ts`)
- Agent runtime → Scene analysis: analyzes scenes
- Agent runtime → Skill registry: uses Skills (evidence: `README.md`)
- Skill registry → Rendering analysis: generates detection Skill (evidence: `backend/src/services/skillEngine/skillLoader.ts`)
- Rendering analysis → Trace processor: queries trace (evidence: `backend/src/services/renderingPipelineTeachingService.ts`)
- Agent runtime → Codebase lookup: looks up source (evidence: `README.md`)
- Agent runtime → Document knowledge: searches knowledge (evidence: `README.md`)
- Kernel ingestion → RAG storage: stores chunks (evidence: `backend/src/services/rag/kernelSourceIngester.ts`)
- Knowledge admin → RAG storage: manages index (evidence: `backend/src/routes/ragAdminRoutes.ts`)
- Session services → Analysis snapshots: persists results
- Analyst → Trace comparison: compares traces (evidence: `README.md`)
- Analyst → Critical path: opens wait chain (evidence: `README.md`)
- Analyst → Flamegraph analysis: views hotspots (evidence: `README.md`)
- Analyst → Device capture: captures trace (evidence: `README.md`)
- Analyst → Batch analysis: analyzes batch (evidence: `README.md`)
