# samruth-2005/supportlens-ai architecture

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

- Interactive diagram: https://gitdiagram.com/samruth-2005/supportlens-ai
- Repository: https://github.com/samruth-2005/supportlens-ai

## Overview

SupportLens AI guides a user from an IT issue report through diagnosis and one safe troubleshooting check at a time, then records a resolution or escalation. The analyze endpoint validates the request and delegates diagnosis to Gemini; the deterministic engine advances sessions from user-reported results. Session history is available through the store boundary. The README describes screenshot analysis and Supabase as capabilities or plans, but says they are not connected; those integrations are not shown as working. The route and component excerpts establish the main wiring; details of unsampled UI and storage internals are omitted.

Main entry points: [`app/api/troubleshoot/route.ts`](https://github.com/samruth-2005/supportlens-ai/blob/main/app/api/troubleshoot/route.ts) (Advance endpoint), [`app/api/analyze/route.ts`](https://github.com/samruth-2005/supportlens-ai/blob/main/app/api/analyze/route.ts) (Analyze endpoint), [`lib/store/index.ts`](https://github.com/samruth-2005/supportlens-ai/blob/main/lib/store/index.ts) (Session store boundary), [`lib/gemini.ts`](https://github.com/samruth-2005/supportlens-ai/blob/main/lib/gemini.ts) (Gemini client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_home["Issue entry page<br/>[page.tsx]"]
  node_issue["Issue input<br/>[IssueInput.tsx]"]
  node_sessionview["Troubleshooting view"]
  node_timeline["Session timeline"]
  node_history["History page<br/>[page.tsx]"]
end

subgraph group_api["API and workflow"]
  node_analyze["Analyze endpoint<br/>[route.ts]"]
  node_troubleshoot["Advance endpoint<br/>[route.ts]"]
  node_schemas["Request schemas<br/>[schemas.ts]"]
  node_engine["Transition engine<br/>[index.ts]"]
  node_catalog["Step catalog<br/>[catalog.ts]"]
  node_bootstrap["Session bootstrap<br/>[bootstrap.ts]"]
end

subgraph group_diagnosis["Diagnosis"]
  node_gemini["Gemini client<br/>[gemini.ts]"]
  node_prompts["Diagnosis prompts<br/>[prompts.ts]"]
  node_scenarios["Seeded scenarios<br/>[scenarios.ts]"]
end

subgraph group_state["Session state"]
  node_store["Session store boundary<br/>[index.ts]"]
  node_cookie["Durable cookie store<br/>[cookie.ts]"]
end

node_user(("Support requester"))
node_model{{"Gemini service"}}

node_user -->|"opens app"| node_home
node_home -->|"renders"| node_issue
node_issue -->|"submits issue"| node_analyze
node_analyze -->|"validates request"| node_schemas
node_analyze -->|"requests diagnosis"| node_gemini
node_gemini -->|"builds prompts"| node_prompts
node_gemini -->|"sends analysis"| node_model
node_gemini -->|"returns diagnosis"| node_analyze
node_analyze -->|"creates session"| node_engine
node_analyze -->|"creates session"| node_store
node_user -->|"reports check result"| node_sessionview
node_sessionview -->|"posts result"| node_troubleshoot
node_troubleshoot -->|"validates request"| node_schemas
node_troubleshoot -->|"loads or seeds"| node_bootstrap
node_troubleshoot -->|"loads session"| node_store
node_troubleshoot -->|"advances session"| node_engine
node_engine -->|"resolves next step"| node_catalog
node_troubleshoot -->|"saves session"| node_store
node_troubleshoot -->|"returns session"| node_sessionview
node_sessionview -->|"renders progress"| node_timeline
node_history -->|"lists sessions"| node_store
node_store -->|"exports implementation"| node_cookie

click node_home "https://github.com/samruth-2005/supportlens-ai/blob/main/app/page.tsx"
click node_issue "https://github.com/samruth-2005/supportlens-ai/blob/main/components/IssueInput.tsx"
click node_sessionview "https://github.com/samruth-2005/supportlens-ai/blob/main/components/TroubleshootingSession.tsx"
click node_timeline "https://github.com/samruth-2005/supportlens-ai/blob/main/components/SessionTimeline.tsx"
click node_history "https://github.com/samruth-2005/supportlens-ai/blob/main/app/history/page.tsx"
click node_analyze "https://github.com/samruth-2005/supportlens-ai/blob/main/app/api/analyze/route.ts"
click node_troubleshoot "https://github.com/samruth-2005/supportlens-ai/blob/main/app/api/troubleshoot/route.ts"
click node_schemas "https://github.com/samruth-2005/supportlens-ai/blob/main/lib/schemas.ts"
click node_engine "https://github.com/samruth-2005/supportlens-ai/blob/main/lib/engine/index.ts"
click node_catalog "https://github.com/samruth-2005/supportlens-ai/blob/main/lib/engine/catalog.ts"
click node_bootstrap "https://github.com/samruth-2005/supportlens-ai/blob/main/lib/engine/bootstrap.ts"
click node_gemini "https://github.com/samruth-2005/supportlens-ai/blob/main/lib/gemini.ts"
click node_prompts "https://github.com/samruth-2005/supportlens-ai/blob/main/lib/prompts.ts"
click node_scenarios "https://github.com/samruth-2005/supportlens-ai/blob/main/lib/demo/scenarios.ts"
click node_store "https://github.com/samruth-2005/supportlens-ai/blob/main/lib/store/index.ts"
click node_cookie "https://github.com/samruth-2005/supportlens-ai/blob/main/lib/store/cookie.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_home,node_issue,node_sessionview,node_timeline,node_history toneBlue
class node_analyze,node_troubleshoot,node_schemas,node_engine,node_catalog,node_bootstrap toneAmber
class node_gemini,node_prompts,node_scenarios,node_user toneMint
class node_store,node_cookie toneRose
class node_model toneIndigo
```

## Components

### User experience

- [Issue entry page](https://github.com/samruth-2005/supportlens-ai/blob/main/app/page.tsx): `app/page.tsx`
- [Issue input](https://github.com/samruth-2005/supportlens-ai/blob/main/components/IssueInput.tsx): `components/IssueInput.tsx`
- [Troubleshooting view](https://github.com/samruth-2005/supportlens-ai/blob/main/components/TroubleshootingSession.tsx): `components/TroubleshootingSession.tsx`
- [Session timeline](https://github.com/samruth-2005/supportlens-ai/blob/main/components/SessionTimeline.tsx): `components/SessionTimeline.tsx`
- [History page](https://github.com/samruth-2005/supportlens-ai/blob/main/app/history/page.tsx): `app/history/page.tsx`

### API and workflow

- [Analyze endpoint](https://github.com/samruth-2005/supportlens-ai/blob/main/app/api/analyze/route.ts): `app/api/analyze/route.ts`
- [Advance endpoint](https://github.com/samruth-2005/supportlens-ai/blob/main/app/api/troubleshoot/route.ts): `app/api/troubleshoot/route.ts`
- [Request schemas](https://github.com/samruth-2005/supportlens-ai/blob/main/lib/schemas.ts): `lib/schemas.ts`
- [Transition engine](https://github.com/samruth-2005/supportlens-ai/blob/main/lib/engine/index.ts): `lib/engine/index.ts`
- [Step catalog](https://github.com/samruth-2005/supportlens-ai/blob/main/lib/engine/catalog.ts): `lib/engine/catalog.ts`
- [Session bootstrap](https://github.com/samruth-2005/supportlens-ai/blob/main/lib/engine/bootstrap.ts): `lib/engine/bootstrap.ts`

### Diagnosis

- [Gemini client](https://github.com/samruth-2005/supportlens-ai/blob/main/lib/gemini.ts): `lib/gemini.ts`
- [Diagnosis prompts](https://github.com/samruth-2005/supportlens-ai/blob/main/lib/prompts.ts): `lib/prompts.ts`
- [Seeded scenarios](https://github.com/samruth-2005/supportlens-ai/blob/main/lib/demo/scenarios.ts): `lib/demo/scenarios.ts`

### Session state

- [Session store boundary](https://github.com/samruth-2005/supportlens-ai/blob/main/lib/store/index.ts): `lib/store/index.ts`
- [Durable cookie store](https://github.com/samruth-2005/supportlens-ai/blob/main/lib/store/cookie.ts): `lib/store/cookie.ts`

### Other components

- **Support requester**
- **Gemini service**

## Connections

- Support requester → Issue entry page: opens app
- Issue entry page → Issue input: renders
- Issue input → Analyze endpoint: submits issue
- Analyze endpoint → Request schemas: validates request
- Analyze endpoint → Gemini client: requests diagnosis
- Gemini client → Diagnosis prompts: builds prompts
- Gemini client → Gemini service: sends analysis
- Gemini client → Analyze endpoint: returns diagnosis
- Analyze endpoint → Transition engine: creates session
- Analyze endpoint → Session store boundary: creates session
- Support requester → Troubleshooting view: reports check result
- Troubleshooting view → Advance endpoint: posts result
- Advance endpoint → Request schemas: validates request
- Advance endpoint → Session bootstrap: loads or seeds
- Advance endpoint → Session store boundary: loads session
- Advance endpoint → Transition engine: advances session
- Transition engine → Step catalog: resolves next step
- Advance endpoint → Session store boundary: saves session
- Advance endpoint → Troubleshooting view: returns session
- Troubleshooting view → Session timeline: renders progress
- History page → Session store boundary: lists sessions
- Session store boundary → Durable cookie store: exports implementation