# akhileshjoshi10/ai-powered-operating-intelligence-platform architecture

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

- Interactive diagram: https://gitdiagram.com/akhileshjoshi10/ai-powered-operating-intelligence-platform
- Repository: https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform

## Overview

SmartMart is an operating-intelligence platform that turns business data into reviewed management actions and executive briefs. Its documented workflow runs from validation and storage through deterministic analysis, issue prioritization, evidence-based diagnosis, agent enhancement, recommendations, human approval, tasks, and automation. The graph preserves major documented capabilities, including knowledge retrieval and controlled tools. README-documented relationships are cited there; source-level wiring is limited to shown imports and calls. Several major subsystems are represented by their exact service or analytics paths, but their unsampled internals are not asserted.

Main entry points: [`backend/app/agents/orchestrator.py`](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/agents/orchestrator.py) (Multi-agent workflow), [`backend/database.py`](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/database.py) (PostgreSQL store), [`backend/app/services/llm_tool_execution_service.py`](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/llm_tool_execution_service.py) (LLM tool execution), [`backend/app/main.py`](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/main.py) (FastAPI control layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data foundation"]
  node_import_validation["Import and validation"]
  node_operational_store[("PostgreSQL store<br/>[database.py]")]
end

subgraph group_intelligence["Business intelligence"]
  node_analytics["Deterministic analytics<br/>[priority_engine.py]"]
  node_issue_detection["Issue detection<br/>[issue_detection.py]"]
  node_priority["Priority ranking<br/>[priority_engine.py]"]
  node_evidence_root_cause["Evidence and root cause"]
end

subgraph group_agents["Agent decision support"]
  node_knowledge["Knowledge retrieval"]
  node_controlled_tools["Controlled tools<br/>[tool_executor.py]"]
  node_agent_workflow["Multi-agent workflow<br/>[orchestrator.py]"]
  node_llm_tool_loop["LLM tool execution"]
  node_llm_provider["LLM providers<br/>[groq_provider.py]"]
end

subgraph group_execution["Action and oversight"]
  node_recommendations["Recommendations"]
  node_manager_review["Manager review<br/>[recommendations.py]"]
  node_tasks[("Task tracking<br/>[task_service.py]")]
  node_automation["Workflow automation"]
  node_executive_briefs["Executive briefs"]
end

subgraph group_interface["Application access"]
  node_api["FastAPI control layer<br/>[main.py]"]
  node_web_auth["Web authentication<br/>[tokenStorage.ts]"]
end

node_business_data[("Business data")]
node_manager(("Manager / application user"))
node_n8n["n8n automation"]

node_business_data -->|"ingests and validates"| node_import_validation
node_import_validation -->|"loads data"| node_operational_store
node_operational_store -->|"supplies data"| node_analytics
node_analytics -->|"detects risks"| node_issue_detection
node_issue_detection -->|"ranks issues"| node_priority
node_priority -->|"supports diagnosis"| node_evidence_root_cause
node_evidence_root_cause -->|"enhances analysis"| node_agent_workflow
node_knowledge -->|"provides retrieved knowledge"| node_agent_workflow
node_controlled_tools -->|"provides tool outputs"| node_agent_workflow
node_agent_workflow -.->|"uses controlled tools"| node_llm_tool_loop
node_llm_tool_loop -->|"requests generation"| node_llm_provider
node_llm_tool_loop -->|"executes tool calls"| node_controlled_tools
node_agent_workflow -->|"generates actions"| node_recommendations
node_recommendations -->|"submits for review"| node_manager_review
node_manager_review -->|"converts approved actions"| node_tasks
node_tasks -->|"triggers follow-ups"| node_automation
node_automation -->|"dispatches workflows"| node_n8n
node_api -->|"serves brief routes"| node_executive_briefs
node_api -->|"serves chief-of-staff route"| node_agent_workflow
node_operational_store -->|"informs briefs"| node_executive_briefs
node_manager -->|"authenticates"| node_web_auth
node_web_auth -.->|"calls authenticated API"| node_api
node_manager -->|"accepts, edits, or rejects"| node_manager_review

click node_import_validation "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/data_import_service.py"
click node_operational_store "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/database.py"
click node_analytics "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/analytics/priority_engine.py"
click node_issue_detection "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/analytics/issue_detection.py"
click node_priority "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/analytics/priority_engine.py"
click node_evidence_root_cause "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/analytics/root_cause_analysis.py"
click node_knowledge "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/knowledge_service.py"
click node_controlled_tools "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/tools/tool_executor.py"
click node_agent_workflow "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/agents/orchestrator.py"
click node_llm_tool_loop "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/llm_tool_execution_service.py"
click node_llm_provider "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/llm/groq_provider.py"
click node_recommendations "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/recommendation_service.py"
click node_manager_review "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/routers/recommendations.py"
click node_tasks "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/task_service.py"
click node_automation "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/automation_service.py"
click node_executive_briefs "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/executive_brief_service.py"
click node_api "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/main.py"
click node_web_auth "https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/frontend/src/auth/tokenStorage.ts"

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_import_validation,node_operational_store,node_manager toneBlue
class node_analytics,node_issue_detection,node_priority,node_evidence_root_cause,node_business_data toneAmber
class node_knowledge,node_controlled_tools,node_agent_workflow,node_llm_tool_loop,node_llm_provider toneMint
class node_recommendations,node_manager_review,node_tasks,node_automation,node_executive_briefs toneRose
class node_api,node_web_auth,node_n8n toneIndigo
```

## Components

### Data foundation

- [Import and validation](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/data_import_service.py): `backend/app/services/data_import_service.py`
- [PostgreSQL store](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/database.py): `backend/database.py`

### Business intelligence

- [Deterministic analytics](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/analytics/priority_engine.py): `backend/analytics/priority_engine.py`
- [Issue detection](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/analytics/issue_detection.py): `backend/analytics/issue_detection.py`
- [Priority ranking](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/analytics/priority_engine.py): `backend/analytics/priority_engine.py`
- [Evidence and root cause](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/analytics/root_cause_analysis.py): `backend/analytics/root_cause_analysis.py`

### Agent decision support

- [Knowledge retrieval](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/knowledge_service.py): `backend/app/services/knowledge_service.py`
- [Controlled tools](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/tools/tool_executor.py): `backend/app/tools/tool_executor.py`
- [Multi-agent workflow](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/agents/orchestrator.py): `backend/app/agents/orchestrator.py`
- [LLM tool execution](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/llm_tool_execution_service.py): `backend/app/services/llm_tool_execution_service.py`
- [LLM providers](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/llm/groq_provider.py): `backend/app/llm/groq_provider.py`

### Action and oversight

- [Recommendations](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/recommendation_service.py): `backend/app/services/recommendation_service.py`
- [Manager review](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/routers/recommendations.py): `backend/app/routers/recommendations.py`
- [Task tracking](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/task_service.py): `backend/app/services/task_service.py`
- [Workflow automation](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/automation_service.py): `backend/app/services/automation_service.py`
- [Executive briefs](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/services/executive_brief_service.py): `backend/app/services/executive_brief_service.py`

### Application access

- [FastAPI control layer](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/backend/app/main.py): `backend/app/main.py`
- [Web authentication](https://github.com/akhileshjoshi10/ai-powered-operating-intelligence-platform/blob/main/frontend/src/auth/tokenStorage.ts): `frontend/src/auth/tokenStorage.ts`

### Other components

- **Business data**
- **Manager / application user**
- **n8n automation**

## Connections

- Business data → Import and validation: ingests and validates (evidence: `README.md`)
- Import and validation → PostgreSQL store: loads data (evidence: `README.md`)
- PostgreSQL store → Deterministic analytics: supplies data (evidence: `README.md`)
- Deterministic analytics → Issue detection: detects risks (evidence: `README.md`)
- Issue detection → Priority ranking: ranks issues (evidence: `README.md`)
- Priority ranking → Evidence and root cause: supports diagnosis (evidence: `README.md`)
- Evidence and root cause → Multi-agent workflow: enhances analysis (evidence: `README.md`)
- Knowledge retrieval → Multi-agent workflow: provides retrieved knowledge (evidence: `README.md`)
- Controlled tools → Multi-agent workflow: provides tool outputs (evidence: `README.md`)
- Multi-agent workflow → LLM tool execution: uses controlled tools
- LLM tool execution → LLM providers: requests generation (evidence: `backend/app/services/llm_tool_execution_service.py`)
- LLM tool execution → Controlled tools: executes tool calls (evidence: `backend/app/services/llm_tool_execution_service.py`)
- Multi-agent workflow → Recommendations: generates actions (evidence: `README.md`)
- Recommendations → Manager review: submits for review (evidence: `README.md`)
- Manager review → Task tracking: converts approved actions
- Task tracking → Workflow automation: triggers follow-ups (evidence: `README.md`)
- Workflow automation → n8n automation: dispatches workflows (evidence: `README.md`)
- FastAPI control layer → Executive briefs: serves brief routes (evidence: `backend/app/main.py`)
- FastAPI control layer → Multi-agent workflow: serves chief-of-staff route (evidence: `backend/app/main.py`)
- PostgreSQL store → Executive briefs: informs briefs (evidence: `README.md`)
- Manager / application user → Web authentication: authenticates
- Web authentication → FastAPI control layer: calls authenticated API
- Manager / application user → Manager review: accepts, edits, or rejects (evidence: `README.md`)
