# mohatemtc/barq-sprints-ai-servicenow-support-assistant-4 architecture

> Architecture diagram of the GitHub repository mohatemtc/barq-sprints-ai-servicenow-support-assistant-4, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4
- Repository: https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4

## Overview

BARQ AI is an event-driven ServiceNow support assistant: incident and knowledge-base events enter through webhooks, background tasks coordinate processing, and the assistant retrieves knowledge and prepares a human-reviewable suggestion. A separate KB synchronization path keeps the retrieval index current. The repository also contains a standalone grounded-generation agent implementation. Evidence is limited to the README and indexed or excerpted files; connections for unsampled behavior are omitted.

Main entry points: [`src/barq_ai_support/kb_sync_service.py`](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/kb_sync_service.py) (KB Sync), [`src/barq_ai_support/agent/s3_worker.py`](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/agent/s3_worker.py) (Agent Worker), [`src/barq_ai_support/tasks.py`](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/tasks.py) (Background Tasks), [`agent/executor.py`](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/agent/executor.py) (Grounded Executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Event Intake"]
  node_business_rule["Incident Rule<br/>[business_rule.js]"]
  node_api["FastAPI App<br/>[main.py]"]
  node_incident_hook["Incident Webhook<br/>[webhook.py]"]
  node_kb_hook["KB Webhook<br/>[kb_webhook.py]"]
end

subgraph group_jobs["Async Processing"]
  node_celery["Task Queue<br/>[celery_app.py]"]
  node_tasks["Background Tasks<br/>[tasks.py]"]
end

subgraph group_knowledge["Knowledge Pipeline"]
  node_sync["KB Sync<br/>[kb_sync_service.py]"]
  node_servicenow_client["ServiceNow Client"]
  node_chunker["Article Chunker<br/>[chunker.py]"]
  node_embedding["Embedding<br/>[embedding.py]"]
  node_vector_store[("Qdrant Index<br/>[qdrant_store.py]")]
  node_kb_state[("KB State<br/>[kb_state_store.py]")]
end

subgraph group_assistant["Incident Assistant"]
  node_retriever["Semantic Retrieval<br/>[retriever.py]"]
  node_worker["Agent Worker<br/>[s3_worker.py]"]
end

subgraph group_grounded["Grounded Agent"]
  node_legacy_executor["Grounded Executor<br/>[executor.py]"]
  node_prompt["Grounding Prompt<br/>[prompt.py]"]
  node_schemas["Agent Schemas<br/>[schemas.py]"]
  node_validators["Output Validators<br/>[validators.py]"]
end

node_servicenow(("ServiceNow"))
node_human(("Support Reviewer"))

node_servicenow -->|"creates incident"| node_business_rule
node_business_rule -->|"posts event"| node_incident_hook
node_api -->|"mounts route"| node_incident_hook
node_api -->|"mounts route"| node_kb_hook
node_incident_hook -->|"dispatches task"| node_tasks
node_kb_hook -->|"dispatches task"| node_tasks
node_tasks -->|"registers tasks"| node_celery
node_tasks -->|"runs agent"| node_worker
node_tasks -->|"runs sync"| node_sync
node_sync -->|"fetches article"| node_servicenow_client
node_servicenow_client -->|"reads and writes"| node_servicenow
node_sync -->|"chunks article"| node_chunker
node_sync -->|"updates index"| node_vector_store
node_sync -->|"tracks changes"| node_kb_state
node_retriever -->|"queries index"| node_vector_store
node_worker -->|"searches knowledge"| node_retriever
node_worker -->|"loads and updates"| node_servicenow_client
node_worker -->|"uses embeddings"| node_embedding
node_worker -->|"suggests for review"| node_human
node_legacy_executor -->|"builds prompt"| node_prompt
node_legacy_executor -->|"validates inputs"| node_schemas
node_legacy_executor -->|"validates output"| node_validators

click node_business_rule "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/businessRule/business_rule.js"
click node_api "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/main.py"
click node_incident_hook "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/webhook.py"
click node_kb_hook "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/kb_webhook.py"
click node_celery "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/celery_app.py"
click node_tasks "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/tasks.py"
click node_sync "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/kb_sync_service.py"
click node_servicenow_client "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/servicenow_client.py"
click node_chunker "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/ingestion/chunker.py"
click node_embedding "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/ingestion/embedding.py"
click node_vector_store "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/ingestion/qdrant_store.py"
click node_kb_state "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/kb_state_store.py"
click node_retriever "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/retrieval/retriever.py"
click node_worker "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/agent/s3_worker.py"
click node_legacy_executor "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/agent/executor.py"
click node_prompt "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/agent/prompt.py"
click node_schemas "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/agent/schemas.py"
click node_validators "https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/agent/validators.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_business_rule,node_api,node_incident_hook,node_kb_hook,node_human toneBlue
class node_celery,node_tasks toneAmber
class node_sync,node_servicenow_client,node_chunker,node_embedding,node_vector_store,node_kb_state toneMint
class node_retriever,node_worker toneRose
class node_legacy_executor,node_prompt,node_schemas,node_validators,node_servicenow toneIndigo
```

## Components

### Event Intake

- [Incident Rule](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/businessRule/business_rule.js): `businessRule/business_rule.js`
- [FastAPI App](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/main.py): `src/barq_ai_support/main.py`
- [Incident Webhook](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/webhook.py): `src/barq_ai_support/webhook.py`
- [KB Webhook](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/kb_webhook.py): `src/barq_ai_support/kb_webhook.py`

### Async Processing

- [Task Queue](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/celery_app.py): `src/barq_ai_support/celery_app.py`
- [Background Tasks](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/tasks.py): `src/barq_ai_support/tasks.py`

### Knowledge Pipeline

- [KB Sync](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/kb_sync_service.py): `src/barq_ai_support/kb_sync_service.py`
- [ServiceNow Client](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/servicenow_client.py): `src/barq_ai_support/servicenow_client.py`
- [Article Chunker](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/ingestion/chunker.py): `src/barq_ai_support/ingestion/chunker.py`
- [Embedding](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/ingestion/embedding.py): `src/barq_ai_support/ingestion/embedding.py`
- [Qdrant Index](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/ingestion/qdrant_store.py): `src/barq_ai_support/ingestion/qdrant_store.py`
- [KB State](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/kb_state_store.py): `src/barq_ai_support/kb_state_store.py`

### Incident Assistant

- [Semantic Retrieval](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/retrieval/retriever.py): `src/barq_ai_support/retrieval/retriever.py`
- [Agent Worker](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/src/barq_ai_support/agent/s3_worker.py): `src/barq_ai_support/agent/s3_worker.py`

### Grounded Agent

- [Grounded Executor](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/agent/executor.py): `agent/executor.py`
- [Grounding Prompt](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/agent/prompt.py): `agent/prompt.py`
- [Agent Schemas](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/agent/schemas.py): `agent/schemas.py`
- [Output Validators](https://github.com/mohatemtc/barq-sprints-ai-servicenow-support-assistant-4/blob/main/agent/validators.py): `agent/validators.py`

### Other components

- **ServiceNow**
- **Support Reviewer**

## Connections

- ServiceNow → Incident Rule: creates incident (evidence: `README.md`)
- Incident Rule → Incident Webhook: posts event (evidence: `README.md`)
- FastAPI App → Incident Webhook: mounts route (evidence: `src/barq_ai_support/main.py`)
- FastAPI App → KB Webhook: mounts route (evidence: `src/barq_ai_support/main.py`)
- Incident Webhook → Background Tasks: dispatches task (evidence: `src/barq_ai_support/webhook.py`)
- KB Webhook → Background Tasks: dispatches task (evidence: `src/barq_ai_support/kb_webhook.py`)
- Background Tasks → Task Queue: registers tasks (evidence: `src/barq_ai_support/tasks.py`)
- Background Tasks → Agent Worker: runs agent (evidence: `src/barq_ai_support/tasks.py`)
- Background Tasks → KB Sync: runs sync (evidence: `src/barq_ai_support/tasks.py`)
- KB Sync → ServiceNow Client: fetches article (evidence: `src/barq_ai_support/kb_sync_service.py`)
- ServiceNow Client → ServiceNow: reads and writes (evidence: `src/barq_ai_support/servicenow_client.py`)
- KB Sync → Article Chunker: chunks article (evidence: `src/barq_ai_support/kb_sync_service.py`)
- KB Sync → Qdrant Index: updates index (evidence: `src/barq_ai_support/kb_sync_service.py`)
- KB Sync → KB State: tracks changes (evidence: `src/barq_ai_support/kb_sync_service.py`)
- Semantic Retrieval → Qdrant Index: queries index (evidence: `src/barq_ai_support/retrieval/retriever.py`)
- Agent Worker → Semantic Retrieval: searches knowledge (evidence: `src/barq_ai_support/agent/s3_worker.py`)
- Agent Worker → ServiceNow Client: loads and updates (evidence: `src/barq_ai_support/agent/s3_worker.py`)
- Agent Worker → Embedding: uses embeddings (evidence: `src/barq_ai_support/agent/s3_worker.py`)
- Agent Worker → Support Reviewer: suggests for review (evidence: `README.md`)
- Grounded Executor → Grounding Prompt: builds prompt (evidence: `agent/executor.py`)
- Grounded Executor → Agent Schemas: validates inputs (evidence: `agent/executor.py`)
- Grounded Executor → Output Validators: validates output (evidence: `agent/executor.py`)
