# sugan-developerinnooryze-stack/leadryze_ai architecture

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

- Interactive diagram: https://gitdiagram.com/sugan-developerinnooryze-stack/leadryze_ai
- Repository: https://github.com/sugan-developerinnooryze-stack/leadryze_ai

## Overview

LeadRyze AI is a tenant-aware lead-generation and conversational AI service. Its main workflow accepts chat through the API, routes it to a lead agent, and uses agent logic, conversation state, context retrieval, and model providers to produce responses and capture leads. Separate branches support knowledge ingestion/search, product and booking tools, template analysis, and voice. The README documents the wider tool and provider capabilities; sampled excerpts establish only some internal calls, so uncertain wiring is omitted. The continuous voice worker is a separate process.

Main entry points: [`src/agents/base.agent.ts`](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/agents/base.agent.ts) (Base agent), [`src/agents/lead.agent.ts`](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/agents/lead.agent.ts) (Lead agent), [`src/app.ts`](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/app.ts) (Express application), [`src/rag/website-ingest.service.ts`](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/website-ingest.service.ts) (Website ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_app["Express application<br/>[app.ts]"]
  node_chat["Chat routes<br/>[chat.routes.ts]"]
  node_knowledge_api["Knowledge routes"]
  node_template_api["Template analysis route"]
  node_voice_api["Voice routes<br/>[voice.routes.ts]"]
end

subgraph group_agents["Conversation agents"]
  node_lead_agent["Lead agent<br/>[lead.agent.ts]"]
  node_base_agent["Base agent<br/>[base.agent.ts]"]
  node_agent_graph["Agent workflows<br/>[graph.ts]"]
  node_booking_shortcut["Booking shortcut"]
  node_agent_specialists["Specialist agents"]
  node_tools["Product and booking tools"]
  node_template_service["Template analysis"]
end

subgraph group_knowledge["Knowledge and retrieval"]
  node_knowledge_ingest["Website ingestion"]
  node_crawler["Website crawler<br/>[web-crawler.ts]"]
  node_rag_pipeline["RAG pipeline<br/>[pipeline.ts]"]
  node_dataset_index["Dataset index"]
  node_embeddings["Embeddings<br/>[embeddings.ts]"]
  node_qdrant[("Qdrant vector store<br/>[qdrant.client.ts]")]
end

subgraph group_integrations["Services and integrations"]
  node_session_memory["Conversation state"]
  node_redis[("Redis")]
  node_context["Context builder<br/>[context.builder.ts]"]
  node_backend["Backend client<br/>[backend.client.ts]"]
  node_llm["LLM provider layer<br/>[llm.provider.ts]"]
  node_guardrails["Moderation and limits"]
end

subgraph group_voice["Voice experience"]
  node_voice_registry["Speech provider registry<br/>[registry.ts]"]
  node_voice_worker["Voice worker<br/>[worker.ts]"]
  node_voice_llm["Voice lead adapter<br/>[lead-agent-llm.ts]"]
end

node_client(("Service caller"))
node_backend_service["LeadRyze backend"]
node_model_services["LLM providers"]
node_speech_services["Speech services"]

node_client -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_chat
node_app -->|"mounts routes"| node_knowledge_api
node_app -->|"mounts routes"| node_template_api
node_app -->|"mounts routes"| node_voice_api
node_chat -->|"runs agent"| node_lead_agent
node_chat -->|"dispatches requests"| node_agent_specialists
node_lead_agent -->|"delegates turns"| node_base_agent
node_lead_agent -->|"builds context"| node_context
node_lead_agent -.->|"reads state"| node_session_memory
node_base_agent -->|"reads and writes"| node_session_memory
node_base_agent -->|"checks shortcut"| node_booking_shortcut
node_base_agent -->|"requests completions"| node_llm
node_base_agent -->|"retrieves knowledge"| node_rag_pipeline
node_base_agent -->|"applies checks"| node_guardrails
node_base_agent -.->|"invokes tools"| node_tools
node_context -->|"loads tenant context"| node_backend
node_backend -->|"calls internal API"| node_backend_service
node_session_memory -->|"stores session state"| node_redis
node_llm -->|"uses providers"| node_model_services
node_knowledge_api -->|"ingests and searches"| node_rag_pipeline
node_knowledge_api -->|"indexes datasets"| node_dataset_index
node_knowledge_api -->|"starts website crawl"| node_knowledge_ingest
node_knowledge_ingest -->|"crawls pages"| node_crawler
node_knowledge_ingest -->|"ingests chunks"| node_rag_pipeline
node_knowledge_ingest -->|"updates crawl status"| node_backend
node_knowledge_ingest -->|"tracks crawl status"| node_session_memory
node_rag_pipeline -->|"embeds text"| node_embeddings
node_rag_pipeline -->|"searches and writes"| node_qdrant
node_dataset_index -->|"embeds records"| node_embeddings
node_dataset_index -->|"indexes and searches"| node_qdrant
node_template_api -->|"analyzes templates"| node_template_service
node_voice_api -->|"resolves providers"| node_voice_registry
node_voice_api -->|"runs transcript"| node_lead_agent
node_voice_registry -.->|"selects speech APIs"| node_speech_services
node_voice_worker -->|"runs voice agent"| node_voice_llm
node_voice_llm -->|"uses lead agent"| node_lead_agent
node_voice_worker -->|"reports usage"| node_backend

click node_app "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/app.ts"
click node_chat "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/api/chat.routes.ts"
click node_knowledge_api "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/api/knowledge.routes.ts"
click node_template_api "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/api/template-analysis.routes.ts"
click node_voice_api "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/api/voice.routes.ts"
click node_lead_agent "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/agents/lead.agent.ts"
click node_base_agent "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/agents/base.agent.ts"
click node_agent_graph "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/agents/graph.ts"
click node_booking_shortcut "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/agents/booking-confirmation-shortcut.ts"
click node_agent_specialists "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/tree/main/src/agents"
click node_session_memory "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/memory/conversation.memory.ts"
click node_context "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/services/context.builder.ts"
click node_backend "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/services/backend.client.ts"
click node_llm "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/core/model-abstraction/llm.provider.ts"
click node_guardrails "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/tree/main/src/core/guardrails"
click node_knowledge_ingest "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/website-ingest.service.ts"
click node_crawler "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/web-crawler.ts"
click node_rag_pipeline "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/pipeline.ts"
click node_dataset_index "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/dataset-index.service.ts"
click node_embeddings "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/embeddings.ts"
click node_qdrant "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/qdrant.client.ts"
click node_tools "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/tree/main/src/tools"
click node_template_service "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/services/template-analysis.service.ts"
click node_voice_registry "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/voice/registry.ts"
click node_voice_worker "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/voice-agent/worker.ts"
click node_voice_llm "https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/voice-agent/lead-agent-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_app,node_chat,node_knowledge_api,node_template_api,node_voice_api toneBlue
class node_lead_agent,node_base_agent,node_agent_graph,node_booking_shortcut,node_agent_specialists,node_tools,node_template_service toneAmber
class node_knowledge_ingest,node_crawler,node_rag_pipeline,node_dataset_index,node_embeddings,node_qdrant toneMint
class node_session_memory,node_redis,node_context,node_backend,node_llm,node_guardrails toneRose
class node_voice_registry,node_voice_worker,node_voice_llm,node_client,node_backend_service,node_model_services,node_speech_services toneIndigo
```

## Components

### API and orchestration

- [Express application](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/app.ts): `src/app.ts`
- [Chat routes](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/api/chat.routes.ts): `src/api/chat.routes.ts`
- [Knowledge routes](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/api/knowledge.routes.ts): `src/api/knowledge.routes.ts`
- [Template analysis route](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/api/template-analysis.routes.ts): `src/api/template-analysis.routes.ts`
- [Voice routes](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/api/voice.routes.ts): `src/api/voice.routes.ts`

### Conversation agents

- [Lead agent](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/agents/lead.agent.ts): `src/agents/lead.agent.ts`
- [Base agent](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/agents/base.agent.ts): `src/agents/base.agent.ts`
- [Agent workflows](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/agents/graph.ts): `src/agents/graph.ts`
- [Booking shortcut](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/agents/booking-confirmation-shortcut.ts): `src/agents/booking-confirmation-shortcut.ts`
- [Specialist agents](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/tree/main/src/agents): `src/agents`
- [Product and booking tools](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/tree/main/src/tools): `src/tools`
- [Template analysis](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/services/template-analysis.service.ts): `src/services/template-analysis.service.ts`

### Knowledge and retrieval

- [Website ingestion](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/website-ingest.service.ts): `src/rag/website-ingest.service.ts`
- [Website crawler](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/web-crawler.ts): `src/rag/web-crawler.ts`
- [RAG pipeline](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/pipeline.ts): `src/rag/pipeline.ts`
- [Dataset index](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/dataset-index.service.ts): `src/rag/dataset-index.service.ts`
- [Embeddings](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/embeddings.ts): `src/rag/embeddings.ts`
- [Qdrant vector store](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/rag/qdrant.client.ts): `src/rag/qdrant.client.ts`

### Services and integrations

- [Conversation state](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/memory/conversation.memory.ts): `src/memory/conversation.memory.ts`
- **Redis**
- [Context builder](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/services/context.builder.ts): `src/services/context.builder.ts`
- [Backend client](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/services/backend.client.ts): `src/services/backend.client.ts`
- [LLM provider layer](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/core/model-abstraction/llm.provider.ts): `src/core/model-abstraction/llm.provider.ts`
- [Moderation and limits](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/tree/main/src/core/guardrails): `src/core/guardrails`

### Voice experience

- [Speech provider registry](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/voice/registry.ts): `src/voice/registry.ts`
- [Voice worker](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/voice-agent/worker.ts): `src/voice-agent/worker.ts`
- [Voice lead adapter](https://github.com/sugan-developerinnooryze-stack/leadryze_ai/blob/main/src/voice-agent/lead-agent-llm.ts): `src/voice-agent/lead-agent-llm.ts`

### Other components

- **Service caller**
- **LeadRyze backend**
- **LLM providers**
- **Speech services**

## Connections

- Service caller → Express application: sends requests
- Express application → Chat routes: mounts routes (evidence: `src/app.ts`)
- Express application → Knowledge routes: mounts routes (evidence: `src/app.ts`)
- Express application → Template analysis route: mounts routes (evidence: `src/app.ts`)
- Express application → Voice routes: mounts routes (evidence: `src/app.ts`)
- Chat routes → Lead agent: runs agent (evidence: `src/api/chat.routes.ts`)
- Chat routes → Specialist agents: dispatches requests (evidence: `src/api/chat.routes.ts`)
- Lead agent → Base agent: delegates turns (evidence: `src/agents/lead.agent.ts`)
- Lead agent → Context builder: builds context (evidence: `src/agents/lead.agent.ts`)
- Lead agent → Conversation state: reads state
- Base agent → Conversation state: reads and writes (evidence: `src/agents/base.agent.ts`)
- Base agent → Booking shortcut: checks shortcut (evidence: `src/agents/base.agent.ts`)
- Base agent → LLM provider layer: requests completions (evidence: `src/agents/base.agent.ts`)
- Base agent → RAG pipeline: retrieves knowledge (evidence: `src/agents/base.agent.ts`)
- Base agent → Moderation and limits: applies checks (evidence: `src/agents/base.agent.ts`)
- Base agent → Product and booking tools: invokes tools (evidence: `src/agents/base.agent.ts`)
- Context builder → Backend client: loads tenant context (evidence: `src/services/context.builder.ts`)
- Backend client → LeadRyze backend: calls internal API
- Conversation state → Redis: stores session state (evidence: `src/memory/conversation.memory.ts`)
- LLM provider layer → LLM providers: uses providers
- Knowledge routes → RAG pipeline: ingests and searches (evidence: `src/api/knowledge.routes.ts`)
- Knowledge routes → Dataset index: indexes datasets (evidence: `src/api/knowledge.routes.ts`)
- Knowledge routes → Website ingestion: starts website crawl (evidence: `src/api/knowledge.routes.ts`)
- Website ingestion → Website crawler: crawls pages (evidence: `src/rag/website-ingest.service.ts`)
- Website ingestion → RAG pipeline: ingests chunks (evidence: `src/rag/website-ingest.service.ts`)
- Website ingestion → Backend client: updates crawl status (evidence: `src/rag/website-ingest.service.ts`)
- Website ingestion → Conversation state: tracks crawl status (evidence: `src/rag/website-ingest.service.ts`)
- RAG pipeline → Embeddings: embeds text (evidence: `src/rag/pipeline.ts`)
- RAG pipeline → Qdrant vector store: searches and writes (evidence: `src/rag/pipeline.ts`)
- Dataset index → Embeddings: embeds records (evidence: `src/rag/dataset-index.service.ts`)
- Dataset index → Qdrant vector store: indexes and searches (evidence: `src/rag/dataset-index.service.ts`)
- Template analysis route → Template analysis: analyzes templates (evidence: `src/api/template-analysis.routes.ts`)
- Voice routes → Speech provider registry: resolves providers (evidence: `src/api/voice.routes.ts`)
- Voice routes → Lead agent: runs transcript (evidence: `src/api/voice.routes.ts`)
- Speech provider registry → Speech services: selects speech APIs
- Voice worker → Voice lead adapter: runs voice agent (evidence: `src/voice-agent/worker.ts`)
- Voice lead adapter → Lead agent: uses lead agent (evidence: `src/voice-agent/lead-agent-llm.ts`)
- Voice worker → Backend client: reports usage (evidence: `src/voice-agent/worker.ts`)
