# waterbottles792/cloudob architecture

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

- Interactive diagram: https://gitdiagram.com/waterbottles792/cloudob
- Repository: https://github.com/waterbottles792/cloudob

## Overview

Cloudob Security is an AI customer-support platform with an enterprise operations console. The principal live workflow is browser chat → FastAPI → stateful LangGraph turn: input checks and intent routing lead to retrieval, business-tool handling, or escalation; generated answers are validated and returned with citations and metrics. A separate ingestion path prepares and indexes knowledge documents. The console also presents dashboard, retrieval, guardrail, evaluation, trace, workflow, and administration views; README notes that analytics are illustrative/mock-backed. Some UI-to-backend detail and unsampled subsystems are documented rather than visible in source excerpts.

Main entry points: [`graph/nodes.py`](https://github.com/waterbottles792/cloudob/blob/main/graph/nodes.py) (Agent decisions and generation), [`graph/workflow.py`](https://github.com/waterbottles792/cloudob/blob/main/graph/workflow.py) (Turn orchestration), [`rag/retriever.py`](https://github.com/waterbottles792/cloudob/blob/main/rag/retriever.py) (Hybrid retrieval), [`rag/ingest.py`](https://github.com/waterbottles792/cloudob/blob/main/rag/ingest.py) (Document ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Operations console"]
  node_assistant_ui["Assistant chat<br/>[page.tsx]"]
  node_console_views["Console views"]
  node_mock_data["Mock analytics<br/>[mock.ts]"]
  node_api_client["Frontend API client<br/>[api.ts]"]
end

subgraph group_api["API services"]
  node_fastapi["FastAPI endpoints<br/>[main.py]"]
  node_live_services["Live health and documents<br/>[services.py]"]
end

subgraph group_agent["Agent workflow"]
  node_workflow["Turn orchestration<br/>[workflow.py]"]
  node_chat_state["Conversation state<br/>[state.py]"]
  node_agent_nodes["Agent decisions and generation<br/>[nodes.py]"]
  node_input_checks["Input guardrails"]
  node_output_checks["Output validation"]
  node_prompts["Model prompts<br/>[prompts.py]"]
  node_settings["Runtime configuration<br/>[settings.py]"]
end

subgraph group_knowledge["Knowledge and tools"]
  node_ingestion["Document ingestion<br/>[ingest.py]"]
  node_loaders["Document loaders<br/>[loaders.py]"]
  node_processing["Cleaning and chunking<br/>[processing.py]"]
  node_retrieval["Hybrid retrieval<br/>[retriever.py]"]
  node_vector_factory["Vector store factory<br/>[factory.py]"]
  node_vector_store[("Configured vector index")]
  node_llm_factory["Gemini model factory<br/>[factory.py]"]
  node_support_tools["Support and CRM tools<br/>[support_tools.py]"]
end

node_browser(("Support operator"))
node_human(("Human support"))

node_browser -->|"uses"| node_assistant_ui
node_assistant_ui -->|"sends chat"| node_api_client
node_api_client -->|"falls back to"| node_mock_data
node_console_views -->|"shows analytics"| node_mock_data
node_api_client -->|"calls endpoints"| node_fastapi
node_fastapi -->|"runs turn"| node_workflow
node_fastapi -->|"reads health and documents"| node_live_services
node_workflow -->|"dispatches nodes"| node_agent_nodes
node_workflow -->|"threads state"| node_chat_state
node_agent_nodes -->|"reads and updates"| node_chat_state
node_agent_nodes -->|"checks input"| node_input_checks
node_agent_nodes -->|"validates answer"| node_output_checks
node_agent_nodes -->|"retrieves context"| node_retrieval
node_agent_nodes -->|"dispatches tools"| node_support_tools
node_agent_nodes -->|"uses prompts"| node_prompts
node_agent_nodes -.->|"invokes models"| node_llm_factory
node_workflow -.->|"escalates to"| node_human
node_ingestion -->|"loads files"| node_loaders
node_ingestion -->|"cleans and chunks"| node_processing
node_ingestion -->|"indexes chunks"| node_vector_factory
node_retrieval -->|"searches index"| node_vector_factory
node_retrieval -->|"loads parent store"| node_ingestion
node_vector_factory -->|"opens configured store"| node_vector_store
node_vector_factory -->|"gets embeddings"| node_llm_factory
node_retrieval -->|"compresses results"| node_llm_factory
node_live_services -->|"reads chunk counts"| node_vector_store

click node_assistant_ui "https://github.com/waterbottles792/cloudob/blob/main/frontend/app/(platform)/assistant/page.tsx"
click node_console_views "https://github.com/waterbottles792/cloudob/tree/main/frontend/app/(platform)"
click node_mock_data "https://github.com/waterbottles792/cloudob/blob/main/frontend/lib/mock.ts"
click node_api_client "https://github.com/waterbottles792/cloudob/blob/main/frontend/lib/api.ts"
click node_fastapi "https://github.com/waterbottles792/cloudob/blob/main/app/main.py"
click node_live_services "https://github.com/waterbottles792/cloudob/blob/main/app/services.py"
click node_workflow "https://github.com/waterbottles792/cloudob/blob/main/graph/workflow.py"
click node_chat_state "https://github.com/waterbottles792/cloudob/blob/main/graph/state.py"
click node_agent_nodes "https://github.com/waterbottles792/cloudob/blob/main/graph/nodes.py"
click node_input_checks "https://github.com/waterbottles792/cloudob/blob/main/guardrails/input_guardrails.py"
click node_output_checks "https://github.com/waterbottles792/cloudob/blob/main/guardrails/output_guardrails.py"
click node_prompts "https://github.com/waterbottles792/cloudob/blob/main/configs/prompts.py"
click node_settings "https://github.com/waterbottles792/cloudob/blob/main/configs/settings.py"
click node_ingestion "https://github.com/waterbottles792/cloudob/blob/main/rag/ingest.py"
click node_loaders "https://github.com/waterbottles792/cloudob/blob/main/rag/loaders.py"
click node_processing "https://github.com/waterbottles792/cloudob/blob/main/rag/processing.py"
click node_retrieval "https://github.com/waterbottles792/cloudob/blob/main/rag/retriever.py"
click node_vector_factory "https://github.com/waterbottles792/cloudob/blob/main/vectorstores/factory.py"
click node_llm_factory "https://github.com/waterbottles792/cloudob/blob/main/llm/factory.py"
click node_support_tools "https://github.com/waterbottles792/cloudob/blob/main/tools/support_tools.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_assistant_ui,node_console_views,node_mock_data,node_api_client toneBlue
class node_fastapi,node_live_services toneAmber
class node_workflow,node_chat_state,node_agent_nodes,node_input_checks,node_output_checks,node_prompts,node_settings toneMint
class node_ingestion,node_loaders,node_processing,node_retrieval,node_vector_factory,node_vector_store,node_llm_factory,node_support_tools toneRose
class node_browser,node_human toneIndigo
```

## Components

### Operations console

- [Assistant chat](https://github.com/waterbottles792/cloudob/blob/main/frontend/app/(platform)/assistant/page.tsx): `frontend/app/(platform)/assistant/page.tsx`
- [Console views](https://github.com/waterbottles792/cloudob/tree/main/frontend/app/(platform)): `frontend/app/(platform)`
- [Mock analytics](https://github.com/waterbottles792/cloudob/blob/main/frontend/lib/mock.ts): `frontend/lib/mock.ts`
- [Frontend API client](https://github.com/waterbottles792/cloudob/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API services

- [FastAPI endpoints](https://github.com/waterbottles792/cloudob/blob/main/app/main.py): `app/main.py`
- [Live health and documents](https://github.com/waterbottles792/cloudob/blob/main/app/services.py): `app/services.py`

### Agent workflow

- [Turn orchestration](https://github.com/waterbottles792/cloudob/blob/main/graph/workflow.py): `graph/workflow.py`
- [Conversation state](https://github.com/waterbottles792/cloudob/blob/main/graph/state.py): `graph/state.py`
- [Agent decisions and generation](https://github.com/waterbottles792/cloudob/blob/main/graph/nodes.py): `graph/nodes.py`
- [Input guardrails](https://github.com/waterbottles792/cloudob/blob/main/guardrails/input_guardrails.py): `guardrails/input_guardrails.py`
- [Output validation](https://github.com/waterbottles792/cloudob/blob/main/guardrails/output_guardrails.py): `guardrails/output_guardrails.py`
- [Model prompts](https://github.com/waterbottles792/cloudob/blob/main/configs/prompts.py): `configs/prompts.py`
- [Runtime configuration](https://github.com/waterbottles792/cloudob/blob/main/configs/settings.py): `configs/settings.py`

### Knowledge and tools

- [Document ingestion](https://github.com/waterbottles792/cloudob/blob/main/rag/ingest.py): `rag/ingest.py`
- [Document loaders](https://github.com/waterbottles792/cloudob/blob/main/rag/loaders.py): `rag/loaders.py`
- [Cleaning and chunking](https://github.com/waterbottles792/cloudob/blob/main/rag/processing.py): `rag/processing.py`
- [Hybrid retrieval](https://github.com/waterbottles792/cloudob/blob/main/rag/retriever.py): `rag/retriever.py`
- [Vector store factory](https://github.com/waterbottles792/cloudob/blob/main/vectorstores/factory.py): `vectorstores/factory.py`
- **Configured vector index**
- [Gemini model factory](https://github.com/waterbottles792/cloudob/blob/main/llm/factory.py): `llm/factory.py`
- [Support and CRM tools](https://github.com/waterbottles792/cloudob/blob/main/tools/support_tools.py): `tools/support_tools.py`

### Other components

- **Support operator**
- **Human support**

## Connections

- Support operator → Assistant chat: uses
- Assistant chat → Frontend API client: sends chat
- Frontend API client → Mock analytics: falls back to (evidence: `frontend/lib/api.ts`)
- Console views → Mock analytics: shows analytics (evidence: `frontend/lib/mock.ts`)
- Frontend API client → FastAPI endpoints: calls endpoints
- FastAPI endpoints → Turn orchestration: runs turn (evidence: `app/main.py`)
- FastAPI endpoints → Live health and documents: reads health and documents (evidence: `app/main.py`)
- Turn orchestration → Agent decisions and generation: dispatches nodes (evidence: `graph/workflow.py`)
- Turn orchestration → Conversation state: threads state (evidence: `graph/workflow.py`)
- Agent decisions and generation → Conversation state: reads and updates (evidence: `graph/nodes.py`)
- Agent decisions and generation → Input guardrails: checks input (evidence: `graph/nodes.py`)
- Agent decisions and generation → Output validation: validates answer (evidence: `graph/nodes.py`)
- Agent decisions and generation → Hybrid retrieval: retrieves context (evidence: `graph/nodes.py`)
- Agent decisions and generation → Support and CRM tools: dispatches tools (evidence: `graph/nodes.py`)
- Agent decisions and generation → Model prompts: uses prompts (evidence: `graph/nodes.py`)
- Agent decisions and generation → Gemini model factory: invokes models
- Turn orchestration → Human support: escalates to
- Document ingestion → Document loaders: loads files (evidence: `rag/ingest.py`)
- Document ingestion → Cleaning and chunking: cleans and chunks (evidence: `rag/ingest.py`)
- Document ingestion → Vector store factory: indexes chunks (evidence: `rag/ingest.py`)
- Hybrid retrieval → Vector store factory: searches index (evidence: `rag/retriever.py`)
- Hybrid retrieval → Document ingestion: loads parent store (evidence: `rag/retriever.py`)
- Vector store factory → Configured vector index: opens configured store (evidence: `vectorstores/factory.py`)
- Vector store factory → Gemini model factory: gets embeddings (evidence: `vectorstores/factory.py`)
- Hybrid retrieval → Gemini model factory: compresses results (evidence: `rag/retriever.py`)
- Live health and documents → Configured vector index: reads chunk counts (evidence: `app/services.py`)
