# cmudco/dare-backend architecture

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

- Interactive diagram: https://gitdiagram.com/cmudco/dare-backend
- Repository: https://github.com/cmudco/dare-backend

## Overview

DARE is a Django REST and Socket.IO backend for a multi-provider research and conversation platform. Its main user path is client requests into conversation/chat APIs, model dispatch and (when relevant) retrieval over uploaded documents, followed by streamed results. Separate branches provide document ingestion and RAG, visual workflow execution, MCP tools, account/access management, and usage billing. The README documents the product-level connections; internal links below are limited to sampled code references. Several major subsystems are represented at their source-directory level because their implementations were not sampled.

Main entry points: [`workflows/handlers/step_handler.py`](https://github.com/cmudco/dare-backend/blob/main/workflows/handlers/step_handler.py) (Workflow step handler), [`conversations/services`](https://github.com/cmudco/dare-backend/tree/main/conversations/services) (Chat services), [`conversations/api/views.py`](https://github.com/cmudco/dare-backend/blob/main/conversations/api/views.py) (Conversation API), [`core/services/document_processor.py`](https://github.com/cmudco/dare-backend/blob/main/core/services/document_processor.py) (Document processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation and models"]
  node_conversation_api["Conversation API<br/>[views.py]"]
  node_chat_services["Chat services"]
  node_conversation_data[("Conversation data<br/>[models.py]")]
  node_socket["Socket streaming<br/>[socket_server.py]"]
end

subgraph group_documents["Documents and retrieval"]
  node_file_api["File API<br/>[views.py]"]
  node_ingestion["Document ingestion"]
  node_processor["Document processor"]
  node_document_map[("Document map")]
  node_file_data[("File records<br/>[models.py]")]
  node_rag["RAG pipeline<br/>[pipeline.py]"]
end

subgraph group_workflows["Workflow and tools"]
  node_workflow_api["Workflow API<br/>[views.py]"]
  node_step_handler["Workflow step handler<br/>[step_handler.py]"]
  node_workflow_runs["Workflow run services"]
  node_mcp_manager["MCP manager<br/>[mcp_manager.py]"]
end

subgraph group_platform["Accounts and billing"]
  node_users[("Users and access<br/>[models.py]")]
  node_billing["Billing services<br/>[services.py]"]
  node_model_filter["Wallet model filter"]
end

subgraph group_runtime["Core runtime"]
  node_llm_service["LLM dispatch<br/>[llm_service.py]"]
  node_provider_services["Provider services"]
end

node_client(("Platform clients"))
node_vector_stores[("Vector stores")]
node_mcp_servers{{"MCP servers"}}
node_llm_apis{{"LLM providers"}}
node_postgres[("PostgreSQL")]
node_redis[("Redis and jobs")]

node_client -->|"requests chat"| node_conversation_api
node_conversation_api -.->|"serves chat"| node_chat_services
node_chat_services -->|"dispatches prompts"| node_llm_service
node_llm_service -->|"dispatches by provider"| node_provider_services
node_provider_services -->|"calls providers"| node_llm_apis
node_chat_services -->|"retrieves context"| node_rag
node_socket -->|"streams responses"| node_client
node_conversation_api -.->|"persists conversations"| node_conversation_data
node_client -->|"uploads documents"| node_file_api
node_file_api -.->|"starts processing"| node_ingestion
node_ingestion -->|"processes document"| node_processor
node_processor -->|"builds map"| node_document_map
node_document_map -->|"reads and writes"| node_file_data
node_rag -->|"loads map data"| node_document_map
node_rag -->|"retrieves vectors"| node_vector_stores
node_processor -->|"indexes documents"| node_vector_stores
node_client -->|"runs workflows"| node_workflow_api
node_workflow_api -.->|"executes steps"| node_step_handler
node_step_handler -->|"uses tool loop"| node_chat_services
node_step_handler -->|"records workflow sources"| node_workflow_runs
node_step_handler -.->|"executes retrieval tools"| node_mcp_manager
node_mcp_manager -->|"discovers and invokes"| node_mcp_servers
node_client -->|"registers and authenticates"| node_users
node_users -->|"stores accounts"| node_postgres
node_model_filter -->|"resolves wallet"| node_billing
node_client -->|"tracks usage"| node_billing
node_llm_service -.->|"uses background runtime"| node_redis
node_billing -->|"stores usage"| node_postgres

click node_conversation_api "https://github.com/cmudco/dare-backend/blob/main/conversations/api/views.py"
click node_chat_services "https://github.com/cmudco/dare-backend/tree/main/conversations/services"
click node_conversation_data "https://github.com/cmudco/dare-backend/blob/main/conversations/models.py"
click node_socket "https://github.com/cmudco/dare-backend/blob/main/conversations/socket_server.py"
click node_file_api "https://github.com/cmudco/dare-backend/blob/main/files/api/views.py"
click node_ingestion "https://github.com/cmudco/dare-backend/blob/main/core/services/document_ingestion_service.py"
click node_processor "https://github.com/cmudco/dare-backend/blob/main/core/services/document_processor.py"
click node_document_map "https://github.com/cmudco/dare-backend/blob/main/files/services/document_map_service.py"
click node_file_data "https://github.com/cmudco/dare-backend/blob/main/files/models.py"
click node_rag "https://github.com/cmudco/dare-backend/blob/main/core/services/rag/pipeline.py"
click node_workflow_api "https://github.com/cmudco/dare-backend/blob/main/workflows/api/views.py"
click node_step_handler "https://github.com/cmudco/dare-backend/blob/main/workflows/handlers/step_handler.py"
click node_workflow_runs "https://github.com/cmudco/dare-backend/tree/main/workflows/services"
click node_mcp_manager "https://github.com/cmudco/dare-backend/blob/main/mcp/services/mcp_manager.py"
click node_users "https://github.com/cmudco/dare-backend/blob/main/users/models.py"
click node_billing "https://github.com/cmudco/dare-backend/blob/main/billing/services.py"
click node_model_filter "https://github.com/cmudco/dare-backend/blob/main/conversations/services/llm_filter_service.py"
click node_llm_service "https://github.com/cmudco/dare-backend/blob/main/core/services/llm_service.py"
click node_provider_services "https://github.com/cmudco/dare-backend/tree/main/core/services"

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_conversation_api,node_chat_services,node_conversation_data,node_socket,node_client toneBlue
class node_file_api,node_ingestion,node_processor,node_document_map,node_file_data,node_rag,node_vector_stores,node_postgres,node_redis toneAmber
class node_workflow_api,node_step_handler,node_workflow_runs,node_mcp_manager,node_mcp_servers toneMint
class node_users,node_billing,node_model_filter toneRose
class node_llm_service,node_provider_services,node_llm_apis toneIndigo
```

## Components

### Conversation and models

- [Conversation API](https://github.com/cmudco/dare-backend/blob/main/conversations/api/views.py): `conversations/api/views.py`
- [Chat services](https://github.com/cmudco/dare-backend/tree/main/conversations/services): `conversations/services`
- [Conversation data](https://github.com/cmudco/dare-backend/blob/main/conversations/models.py): `conversations/models.py`
- [Socket streaming](https://github.com/cmudco/dare-backend/blob/main/conversations/socket_server.py): `conversations/socket_server.py`

### Documents and retrieval

- [File API](https://github.com/cmudco/dare-backend/blob/main/files/api/views.py): `files/api/views.py`
- [Document ingestion](https://github.com/cmudco/dare-backend/blob/main/core/services/document_ingestion_service.py): `core/services/document_ingestion_service.py`
- [Document processor](https://github.com/cmudco/dare-backend/blob/main/core/services/document_processor.py): `core/services/document_processor.py`
- [Document map](https://github.com/cmudco/dare-backend/blob/main/files/services/document_map_service.py): `files/services/document_map_service.py`
- [File records](https://github.com/cmudco/dare-backend/blob/main/files/models.py): `files/models.py`
- [RAG pipeline](https://github.com/cmudco/dare-backend/blob/main/core/services/rag/pipeline.py): `core/services/rag/pipeline.py`

### Workflow and tools

- [Workflow API](https://github.com/cmudco/dare-backend/blob/main/workflows/api/views.py): `workflows/api/views.py`
- [Workflow step handler](https://github.com/cmudco/dare-backend/blob/main/workflows/handlers/step_handler.py): `workflows/handlers/step_handler.py`
- [Workflow run services](https://github.com/cmudco/dare-backend/tree/main/workflows/services): `workflows/services`
- [MCP manager](https://github.com/cmudco/dare-backend/blob/main/mcp/services/mcp_manager.py): `mcp/services/mcp_manager.py`

### Accounts and billing

- [Users and access](https://github.com/cmudco/dare-backend/blob/main/users/models.py): `users/models.py`
- [Billing services](https://github.com/cmudco/dare-backend/blob/main/billing/services.py): `billing/services.py`
- [Wallet model filter](https://github.com/cmudco/dare-backend/blob/main/conversations/services/llm_filter_service.py): `conversations/services/llm_filter_service.py`

### Core runtime

- [LLM dispatch](https://github.com/cmudco/dare-backend/blob/main/core/services/llm_service.py): `core/services/llm_service.py`
- [Provider services](https://github.com/cmudco/dare-backend/tree/main/core/services): `core/services`

### Other components

- **Platform clients**
- **Vector stores**
- **MCP servers**
- **LLM providers**
- **PostgreSQL**
- **Redis and jobs**

## Connections

- Platform clients → Conversation API: requests chat (evidence: `README.md`)
- Conversation API → Chat services: serves chat
- Chat services → LLM dispatch: dispatches prompts (evidence: `README.md`)
- LLM dispatch → Provider services: dispatches by provider (evidence: `core/services/llm_service.py`)
- Provider services → LLM providers: calls providers (evidence: `README.md`)
- Chat services → RAG pipeline: retrieves context (evidence: `README.md`)
- Socket streaming → Platform clients: streams responses (evidence: `README.md`)
- Conversation API → Conversation data: persists conversations
- Platform clients → File API: uploads documents (evidence: `README.md`)
- File API → Document ingestion: starts processing
- Document ingestion → Document processor: processes document (evidence: `core/services/document_ingestion_service.py`)
- Document processor → Document map: builds map (evidence: `core/services/document_processor.py`)
- Document map → File records: reads and writes (evidence: `files/services/document_map_service.py`)
- RAG pipeline → Document map: loads map data (evidence: `core/services/rag/pipeline.py`)
- RAG pipeline → Vector stores: retrieves vectors (evidence: `README.md`)
- Document processor → Vector stores: indexes documents (evidence: `README.md`)
- Platform clients → Workflow API: runs workflows (evidence: `README.md`)
- Workflow API → Workflow step handler: executes steps
- Workflow step handler → Chat services: uses tool loop (evidence: `workflows/handlers/step_handler.py`)
- Workflow step handler → Workflow run services: records workflow sources (evidence: `workflows/handlers/step_handler.py`)
- Workflow step handler → MCP manager: executes retrieval tools
- MCP manager → MCP servers: discovers and invokes (evidence: `mcp/services/mcp_manager.py`)
- Platform clients → Users and access: registers and authenticates (evidence: `README.md`)
- Users and access → PostgreSQL: stores accounts (evidence: `README.md`)
- Wallet model filter → Billing services: resolves wallet (evidence: `conversations/services/llm_filter_service.py`)
- Platform clients → Billing services: tracks usage (evidence: `README.md`)
- LLM dispatch → Redis and jobs: uses background runtime
- Billing services → PostgreSQL: stores usage (evidence: `README.md`)
