# uktrade/redbox architecture

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

- Interactive diagram: https://gitdiagram.com/uktrade/redbox
- Repository: https://github.com/uktrade/redbox
- Video tour (about a minute): https://gitdiagram.com/uktrade/redbox/video

## Overview

Redbox is a document-ingestion and retrieval-augmented chat application for civil-service documents. Users upload documents for extraction, chunking, and indexing, then ask questions or request summaries; the runtime can retrieve source material and stream responses. The graph includes the Django-facing chat and upload interface, the RAG/agent runtime, ingestion, and shared settings/state. Edges follow shown imports or calls and README descriptions; several Django-to-engine and external-service integrations are not explicit in the excerpts, so those links are omitted.

Main entry points: [`redbox/redbox/app.py`](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/app.py) (RAG application), [`redbox/redbox/loader/ingester.py`](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/loader/ingester.py) (File ingestion), [`django_app/frontend/src/js/web-components/chats/chat-controller.js`](https://github.com/uktrade/redbox/blob/dev/django_app/frontend/src/js/web-components/chats/chat-controller.js) (Chat interface), [`redbox/redbox/retriever/retrievers.py`](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/retriever/retrievers.py) (Document retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User experience"]
  node_chat_ui["Chat interface<br/>[chat-controller.js]"]
  node_message_input["Message input<br/>[message-input.js]"]
  node_chat_message["Chat messages<br/>[chat-message.js]"]
  node_file_upload["File upload UI<br/>[file-upload.js]"]
end

subgraph group_ingest["Document ingestion"]
  node_ingester["File ingestion<br/>[ingester.py]"]
  node_extraction["Content extraction<br/>[service.py]"]
  node_chunking["Document chunking<br/>[service.py]"]
  node_ingest_chain["Ingest chains<br/>[ingest.py]"]
  node_vector_store[("Vector index")]
end

subgraph group_runtime["RAG runtime"]
  node_redbox_api["Redbox API<br/>[wrapper.py]"]
  node_redbox_app["RAG application<br/>[app.py]"]
  node_graph_root["Agent graph<br/>[root.py]"]
  node_agent_configs["Agent configurations<br/>[configs.py]"]
  node_chain_components["RAG chain components<br/>[components.py]"]
  node_retrievers["Document retrieval<br/>[retrievers.py]"]
  node_queries["Retrieval queries<br/>[queries.py]"]
  node_prompts["Agent prompts<br/>[prompts.py]"]
  node_state_models["Chat and run state<br/>[chain.py]"]
end

subgraph group_platform["Application platform"]
  node_django_models[("Application data<br/>[models.py]")]
  node_django_views["Web request handlers"]
  node_worker["Ingestion worker<br/>[worker.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

node_user(("Civil servant"))
node_object_storage[("Document object storage")]
node_llm["Language model"]

node_user -->|"uses"| node_chat_ui
node_chat_ui -->|"renders"| node_message_input
node_chat_ui -->|"uses"| node_chat_message
node_user -->|"uploads documents"| node_file_upload
node_worker -->|"invokes"| node_ingester
node_ingester -->|"extracts content"| node_extraction
node_extraction -.->|"reads files"| node_object_storage
node_ingester -->|"builds ingest flow"| node_ingest_chain
node_ingest_chain -->|"chunks content"| node_chunking
node_ingester -->|"indexes chunks"| node_vector_store
node_user -->|"asks or summarizes"| node_redbox_api
node_redbox_api -->|"wraps"| node_redbox_app
node_redbox_app -->|"executes graph"| node_graph_root
node_redbox_app -->|"configures agents"| node_agent_configs
node_redbox_app -->|"uses chains"| node_chain_components
node_chain_components -->|"retrieves documents"| node_retrievers
node_retrievers -->|"builds queries"| node_queries
node_retrievers -->|"searches index"| node_vector_store
node_agent_configs -->|"configures prompts"| node_prompts
node_redbox_app -->|"uses run state"| node_state_models
node_redbox_app -->|"loads settings"| node_settings
node_redbox_app -.->|"generates responses"| node_llm
node_file_upload -.->|"submits files"| node_django_views
node_django_views -.->|"accesses records"| node_django_models

click node_chat_ui "https://github.com/uktrade/redbox/blob/dev/django_app/frontend/src/js/web-components/chats/chat-controller.js"
click node_message_input "https://github.com/uktrade/redbox/blob/dev/django_app/frontend/src/js/web-components/chats/message-input.js"
click node_chat_message "https://github.com/uktrade/redbox/blob/dev/django_app/frontend/src/js/web-components/chats/chat-message.js"
click node_file_upload "https://github.com/uktrade/redbox/blob/dev/django_app/frontend/src/js/web-components/documents/file-upload.js"
click node_django_models "https://github.com/uktrade/redbox/blob/dev/django_app/redbox_app/redbox_core/models.py"
click node_django_views "https://github.com/uktrade/redbox/tree/dev/django_app/redbox_app/redbox_core/views"
click node_worker "https://github.com/uktrade/redbox/blob/dev/django_app/redbox_app/worker.py"
click node_ingester "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/loader/ingester.py"
click node_extraction "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/loader/extraction/service.py"
click node_chunking "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/loader/chunking/service.py"
click node_ingest_chain "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/chains/ingest.py"
click node_redbox_api "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/api/wrapper.py"
click node_redbox_app "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/app.py"
click node_graph_root "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/graph/root.py"
click node_agent_configs "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/graph/agents/configs.py"
click node_chain_components "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/chains/components.py"
click node_retrievers "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/retriever/retrievers.py"
click node_queries "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/retriever/queries.py"
click node_prompts "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/models/prompts.py"
click node_state_models "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/models/chain.py"
click node_settings "https://github.com/uktrade/redbox/blob/dev/redbox/redbox/models/settings.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_ui,node_message_input,node_chat_message,node_file_upload toneBlue
class node_ingester,node_extraction,node_chunking,node_ingest_chain,node_vector_store,node_object_storage toneAmber
class node_redbox_api,node_redbox_app,node_graph_root,node_agent_configs,node_chain_components,node_retrievers,node_queries,node_prompts,node_state_models toneMint
class node_django_models,node_django_views,node_worker,node_settings toneRose
class node_user,node_llm toneIndigo
```

## Components

### User experience

- [Chat interface](https://github.com/uktrade/redbox/blob/dev/django_app/frontend/src/js/web-components/chats/chat-controller.js): `django_app/frontend/src/js/web-components/chats/chat-controller.js`
- [Message input](https://github.com/uktrade/redbox/blob/dev/django_app/frontend/src/js/web-components/chats/message-input.js): `django_app/frontend/src/js/web-components/chats/message-input.js`
- [Chat messages](https://github.com/uktrade/redbox/blob/dev/django_app/frontend/src/js/web-components/chats/chat-message.js): `django_app/frontend/src/js/web-components/chats/chat-message.js`
- [File upload UI](https://github.com/uktrade/redbox/blob/dev/django_app/frontend/src/js/web-components/documents/file-upload.js): `django_app/frontend/src/js/web-components/documents/file-upload.js`

### Document ingestion

- [File ingestion](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/loader/ingester.py): `redbox/redbox/loader/ingester.py`
- [Content extraction](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/loader/extraction/service.py): `redbox/redbox/loader/extraction/service.py`
- [Document chunking](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/loader/chunking/service.py): `redbox/redbox/loader/chunking/service.py`
- [Ingest chains](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/chains/ingest.py): `redbox/redbox/chains/ingest.py`
- **Vector index**

### RAG runtime

- [Redbox API](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/api/wrapper.py): `redbox/redbox/api/wrapper.py`
- [RAG application](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/app.py): `redbox/redbox/app.py`
- [Agent graph](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/graph/root.py): `redbox/redbox/graph/root.py`
- [Agent configurations](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/graph/agents/configs.py): `redbox/redbox/graph/agents/configs.py`
- [RAG chain components](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/chains/components.py): `redbox/redbox/chains/components.py`
- [Document retrieval](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/retriever/retrievers.py): `redbox/redbox/retriever/retrievers.py`
- [Retrieval queries](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/retriever/queries.py): `redbox/redbox/retriever/queries.py`
- [Agent prompts](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/models/prompts.py): `redbox/redbox/models/prompts.py`
- [Chat and run state](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/models/chain.py): `redbox/redbox/models/chain.py`

### Application platform

- [Application data](https://github.com/uktrade/redbox/blob/dev/django_app/redbox_app/redbox_core/models.py): `django_app/redbox_app/redbox_core/models.py`
- [Web request handlers](https://github.com/uktrade/redbox/tree/dev/django_app/redbox_app/redbox_core/views): `django_app/redbox_app/redbox_core/views`
- [Ingestion worker](https://github.com/uktrade/redbox/blob/dev/django_app/redbox_app/worker.py): `django_app/redbox_app/worker.py`
- [Runtime settings](https://github.com/uktrade/redbox/blob/dev/redbox/redbox/models/settings.py): `redbox/redbox/models/settings.py`

### Other components

- **Civil servant**
- **Document object storage**
- **Language model**

## Connections

- Civil servant → Chat interface: uses (evidence: `README.md`)
- Chat interface → Message input: renders (evidence: `django_app/frontend/src/js/chats.js`)
- Chat interface → Chat messages: uses (evidence: `django_app/frontend/src/js/web-components/chats/chat-controller.js`)
- Civil servant → File upload UI: uploads documents (evidence: `README.md`)
- Ingestion worker → File ingestion: invokes (evidence: `django_app/redbox_app/worker.py`)
- File ingestion → Content extraction: extracts content (evidence: `redbox/redbox/loader/ingester.py`)
- Content extraction → Document object storage: reads files
- File ingestion → Ingest chains: builds ingest flow (evidence: `redbox/redbox/loader/ingester.py`)
- Ingest chains → Document chunking: chunks content (evidence: `redbox/redbox/chains/ingest.py`)
- File ingestion → Vector index: indexes chunks (evidence: `redbox/redbox/loader/ingester.py`)
- Civil servant → Redbox API: asks or summarizes (evidence: `README.md`)
- Redbox API → RAG application: wraps (evidence: `redbox/redbox/app.py`)
- RAG application → Agent graph: executes graph (evidence: `redbox/redbox/app.py`)
- RAG application → Agent configurations: configures agents (evidence: `redbox/redbox/app.py`)
- RAG application → RAG chain components: uses chains (evidence: `redbox/redbox/app.py`)
- RAG chain components → Document retrieval: retrieves documents (evidence: `redbox/redbox/chains/components.py`)
- Document retrieval → Retrieval queries: builds queries (evidence: `redbox/redbox/retriever/retrievers.py`)
- Document retrieval → Vector index: searches index (evidence: `redbox/redbox/retriever/retrievers.py`)
- Agent configurations → Agent prompts: configures prompts (evidence: `redbox/redbox/graph/agents/configs.py`)
- RAG application → Chat and run state: uses run state (evidence: `redbox/redbox/app.py`)
- RAG application → Runtime settings: loads settings (evidence: `redbox/redbox/app.py`)
- RAG application → Language model: generates responses
- File upload UI → Web request handlers: submits files
- Web request handlers → Application data: accesses records
