# tortextrx/ecoflow architecture

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

- Interactive diagram: https://gitdiagram.com/tortextrx/ecoflow
- Repository: https://github.com/tortextrx/ecoflow

## Overview

ecoFlow is a conversational assistant for managing ecoSoftWEB ERP records and documents. The principal workflow accepts chat text or an attachment, interprets intent, resolves entities and missing details, applies a confirmation-aware operation flow, invokes ERP tools, and returns a humanized response. Separate capabilities cover entities, services, contracts, articles, and invoicing; internal routes also support queued message processing and persistence. The README documents the cognitive, deterministic orchestration, response, and ERP-connector layers. Some implementation relationships are shown as unverified because the current orchestrator and most tool implementations were not sampled.

Main entry points: [`app/services/tools/registry.py`](https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/registry.py) (Tool registry), [`app/services/orchestrator.py`](https://github.com/tortextrx/ecoflow/blob/main/app/services/orchestrator.py) (Flow orchestrator), [`app/api/routes_internal.py`](https://github.com/tortextrx/ecoflow/blob/main/app/api/routes_internal.py) (Internal intake), [`app/services/chat_service.py`](https://github.com/tortextrx/ecoflow/blob/main/app/services/chat_service.py) (Chat service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Chat and ingress"]
  node_chat_api["Chat endpoint<br/>[routes_chat.py]"]
  node_internal_api["Internal intake<br/>[routes_internal.py]"]
end

subgraph group_conversation["Conversation processing"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_orchestrator["Flow orchestrator<br/>[orchestrator.py]"]
  node_cognitive["Intent analysis"]
  node_routing["Flow routing"]
  node_conversation_logic["State logic"]
  node_normalizers["Input normalization<br/>[normalizers.py]"]
  node_resolver["Entity resolution<br/>[resolver.py]"]
  node_response["Response generation"]
end

subgraph group_operations["ERP operations"]
  node_tool_registry["Tool registry<br/>[registry.py]"]
  node_entity_ops["Entity operations<br/>[entidades_tools.py]"]
  node_service_ops["Service operations<br/>[servicios_tools.py]"]
  node_contract_ops["Contract operations<br/>[contratos_tools.py]"]
  node_article_ops["Article operations<br/>[articulos_tools.py]"]
  node_billing_ops["Billing operations"]
  node_document_ops["Document extraction"]
end

subgraph group_integration["ERP integration"]
  node_erp_connectors["ERP connectors"]
  node_entity_mapper["Entity mapper"]
  node_billing_mapper["Billing mapper"]
  node_llm_provider["LLM provider<br/>[llm_provider.py]"]
end

subgraph group_state["Persistence and jobs"]
  node_database[("Application database<br/>[db.py]")]
  node_repositories["Data repositories"]
  node_job_queue["Job queue<br/>[job_queue.py]"]
end

node_user(("ERP user"))

node_user -->|"submits chat"| node_chat_api
node_chat_api -->|"delegates handling"| node_chat_service
node_chat_service -->|"runs flow"| node_orchestrator
node_chat_service -->|"uses response"| node_response
node_orchestrator -->|"classifies intent"| node_cognitive
node_orchestrator -->|"resolves entities"| node_resolver
node_orchestrator -->|"dispatches tools"| node_tool_registry
node_orchestrator -->|"uses flow detection"| node_routing
node_orchestrator -->|"uses state logic"| node_conversation_logic
node_orchestrator -->|"normalizes input"| node_normalizers
node_resolver -->|"queries entities"| node_tool_registry
node_tool_registry -->|"registers tools"| node_entity_ops
node_tool_registry -->|"registers tools"| node_service_ops
node_tool_registry -->|"registers tools"| node_contract_ops
node_tool_registry -->|"registers tools"| node_article_ops
node_tool_registry -->|"registers tools"| node_billing_ops
node_tool_registry -->|"registers tools"| node_document_ops
node_user -.->|"sends message"| node_internal_api
node_internal_api -->|"queues work"| node_job_queue
node_internal_api -->|"persists intake"| node_database
node_internal_api -->|"uses job repository"| node_repositories
node_chat_service -->|"loads conversation"| node_repositories
node_entity_ops -.->|"calls ERP"| node_erp_connectors
node_billing_ops -.->|"calls ERP"| node_erp_connectors
node_entity_mapper -.->|"builds ERP payload"| node_erp_connectors
node_billing_mapper -.->|"builds ERP payload"| node_erp_connectors
node_cognitive -.->|"calls model"| node_llm_provider

click node_chat_api "https://github.com/tortextrx/ecoflow/blob/main/app/api/routes_chat.py"
click node_internal_api "https://github.com/tortextrx/ecoflow/blob/main/app/api/routes_internal.py"
click node_chat_service "https://github.com/tortextrx/ecoflow/blob/main/app/services/chat_service.py"
click node_orchestrator "https://github.com/tortextrx/ecoflow/blob/main/app/services/orchestrator.py"
click node_cognitive "https://github.com/tortextrx/ecoflow/blob/main/app/services/cognitive_service.py"
click node_routing "https://github.com/tortextrx/ecoflow/blob/main/app/services/orchestrator_routing.py"
click node_conversation_logic "https://github.com/tortextrx/ecoflow/blob/main/app/services/conversational_logic.py"
click node_normalizers "https://github.com/tortextrx/ecoflow/blob/main/app/services/normalizers.py"
click node_resolver "https://github.com/tortextrx/ecoflow/blob/main/app/services/resolver.py"
click node_response "https://github.com/tortextrx/ecoflow/blob/main/app/services/response_service.py"
click node_tool_registry "https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/registry.py"
click node_entity_ops "https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/entidades_tools.py"
click node_service_ops "https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/servicios_tools.py"
click node_contract_ops "https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/contratos_tools.py"
click node_article_ops "https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/articulos_tools.py"
click node_billing_ops "https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/facturacion_tools.py"
click node_document_ops "https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/extraer_documento.py"
click node_erp_connectors "https://github.com/tortextrx/ecoflow/tree/main/app/connectors"
click node_entity_mapper "https://github.com/tortextrx/ecoflow/blob/main/app/mappers/entidades_mapper.py"
click node_billing_mapper "https://github.com/tortextrx/ecoflow/blob/main/app/mappers/facturacion_mapper.py"
click node_database "https://github.com/tortextrx/ecoflow/blob/main/app/core/db.py"
click node_repositories "https://github.com/tortextrx/ecoflow/tree/main/app/repositories"
click node_job_queue "https://github.com/tortextrx/ecoflow/blob/main/app/core/job_queue.py"
click node_llm_provider "https://github.com/tortextrx/ecoflow/blob/main/app/providers/llm_provider.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_chat_api,node_internal_api,node_user toneBlue
class node_chat_service,node_orchestrator,node_cognitive,node_routing,node_conversation_logic,node_normalizers,node_resolver,node_response toneAmber
class node_tool_registry,node_entity_ops,node_service_ops,node_contract_ops,node_article_ops,node_billing_ops,node_document_ops toneMint
class node_erp_connectors,node_entity_mapper,node_billing_mapper,node_llm_provider toneRose
class node_database,node_repositories,node_job_queue toneIndigo
```

## Components

### Chat and ingress

- [Chat endpoint](https://github.com/tortextrx/ecoflow/blob/main/app/api/routes_chat.py): `app/api/routes_chat.py`
- [Internal intake](https://github.com/tortextrx/ecoflow/blob/main/app/api/routes_internal.py): `app/api/routes_internal.py`

### Conversation processing

- [Chat service](https://github.com/tortextrx/ecoflow/blob/main/app/services/chat_service.py): `app/services/chat_service.py`
- [Flow orchestrator](https://github.com/tortextrx/ecoflow/blob/main/app/services/orchestrator.py): `app/services/orchestrator.py`
- [Intent analysis](https://github.com/tortextrx/ecoflow/blob/main/app/services/cognitive_service.py): `app/services/cognitive_service.py`
- [Flow routing](https://github.com/tortextrx/ecoflow/blob/main/app/services/orchestrator_routing.py): `app/services/orchestrator_routing.py`
- [State logic](https://github.com/tortextrx/ecoflow/blob/main/app/services/conversational_logic.py): `app/services/conversational_logic.py`
- [Input normalization](https://github.com/tortextrx/ecoflow/blob/main/app/services/normalizers.py): `app/services/normalizers.py`
- [Entity resolution](https://github.com/tortextrx/ecoflow/blob/main/app/services/resolver.py): `app/services/resolver.py`
- [Response generation](https://github.com/tortextrx/ecoflow/blob/main/app/services/response_service.py): `app/services/response_service.py`

### ERP operations

- [Tool registry](https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/registry.py): `app/services/tools/registry.py`
- [Entity operations](https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/entidades_tools.py): `app/services/tools/entidades_tools.py`
- [Service operations](https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/servicios_tools.py): `app/services/tools/servicios_tools.py`
- [Contract operations](https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/contratos_tools.py): `app/services/tools/contratos_tools.py`
- [Article operations](https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/articulos_tools.py): `app/services/tools/articulos_tools.py`
- [Billing operations](https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/facturacion_tools.py): `app/services/tools/facturacion_tools.py`
- [Document extraction](https://github.com/tortextrx/ecoflow/blob/main/app/services/tools/extraer_documento.py): `app/services/tools/extraer_documento.py`

### ERP integration

- [ERP connectors](https://github.com/tortextrx/ecoflow/tree/main/app/connectors): `app/connectors`
- [Entity mapper](https://github.com/tortextrx/ecoflow/blob/main/app/mappers/entidades_mapper.py): `app/mappers/entidades_mapper.py`
- [Billing mapper](https://github.com/tortextrx/ecoflow/blob/main/app/mappers/facturacion_mapper.py): `app/mappers/facturacion_mapper.py`
- [LLM provider](https://github.com/tortextrx/ecoflow/blob/main/app/providers/llm_provider.py): `app/providers/llm_provider.py`

### Persistence and jobs

- [Application database](https://github.com/tortextrx/ecoflow/blob/main/app/core/db.py): `app/core/db.py`
- [Data repositories](https://github.com/tortextrx/ecoflow/tree/main/app/repositories): `app/repositories`
- [Job queue](https://github.com/tortextrx/ecoflow/blob/main/app/core/job_queue.py): `app/core/job_queue.py`

### Other components

- **ERP user**

## Connections

- ERP user → Chat endpoint: submits chat (evidence: `app/api/routes_chat.py`)
- Chat endpoint → Chat service: delegates handling (evidence: `app/api/routes_chat.py`)
- Chat service → Flow orchestrator: runs flow (evidence: `app/services/chat_service.py`)
- Chat service → Response generation: uses response (evidence: `app/services/chat_service.py`)
- Flow orchestrator → Intent analysis: classifies intent
- Flow orchestrator → Entity resolution: resolves entities
- Flow orchestrator → Tool registry: dispatches tools
- Flow orchestrator → Flow routing: uses flow detection
- Flow orchestrator → State logic: uses state logic
- Flow orchestrator → Input normalization: normalizes input
- Entity resolution → Tool registry: queries entities (evidence: `app/services/resolver.py`)
- Tool registry → Entity operations: registers tools (evidence: `app/services/tools/registry.py`)
- Tool registry → Service operations: registers tools (evidence: `app/services/tools/registry.py`)
- Tool registry → Contract operations: registers tools (evidence: `app/services/tools/registry.py`)
- Tool registry → Article operations: registers tools (evidence: `app/services/tools/registry.py`)
- Tool registry → Billing operations: registers tools (evidence: `app/services/tools/registry.py`)
- Tool registry → Document extraction: registers tools (evidence: `app/services/tools/registry.py`)
- ERP user → Internal intake: sends message
- Internal intake → Job queue: queues work (evidence: `app/api/routes_internal.py`)
- Internal intake → Application database: persists intake (evidence: `app/api/routes_internal.py`)
- Internal intake → Data repositories: uses job repository (evidence: `app/api/routes_internal.py`)
- Chat service → Data repositories: loads conversation (evidence: `app/services/chat_service.py`)
- Entity operations → ERP connectors: calls ERP
- Billing operations → ERP connectors: calls ERP
- Entity mapper → ERP connectors: builds ERP payload
- Billing mapper → ERP connectors: builds ERP payload
- Intent analysis → LLM provider: calls model