# dua-saeed641/resolvyn architecture

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

- Interactive diagram: https://gitdiagram.com/dua-saeed641/resolvyn
- Repository: https://github.com/dua-saeed641/resolvyn

## Overview

Resolvyn is an AI customer-support system that handles voice, chat, and email, while giving operators a live view and explicit human controls. Its main workflow is to receive a customer issue, perceive and judge it, recall relevant knowledge, choose a resolution, route work to a specialist, perform and verify actions, respond, and learn from the outcome. The repository also includes an Epsilon model-serving engine. The README documents the overall workflow and product capabilities; sampled source confirms selected decision, memory, persistence, and model boundaries, but not every runtime connection.

Main entry points: [`agents/graph.py`](https://github.com/dua-saeed641/resolvyn/blob/main/agents/graph.py) (Ticket orchestrator), [`backend/app/services/ticket_engine.py`](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/services/ticket_engine.py) (Ticket state machine), [`backend/app/api/telephony.py`](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/api/telephony.py) (Voice channel), [`backend/app/human_intelligence/human_service.py`](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/human_intelligence/human_service.py) (Human intelligence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["Customer channels"]
  node_web_channels["Chat interface<br/>[page.tsx]"]
  node_voice_channel["Voice channel<br/>[telephony.py]"]
  node_email_channel["Email support<br/>[email_service.py]"]
  node_voice_services["Speech services<br/>[speech.py]"]
end

subgraph group_resolution["Resolution workflow"]
  node_orchestrator["Ticket orchestrator<br/>[graph.py]"]
  node_perception["Issue perception"]
  node_judgment["Jev judgment<br/>[jev.py]"]
  node_memory["Knowledge and memory<br/>[memory_engine.py]"]
  node_decision["Resolution decision<br/>[decision_engine.py]"]
  node_swarm["Department routing<br/>[swarm_router.py]"]
  node_specialists["Specialist agents<br/>[base_agent.py]"]
  node_tools["Support tools<br/>[tool_service.py]"]
  node_truth_guard["Verified response<br/>[conversation.py]"]
end

subgraph group_operations["Human operations"]
  node_human_actions["Human intelligence<br/>[human_service.py]"]
  node_ticket_state["Ticket state machine<br/>[ticket_engine.py]"]
  node_live_ops["Live operations console<br/>[page.tsx]"]
  node_context["Ticket context<br/>[context_engine.py]"]
  node_learning["Learning signals"]
end

subgraph group_platform["Runtime platform"]
  node_api_entry["API entry points<br/>[router.py]"]
  node_database[("Application database<br/>[database.py]")]
  node_llm["Model interface<br/>[router.py]"]
  node_model_engine["Tiered model engine<br/>[model_manager.py]"]
end

node_customer(("Customer"))
node_console_user(("Support operator"))

node_customer -->|"starts chat"| node_web_channels
node_customer -->|"calls support"| node_voice_channel
node_customer -->|"emails support"| node_email_channel
node_web_channels -.->|"sends requests"| node_api_entry
node_voice_channel -->|"enters service"| node_api_entry
node_email_channel -->|"shares workflow"| node_orchestrator
node_api_entry -.->|"starts workflow"| node_orchestrator
node_orchestrator -->|"perceives issue"| node_perception
node_orchestrator -->|"judges issue"| node_judgment
node_orchestrator -->|"recalls knowledge"| node_memory
node_orchestrator -->|"chooses resolution"| node_decision
node_orchestrator -->|"routes ticket"| node_swarm
node_swarm -->|"selects specialist"| node_specialists
node_specialists -->|"runs actions"| node_tools
node_orchestrator -->|"pauses for input"| node_human_actions
node_human_actions -->|"updates ticket"| node_ticket_state
node_orchestrator -->|"records progress"| node_ticket_state
node_ticket_state -->|"persists state"| node_database
node_ticket_state -->|"broadcasts updates"| node_live_ops
node_orchestrator -->|"verifies claims"| node_truth_guard
node_truth_guard -->|"sends reply"| node_customer
node_orchestrator -.->|"refreshes notes"| node_context
node_context -->|"pushes summaries"| node_live_ops
node_human_actions -->|"teaches system"| node_learning
node_orchestrator -.->|"learns outcomes"| node_learning
node_voice_channel -.->|"handles speech"| node_voice_services
node_llm -->|"uses local engine"| node_model_engine

click node_web_channels "https://github.com/dua-saeed641/resolvyn/blob/main/frontend/app/talk/page.tsx"
click node_voice_channel "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/api/telephony.py"
click node_email_channel "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/services/email_service.py"
click node_api_entry "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/api/router.py"
click node_orchestrator "https://github.com/dua-saeed641/resolvyn/blob/main/agents/graph.py"
click node_perception "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/perception/perception_service.py"
click node_judgment "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/judgment/jev.py"
click node_memory "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/memory/memory_engine.py"
click node_decision "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/decision_engine/decision_engine.py"
click node_swarm "https://github.com/dua-saeed641/resolvyn/blob/main/agents/swarm_router.py"
click node_specialists "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/agents/base_agent.py"
click node_tools "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/tools/tool_service.py"
click node_truth_guard "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/services/conversation.py"
click node_human_actions "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/human_intelligence/human_service.py"
click node_ticket_state "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/services/ticket_engine.py"
click node_live_ops "https://github.com/dua-saeed641/resolvyn/blob/main/frontend/app/ops/overview/page.tsx"
click node_context "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/context_engine/context_engine.py"
click node_learning "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/learning/learning_service.py"
click node_database "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/database.py"
click node_llm "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/llm/router.py"
click node_model_engine "https://github.com/dua-saeed641/resolvyn/blob/main/engine/backend/tiers/model_manager.py"
click node_voice_services "https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/voice/speech.py"

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_channels,node_voice_channel,node_email_channel,node_voice_services toneBlue
class node_orchestrator,node_perception,node_judgment,node_memory,node_decision,node_swarm,node_specialists,node_tools,node_truth_guard toneAmber
class node_human_actions,node_ticket_state,node_live_ops,node_context,node_learning toneMint
class node_api_entry,node_database,node_llm,node_model_engine toneRose
class node_customer,node_console_user toneIndigo
```

## Components

### Customer channels

- [Chat interface](https://github.com/dua-saeed641/resolvyn/blob/main/frontend/app/talk/page.tsx): `frontend/app/talk/page.tsx`
- [Voice channel](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/api/telephony.py): `backend/app/api/telephony.py`
- [Email support](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/services/email_service.py): `backend/app/services/email_service.py`
- [Speech services](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/voice/speech.py): `backend/app/voice/speech.py`

### Resolution workflow

- [Ticket orchestrator](https://github.com/dua-saeed641/resolvyn/blob/main/agents/graph.py): `agents/graph.py`
- [Issue perception](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/perception/perception_service.py): `backend/app/perception/perception_service.py`
- [Jev judgment](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/judgment/jev.py): `backend/app/judgment/jev.py`
- [Knowledge and memory](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/memory/memory_engine.py): `backend/app/memory/memory_engine.py`
- [Resolution decision](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/decision_engine/decision_engine.py): `backend/app/decision_engine/decision_engine.py`
- [Department routing](https://github.com/dua-saeed641/resolvyn/blob/main/agents/swarm_router.py): `agents/swarm_router.py`
- [Specialist agents](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/agents/base_agent.py): `backend/app/agents/base_agent.py`
- [Support tools](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/tools/tool_service.py): `backend/app/tools/tool_service.py`
- [Verified response](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/services/conversation.py): `backend/app/services/conversation.py`

### Human operations

- [Human intelligence](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/human_intelligence/human_service.py): `backend/app/human_intelligence/human_service.py`
- [Ticket state machine](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/services/ticket_engine.py): `backend/app/services/ticket_engine.py`
- [Live operations console](https://github.com/dua-saeed641/resolvyn/blob/main/frontend/app/ops/overview/page.tsx): `frontend/app/ops/overview/page.tsx`
- [Ticket context](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/context_engine/context_engine.py): `backend/app/context_engine/context_engine.py`
- [Learning signals](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/learning/learning_service.py): `backend/app/learning/learning_service.py`

### Runtime platform

- [API entry points](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Application database](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/database.py): `backend/app/database.py`
- [Model interface](https://github.com/dua-saeed641/resolvyn/blob/main/backend/app/llm/router.py): `backend/app/llm/router.py`
- [Tiered model engine](https://github.com/dua-saeed641/resolvyn/blob/main/engine/backend/tiers/model_manager.py): `engine/backend/tiers/model_manager.py`

### Other components

- **Customer**
- **Support operator**

## Connections

- Customer → Chat interface: starts chat
- Customer → Voice channel: calls support
- Customer → Email support: emails support
- Chat interface → API entry points: sends requests
- Voice channel → API entry points: enters service (evidence: `backend/app/main.py`)
- Email support → Ticket orchestrator: shares workflow
- API entry points → Ticket orchestrator: starts workflow
- Ticket orchestrator → Issue perception: perceives issue
- Ticket orchestrator → Jev judgment: judges issue
- Ticket orchestrator → Knowledge and memory: recalls knowledge
- Ticket orchestrator → Resolution decision: chooses resolution
- Ticket orchestrator → Department routing: routes ticket
- Department routing → Specialist agents: selects specialist
- Specialist agents → Support tools: runs actions (evidence: `backend/app/agents/base_agent.py`)
- Ticket orchestrator → Human intelligence: pauses for input
- Human intelligence → Ticket state machine: updates ticket (evidence: `backend/app/human_intelligence/human_service.py`)
- Ticket orchestrator → Ticket state machine: records progress
- Ticket state machine → Application database: persists state (evidence: `backend/app/services/ticket_engine.py`)
- Ticket state machine → Live operations console: broadcasts updates (evidence: `backend/app/services/ticket_engine.py`)
- Ticket orchestrator → Verified response: verifies claims
- Verified response → Customer: sends reply
- Ticket orchestrator → Ticket context: refreshes notes
- Ticket context → Live operations console: pushes summaries (evidence: `backend/app/context_engine/context_engine.py`)
- Human intelligence → Learning signals: teaches system (evidence: `backend/app/human_intelligence/human_service.py`)
- Ticket orchestrator → Learning signals: learns outcomes
- Voice channel → Speech services: handles speech
- Model interface → Tiered model engine: uses local engine