# f3nd1/intelligence-dashboard-v2 architecture

> Architecture diagram of the GitHub repository f3nd1/intelligence-dashboard-v2, 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/f3nd1/intelligence-dashboard-v2
- Repository: https://github.com/f3nd1/intelligence-dashboard-v2

## Overview

UCC Intelligence is a Frappe-based institutional analytics and staff-support platform. Staff enter through dashboard and Ask UCC interfaces; analytics requests produce criterion views and drilldowns, while Ask UCC combines domain lookups with guarded AI explanations. Separate administrative workflows manage knowledge documents, monitoring findings, permissions, and proposed actions. The README also documents a Custom HTML Block visual catalogue and live panels. Some subsystem links below rely on the SOURCE INDEX’s file references; unsampled implementation details and runtime wiring are not asserted.

Main entry points: [`ucc_intelligence/ucc_intelligence/api.py`](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/api.py) (Whitelisted API), [`ucc_intelligence/ucc_intelligence/ai/orchestration.py`](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/ai/orchestration.py) (Answer orchestration), [`ucc_intelligence/ucc_intelligence/operations/service.py`](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/operations/service.py) (Operations workspace), [`ucc_intelligence/ucc_intelligence/knowledge/retrieval.py`](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/knowledge/retrieval.py) (Knowledge retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Staff interfaces"]
  node_custom_block["Dashboard block<br/>[JAVASCRIPT.js]"]
  node_platform_ui["Platform runtime"]
  node_explore_ui["Explore runtime"]
  node_live_ui["Live panels"]
  node_visual_nav["Visual navigation"]
end

subgraph group_analytics["Analytics"]
  node_analytics["Criterion analytics"]
  node_analytics_contracts["Analytics contracts<br/>[contracts.py]"]
  node_drilldown["Analytics drilldown<br/>[drilldown.py]"]
end

subgraph group_ask["Ask UCC"]
  node_ask_modules["Ask domain tools"]
  node_guided["Guided questions"]
  node_orchestration["Answer orchestration<br/>[orchestration.py]"]
  node_ai_client["AI provider client<br/>[client.py]"]
end

subgraph group_operations["Operations"]
  node_knowledge_ingest["Knowledge ingestion<br/>[ingestion.py]"]
  node_retrieval["Knowledge retrieval<br/>[retrieval.py]"]
  node_monitor_engine["Monitoring engine<br/>[engine.py]"]
  node_monitor_rules["Monitoring rules<br/>[rule_registry.py]"]
  node_operations_service["Operations workspace<br/>[service.py]"]
  node_action_service["Action approval<br/>[service.py]"]
  node_action_registry["Action registry<br/>[registry.py]"]
end

subgraph group_platform["Platform services"]
  node_api["Whitelisted API<br/>[api.py]"]
  node_access["Dashboard access<br/>[access.py]"]
end

node_staff(("Staff user"))
node_ai_provider["OpenAI service"]

node_staff -->|"uses"| node_custom_block
node_custom_block -->|"mounts"| node_visual_nav
node_staff -->|"uses"| node_platform_ui
node_platform_ui -.->|"requests"| node_api
node_explore_ui -.->|"requests"| node_api
node_live_ui -.->|"requests"| node_api
node_api -->|"dispatches criteria"| node_analytics
node_api -->|"dispatches"| node_drilldown
node_api -->|"uses contract"| node_analytics_contracts
node_analytics -.->|"standardizes responses"| node_analytics_contracts
node_api -->|"dispatches Ask"| node_orchestration
node_api -->|"routes tools"| node_ask_modules
node_staff -.->|"asks questions"| node_api
node_orchestration -->|"routes questions"| node_guided
node_orchestration -->|"calls domain tools"| node_ask_modules
node_orchestration -->|"requests completion"| node_ai_client
node_ai_client -->|"sends API request"| node_ai_provider
node_operations_service -->|"reads rule definitions"| node_monitor_rules
node_operations_service -->|"runs monitoring"| node_monitor_engine
node_monitor_engine -->|"evaluates rules"| node_monitor_rules
node_operations_service -->|"manages indexing"| node_knowledge_ingest
node_knowledge_ingest -->|"indexes sections"| node_retrieval
node_api -->|"searches knowledge"| node_retrieval
node_orchestration -.->|"retrieves facts"| node_retrieval
node_action_service -->|"resolves action"| node_action_registry
node_api -.->|"resolves access"| node_access

click node_custom_block "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/custom-html-block/JAVASCRIPT.js"
click node_platform_ui "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/src/js/10-platform-runtime.js"
click node_explore_ui "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/src/js/20-explore-runtime.js"
click node_live_ui "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/src/js/30-live-foundation-runtime.js"
click node_visual_nav "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/src/js/40-visual-navigation-runtime.js"
click node_api "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/api.py"
click node_analytics "https://github.com/f3nd1/intelligence-dashboard-v2/tree/main/ucc_intelligence/ucc_intelligence/analytics"
click node_analytics_contracts "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/analytics/contracts.py"
click node_drilldown "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/analytics/drilldown.py"
click node_ask_modules "https://github.com/f3nd1/intelligence-dashboard-v2/tree/main/ucc_intelligence/ucc_intelligence/ask_ucc"
click node_guided "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/ask_ucc/guided_questions.py"
click node_orchestration "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/ai/orchestration.py"
click node_ai_client "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/ai/client.py"
click node_knowledge_ingest "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/knowledge/ingestion.py"
click node_retrieval "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/knowledge/retrieval.py"
click node_monitor_engine "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/monitoring/engine.py"
click node_monitor_rules "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/monitoring/rule_registry.py"
click node_operations_service "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/operations/service.py"
click node_action_service "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/actions/service.py"
click node_action_registry "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/actions/registry.py"
click node_access "https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/permissions/access.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_custom_block,node_platform_ui,node_explore_ui,node_live_ui,node_visual_nav,node_staff toneBlue
class node_analytics,node_analytics_contracts,node_drilldown toneAmber
class node_ask_modules,node_guided,node_orchestration,node_ai_client toneMint
class node_knowledge_ingest,node_retrieval,node_monitor_engine,node_monitor_rules,node_operations_service,node_action_service,node_action_registry toneRose
class node_api,node_access,node_ai_provider toneIndigo
```

## Components

### Staff interfaces

- [Dashboard block](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/custom-html-block/JAVASCRIPT.js): `custom-html-block/JAVASCRIPT.js`
- [Platform runtime](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/src/js/10-platform-runtime.js): `src/js/10-platform-runtime.js`
- [Explore runtime](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/src/js/20-explore-runtime.js): `src/js/20-explore-runtime.js`
- [Live panels](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/src/js/30-live-foundation-runtime.js): `src/js/30-live-foundation-runtime.js`
- [Visual navigation](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/src/js/40-visual-navigation-runtime.js): `src/js/40-visual-navigation-runtime.js`

### Analytics

- [Criterion analytics](https://github.com/f3nd1/intelligence-dashboard-v2/tree/main/ucc_intelligence/ucc_intelligence/analytics): `ucc_intelligence/ucc_intelligence/analytics`
- [Analytics contracts](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/analytics/contracts.py): `ucc_intelligence/ucc_intelligence/analytics/contracts.py`
- [Analytics drilldown](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/analytics/drilldown.py): `ucc_intelligence/ucc_intelligence/analytics/drilldown.py`

### Ask UCC

- [Ask domain tools](https://github.com/f3nd1/intelligence-dashboard-v2/tree/main/ucc_intelligence/ucc_intelligence/ask_ucc): `ucc_intelligence/ucc_intelligence/ask_ucc`
- [Guided questions](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/ask_ucc/guided_questions.py): `ucc_intelligence/ucc_intelligence/ask_ucc/guided_questions.py`
- [Answer orchestration](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/ai/orchestration.py): `ucc_intelligence/ucc_intelligence/ai/orchestration.py`
- [AI provider client](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/ai/client.py): `ucc_intelligence/ucc_intelligence/ai/client.py`

### Operations

- [Knowledge ingestion](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/knowledge/ingestion.py): `ucc_intelligence/ucc_intelligence/knowledge/ingestion.py`
- [Knowledge retrieval](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/knowledge/retrieval.py): `ucc_intelligence/ucc_intelligence/knowledge/retrieval.py`
- [Monitoring engine](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/monitoring/engine.py): `ucc_intelligence/ucc_intelligence/monitoring/engine.py`
- [Monitoring rules](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/monitoring/rule_registry.py): `ucc_intelligence/ucc_intelligence/monitoring/rule_registry.py`
- [Operations workspace](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/operations/service.py): `ucc_intelligence/ucc_intelligence/operations/service.py`
- [Action approval](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/actions/service.py): `ucc_intelligence/ucc_intelligence/actions/service.py`
- [Action registry](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/actions/registry.py): `ucc_intelligence/ucc_intelligence/actions/registry.py`

### Platform services

- [Whitelisted API](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/api.py): `ucc_intelligence/ucc_intelligence/api.py`
- [Dashboard access](https://github.com/f3nd1/intelligence-dashboard-v2/blob/main/ucc_intelligence/ucc_intelligence/permissions/access.py): `ucc_intelligence/ucc_intelligence/permissions/access.py`

### Other components

- **Staff user**
- **OpenAI service**

## Connections

- Staff user → Dashboard block: uses
- Dashboard block → Visual navigation: mounts
- Staff user → Platform runtime: uses
- Platform runtime → Whitelisted API: requests
- Explore runtime → Whitelisted API: requests
- Live panels → Whitelisted API: requests
- Whitelisted API → Criterion analytics: dispatches criteria (evidence: `ucc_intelligence/ucc_intelligence/api.py`)
- Whitelisted API → Analytics drilldown: dispatches (evidence: `ucc_intelligence/ucc_intelligence/api.py`)
- Whitelisted API → Analytics contracts: uses contract (evidence: `ucc_intelligence/ucc_intelligence/api.py`)
- Criterion analytics → Analytics contracts: standardizes responses (evidence: `ucc_intelligence/ucc_intelligence/analytics/criterion_4_admission.py`)
- Whitelisted API → Answer orchestration: dispatches Ask (evidence: `ucc_intelligence/ucc_intelligence/api.py`)
- Whitelisted API → Ask domain tools: routes tools (evidence: `ucc_intelligence/ucc_intelligence/api.py`)
- Staff user → Whitelisted API: asks questions
- Answer orchestration → Guided questions: routes questions (evidence: `ucc_intelligence/ucc_intelligence/ai/orchestration.py`)
- Answer orchestration → Ask domain tools: calls domain tools (evidence: `ucc_intelligence/ucc_intelligence/ai/orchestration.py`)
- Answer orchestration → AI provider client: requests completion (evidence: `ucc_intelligence/ucc_intelligence/ai/orchestration.py`)
- AI provider client → OpenAI service: sends API request (evidence: `ucc_intelligence/ucc_intelligence/ai/client.py`)
- Operations workspace → Monitoring rules: reads rule definitions (evidence: `ucc_intelligence/ucc_intelligence/operations/service.py`)
- Operations workspace → Monitoring engine: runs monitoring (evidence: `ucc_intelligence/ucc_intelligence/operations/service.py`)
- Monitoring engine → Monitoring rules: evaluates rules (evidence: `ucc_intelligence/ucc_intelligence/monitoring/engine.py`)
- Operations workspace → Knowledge ingestion: manages indexing (evidence: `ucc_intelligence/ucc_intelligence/operations/service.py`)
- Knowledge ingestion → Knowledge retrieval: indexes sections (evidence: `ucc_intelligence/ucc_intelligence/knowledge/ingestion.py`)
- Whitelisted API → Knowledge retrieval: searches knowledge (evidence: `ucc_intelligence/ucc_intelligence/api.py`)
- Answer orchestration → Knowledge retrieval: retrieves facts
- Action approval → Action registry: resolves action (evidence: `ucc_intelligence/ucc_intelligence/actions/service.py`)
- Whitelisted API → Dashboard access: resolves access (evidence: `ucc_intelligence/ucc_intelligence/api.py`)
