# shiva-74/leadlens architecture

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

- Interactive diagram: https://gitdiagram.com/shiva-74/leadlens
- Repository: https://github.com/shiva-74/leadlens

## Overview

LeadLens is a real-estate sales copilot whose main workflow turns a form, pasted enquiry, or audio recording into a reviewed lead, AI analysis and explainable priority, then a follow-up action. The frontend provides queue and lead workspaces; the Express API orchestrates transcription, extraction, analysis, call preparation/debrief, chat, and persistence. PostgreSQL stores leads and activity. The README documents provider integrations and several product capabilities not visible in the sampled implementation; those are included as documented subsystems, with evidence limits reflected in the edges.

Main entry points: [`server/routes/api.ts`](https://github.com/shiva-74/leadlens/blob/main/server/routes/api.ts) (Lead API), [`src/pages/LeadDetailPage.tsx`](https://github.com/shiva-74/leadlens/blob/main/src/pages/LeadDetailPage.tsx) (Lead workspace), [`src/App.tsx`](https://github.com/shiva-74/leadlens/blob/main/src/App.tsx) (App routing), [`server/ai/index.ts`](https://github.com/shiva-74/leadlens/blob/main/server/ai/index.ts) (AI workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Sales workspace"]
  node_app["App routing<br/>[App.tsx]"]
  node_layout["Workspace navigation<br/>[Layout.tsx]"]
  node_new_lead["Lead capture<br/>[NewLeadPage.tsx]"]
  node_recorder["Audio recorder<br/>[VoiceRecorder.tsx]"]
  node_queue["Today's queue<br/>[QueuePage.tsx]"]
  node_all_leads["Lead list<br/>[AllLeadsPage.tsx]"]
  node_lead_detail["Lead workspace<br/>[LeadDetailPage.tsx]"]
  node_ui_components["Scoring display<br/>[ui.tsx]"]
  node_lead_actions["Follow-up links<br/>[actions.ts]"]
end

subgraph group_api["Lead services"]
  node_api_routes["Lead API<br/>[api.ts]"]
  node_session["Anonymous sessions<br/>[session.ts]"]
  node_rate_limit["Request limiting<br/>[rateLimit.ts]"]
end

subgraph group_intelligence["AI and voice"]
  node_ai_workflows["AI workflows<br/>[index.ts]"]
  node_ai_prompts["AI prompts<br/>[prompts.ts]"]
  node_ai_provider["Provider selection<br/>[provider.ts]"]
  node_ai_schemas["Structured outputs<br/>[schemas.ts]"]
  node_scoring["Priority scoring<br/>[scoring.ts]"]
  node_transcription["Audio transcription<br/>[index.ts]"]
end

subgraph group_data["Persistence and follow-up"]
  node_database[("PostgreSQL<br/>[index.ts]")]
  node_seed["Sample leads<br/>[seed.ts]"]
end

node_sales_user(("Sales team"))
node_text_ai{{"Text AI services"}}
node_audio_ai{{"Speech services"}}
node_calendar{{"Google Calendar"}}
node_whatsapp{{"WhatsApp"}}

node_sales_user -->|"uses"| node_app
node_app -->|"renders"| node_layout
node_app -->|"routes to"| node_queue
node_app -->|"routes to"| node_all_leads
node_app -->|"routes to"| node_new_lead
node_app -->|"routes to"| node_lead_detail
node_new_lead -->|"renders"| node_recorder
node_new_lead -->|"submits enquiry"| node_api_routes
node_recorder -->|"sends audio"| node_api_routes
node_api_routes -->|"transcribes audio"| node_transcription
node_transcription -->|"uses speech service"| node_audio_ai
node_api_routes -->|"requests extraction"| node_ai_workflows
node_api_routes -->|"requests analysis"| node_ai_workflows
node_ai_workflows -->|"generates outputs"| node_ai_provider
node_ai_workflows -->|"validates outputs"| node_ai_schemas
node_ai_workflows -->|"builds prompts"| node_ai_prompts
node_ai_workflows -->|"computes priority"| node_scoring
node_ai_provider -->|"calls providers"| node_text_ai
node_api_routes -->|"reads and writes"| node_database
node_api_routes -->|"creates samples"| node_seed
node_api_routes -->|"uses session"| node_session
node_api_routes -->|"limits requests"| node_rate_limit
node_queue -->|"loads priorities"| node_api_routes
node_all_leads -->|"loads leads"| node_api_routes
node_lead_detail -->|"manages lead"| node_api_routes
node_lead_detail -->|"renders scores"| node_ui_components
node_lead_detail -->|"requests call brief"| node_api_routes
node_lead_detail -->|"submits debrief"| node_api_routes
node_lead_detail -->|"asks lead chat"| node_api_routes
node_lead_actions -->|"creates visit link"| node_calendar
node_lead_actions -->|"opens follow-up"| node_whatsapp
node_lead_detail -->|"offers follow-up"| node_lead_actions

click node_app "https://github.com/shiva-74/leadlens/blob/main/src/App.tsx"
click node_layout "https://github.com/shiva-74/leadlens/blob/main/src/components/Layout.tsx"
click node_new_lead "https://github.com/shiva-74/leadlens/blob/main/src/pages/NewLeadPage.tsx"
click node_recorder "https://github.com/shiva-74/leadlens/blob/main/src/components/VoiceRecorder.tsx"
click node_queue "https://github.com/shiva-74/leadlens/blob/main/src/pages/QueuePage.tsx"
click node_all_leads "https://github.com/shiva-74/leadlens/blob/main/src/pages/AllLeadsPage.tsx"
click node_lead_detail "https://github.com/shiva-74/leadlens/blob/main/src/pages/LeadDetailPage.tsx"
click node_ui_components "https://github.com/shiva-74/leadlens/blob/main/src/components/ui.tsx"
click node_lead_actions "https://github.com/shiva-74/leadlens/blob/main/src/lib/actions.ts"
click node_api_routes "https://github.com/shiva-74/leadlens/blob/main/server/routes/api.ts"
click node_ai_workflows "https://github.com/shiva-74/leadlens/blob/main/server/ai/index.ts"
click node_ai_prompts "https://github.com/shiva-74/leadlens/blob/main/server/ai/prompts.ts"
click node_ai_provider "https://github.com/shiva-74/leadlens/blob/main/server/ai/provider.ts"
click node_ai_schemas "https://github.com/shiva-74/leadlens/blob/main/server/ai/schemas.ts"
click node_scoring "https://github.com/shiva-74/leadlens/blob/main/server/ai/scoring.ts"
click node_transcription "https://github.com/shiva-74/leadlens/blob/main/server/voice/index.ts"
click node_database "https://github.com/shiva-74/leadlens/blob/main/server/db/index.ts"
click node_seed "https://github.com/shiva-74/leadlens/blob/main/server/db/seed.ts"
click node_session "https://github.com/shiva-74/leadlens/blob/main/server/lib/session.ts"
click node_rate_limit "https://github.com/shiva-74/leadlens/blob/main/server/lib/rateLimit.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_app,node_layout,node_new_lead,node_recorder,node_queue,node_all_leads,node_lead_detail,node_ui_components,node_lead_actions toneBlue
class node_api_routes,node_session,node_rate_limit toneAmber
class node_ai_workflows,node_ai_prompts,node_ai_provider,node_ai_schemas,node_scoring,node_transcription toneMint
class node_database,node_seed toneRose
class node_sales_user,node_text_ai,node_audio_ai,node_calendar,node_whatsapp toneIndigo
```

## Components

### Sales workspace

- [App routing](https://github.com/shiva-74/leadlens/blob/main/src/App.tsx): `src/App.tsx`
- [Workspace navigation](https://github.com/shiva-74/leadlens/blob/main/src/components/Layout.tsx): `src/components/Layout.tsx`
- [Lead capture](https://github.com/shiva-74/leadlens/blob/main/src/pages/NewLeadPage.tsx): `src/pages/NewLeadPage.tsx`
- [Audio recorder](https://github.com/shiva-74/leadlens/blob/main/src/components/VoiceRecorder.tsx): `src/components/VoiceRecorder.tsx`
- [Today's queue](https://github.com/shiva-74/leadlens/blob/main/src/pages/QueuePage.tsx): `src/pages/QueuePage.tsx`
- [Lead list](https://github.com/shiva-74/leadlens/blob/main/src/pages/AllLeadsPage.tsx): `src/pages/AllLeadsPage.tsx`
- [Lead workspace](https://github.com/shiva-74/leadlens/blob/main/src/pages/LeadDetailPage.tsx): `src/pages/LeadDetailPage.tsx`
- [Scoring display](https://github.com/shiva-74/leadlens/blob/main/src/components/ui.tsx): `src/components/ui.tsx`
- [Follow-up links](https://github.com/shiva-74/leadlens/blob/main/src/lib/actions.ts): `src/lib/actions.ts`

### Lead services

- [Lead API](https://github.com/shiva-74/leadlens/blob/main/server/routes/api.ts): `server/routes/api.ts`
- [Anonymous sessions](https://github.com/shiva-74/leadlens/blob/main/server/lib/session.ts): `server/lib/session.ts`
- [Request limiting](https://github.com/shiva-74/leadlens/blob/main/server/lib/rateLimit.ts): `server/lib/rateLimit.ts`

### AI and voice

- [AI workflows](https://github.com/shiva-74/leadlens/blob/main/server/ai/index.ts): `server/ai/index.ts`
- [AI prompts](https://github.com/shiva-74/leadlens/blob/main/server/ai/prompts.ts): `server/ai/prompts.ts`
- [Provider selection](https://github.com/shiva-74/leadlens/blob/main/server/ai/provider.ts): `server/ai/provider.ts`
- [Structured outputs](https://github.com/shiva-74/leadlens/blob/main/server/ai/schemas.ts): `server/ai/schemas.ts`
- [Priority scoring](https://github.com/shiva-74/leadlens/blob/main/server/ai/scoring.ts): `server/ai/scoring.ts`
- [Audio transcription](https://github.com/shiva-74/leadlens/blob/main/server/voice/index.ts): `server/voice/index.ts`

### Persistence and follow-up

- [PostgreSQL](https://github.com/shiva-74/leadlens/blob/main/server/db/index.ts): `server/db/index.ts`
- [Sample leads](https://github.com/shiva-74/leadlens/blob/main/server/db/seed.ts): `server/db/seed.ts`

### Other components

- **Sales team**
- **Text AI services**
- **Speech services**
- **Google Calendar**
- **WhatsApp**

## Connections

- Sales team → App routing: uses (evidence: `README.md`)
- App routing → Workspace navigation: renders (evidence: `src/App.tsx`)
- App routing → Today's queue: routes to (evidence: `src/App.tsx`)
- App routing → Lead list: routes to (evidence: `src/App.tsx`)
- App routing → Lead capture: routes to (evidence: `src/App.tsx`)
- App routing → Lead workspace: routes to (evidence: `src/App.tsx`)
- Lead capture → Audio recorder: renders (evidence: `src/pages/NewLeadPage.tsx`)
- Lead capture → Lead API: submits enquiry (evidence: `README.md`)
- Audio recorder → Lead API: sends audio (evidence: `README.md`)
- Lead API → Audio transcription: transcribes audio (evidence: `server/routes/api.ts`)
- Audio transcription → Speech services: uses speech service (evidence: `README.md`)
- Lead API → AI workflows: requests extraction (evidence: `server/routes/api.ts`)
- Lead API → AI workflows: requests analysis (evidence: `server/routes/api.ts`)
- AI workflows → Provider selection: generates outputs (evidence: `server/ai/index.ts`)
- AI workflows → Structured outputs: validates outputs (evidence: `server/ai/index.ts`)
- AI workflows → AI prompts: builds prompts (evidence: `server/ai/index.ts`)
- AI workflows → Priority scoring: computes priority (evidence: `server/ai/index.ts`)
- Provider selection → Text AI services: calls providers (evidence: `README.md`)
- Lead API → PostgreSQL: reads and writes (evidence: `server/routes/api.ts`)
- Lead API → Sample leads: creates samples (evidence: `server/routes/api.ts`)
- Lead API → Anonymous sessions: uses session (evidence: `server/routes/api.ts`)
- Lead API → Request limiting: limits requests (evidence: `server/routes/api.ts`)
- Today's queue → Lead API: loads priorities (evidence: `README.md`)
- Lead list → Lead API: loads leads (evidence: `README.md`)
- Lead workspace → Lead API: manages lead (evidence: `server/routes/api.ts`)
- Lead workspace → Scoring display: renders scores (evidence: `src/pages/LeadDetailPage.tsx`)
- Lead workspace → Lead API: requests call brief (evidence: `README.md`)
- Lead workspace → Lead API: submits debrief (evidence: `server/routes/api.ts`)
- Lead workspace → Lead API: asks lead chat (evidence: `server/routes/api.ts`)
- Follow-up links → Google Calendar: creates visit link (evidence: `src/lib/actions.ts`)
- Follow-up links → WhatsApp: opens follow-up (evidence: `src/lib/actions.ts`)
- Lead workspace → Follow-up links: offers follow-up (evidence: `README.md`)