# surya2406/business_agent architecture

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

- Interactive diagram: https://gitdiagram.com/surya2406/business_agent
- Repository: https://github.com/surya2406/business_agent

## Overview

#### Purpose and Entry Points
This is a full-stack enterprise sales/operations intelligence application: it manages customers, products, orders, offers, campaigns, and AI-generated analytics/recommendations. The backend starts at `backend/main.py`; versioned HTTP endpoints are under `backend/app/api/v1`. The Vite/React frontend starts at `frontend/src/main.jsx` and composes the application in `frontend/src/App.jsx`.

#### API and Application Boundary
FastAPI-style route modules expose domain and AI capabilities, separating browser-facing requests from service and persistence logic. Key surfaces include AI/analytics (`backend/app/api/v1/routes_ai.py`, `backend/app/api/v1/routes_analytics.py`), operational entities (`backend/app/api/v1/routes_customers.py`, `backend/app/api/v1/routes_orders.py`), and engagement actions (`backend/app/api/v1/routes_campaigns.py`, `backend/app/api/v1/routes_followups.py`).

#### Persistence Layer
Relational persistence is modeled through domain and AI entities in `backend/app/models/customer.py`, `backend/app/models/order.py`, and `backend/app/models/ai_models.py`. Database initialization/session ownership is centralized in `backend/app/database/base.py` and `backend/app/database/session.py`; repositories mediate data access, e.g. `backend/app/repositories/customer_repo.py` and `backend/app/repositories/ai_repo.py`. Alembic provides schema migration history from `backend/alembic/env.py` and `backend/alembic/versions/7dbcdcdd7461_initial_schema.py`.

#### AI Orchestration and Analytics
The AI layer accepts business questions, analyzes conversations, and produces follow-ups or recommendations. `backend/app/ai/orchestrator_agent.py` coordinates specialist agents; `backend/app/ai/multi_agent/descriptive_agent.py`, `backend/app/ai/multi_agent/diagnostic_agent.py`, `backend/app/ai/multi_agent/predictive_agent.py`, and `backend/app/ai/multi_agent/prescriptive_agent.py` represent the main analysis modes. Model-provider access is isolated behind `backend/app/ai/openai_client.py`, while `backend/app/ai/adk_agent.py` indicates an additional ADK-based agent integration.

#### Knowledge-Grounded Agent Behavior
Analytics agents are constrained by repository-managed skills, lookup tables, and playbooks rather than only free-form prompting. Core skill definitions live in `backend/app/ai/skills/descriptive-analytics/SKILL.md`, `backend/app/ai/skills/diagnostic-analytics/SKILL.md`, and `backend/app/ai/skills/predictive-analytics/SKILL.md`; their YAML references supply domain questions, query templates, diagnostics, and prescribed actions. General prompt templates are maintained separately in `backend/app/prompts/business_assistant.txt` and `backend/app/prompts/conversation_analysis.txt`.

#### Domain Intelligence and Automation
Service modules translate stored operational data and agent output into product features: dashboard aggregation (`backend/app/services/dashboard_service.py`), customer health (`backend/app/services/customer_health.py`), campaign generation (`backend/app/services/campaign_generator.py`), and recommendations (`backend/app/services/ai_recommendation_engine.py`). Scheduled/background automation is concentrated in `backend/app/scheduler/jobs.py`. External-channel and platform boundaries are explicit in `backend/app/services/whatsapp_sender.py` and `backend/app/services/meta_sync_service.py`.

#### Frontend Composition
The React SPA calls backend APIs through `frontend/src/api/index.js`, maintains AI interaction state in `frontend/src/contexts/AIContext.jsx`, and presents workflow pages such as `frontend/src/pages/Dashboard.jsx`, `frontend/src/pages/Analytics.jsx`, and `frontend/src/pages/AIAssistant.jsx`. Reusable AI interaction surfaces—chat, insight presentation, and campaign authoring—are in `frontend/src/components/ui/IntentChatHub.jsx`, `frontend/src/components/ui/AIInsightsPanel.jsx`, and `frontend/src/components/ui/CampaignStudio.jsx`. The client runtime is Vite/React, while the backend is Python with database migrations and OpenAI/ADK, Meta, and WhatsApp integration boundaries.

Main entry points: [`backend/app/ai/orchestrator_agent.py`](https://github.com/surya2406/business_agent/blob/main/backend/app/ai/orchestrator_agent.py) (AI orchestrator), [`backend/app/api/v1`](https://github.com/surya2406/business_agent/tree/main/backend/app/api/v1) (Versioned routes), [`backend/app/services/dashboard_service.py`](https://github.com/surya2406/business_agent/blob/main/backend/app/services/dashboard_service.py) (Domain intelligence), [`frontend/src/pages/Analytics.jsx`](https://github.com/surya2406/business_agent/blob/main/frontend/src/pages/Analytics.jsx) (Workflow pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_frontend_entry["Vite entry<br/>React bootstrap<br/>[main.jsx]"]
  node_frontend_app["Application shell<br/>React app<br/>[App.jsx]"]
  node_frontend_pages["Workflow pages<br/>Dashboard, analytics &amp; assistant<br/>[Analytics.jsx]"]
  node_frontend_ai_ui["AI workflow UI<br/>Chat, insights &amp; campaigns<br/>[IntentChatHub.jsx]"]
  node_ai_context["AI client state<br/>React context<br/>[AIContext.jsx]"]
  node_api_client["API client<br/>Frontend transport<br/>[index.js]"]
end

subgraph group_api["Backend API"]
  node_backend_entry["Backend entry<br/>FastAPI application<br/>[main.py]"]
  node_routes["Versioned routes"]
  node_domain_services["Domain intelligence<br/>Feature services"]
end

subgraph group_intelligence["AI &amp; Automation"]
  node_orchestrator["AI orchestrator<br/>Agent coordinator"]
  node_specialist_agents["Analytics specialists<br/>Descriptive through prescriptive agents"]
  node_skills["Analytics skills<br/>Grounding playbooks<br/>[SKILL.md]"]
  node_prompts["Prompt templates<br/>Agent prompts"]
  node_model_clients["Model integrations<br/>OpenAI &amp; ADK boundary<br/>[openai_client.py]"]
  node_scheduler["Background jobs<br/>Scheduled automation<br/>[jobs.py]"]
end

subgraph group_data["Data Platform"]
  node_repositories["Repositories<br/>Data access layer<br/>[customer_repo.py]"]
  node_domain_models["Domain &amp; AI models<br/>Relational entities<br/>[customer.py]"]
  node_database[("Database session<br/>Relational persistence<br/>[session.py]")]
  node_migrations["Schema migrations<br/>Alembic history<br/>[env.py]"]
end

subgraph group_external["External Channels"]
  node_external_channels["Meta &amp; WhatsApp<br/>Channel integrations<br/>[whatsapp_sender.py]"]
end

node_frontend_entry -->|"mounts"| node_frontend_app
node_frontend_app -->|"composes"| node_frontend_pages
node_frontend_pages -->|"uses"| node_frontend_ai_ui
node_frontend_ai_ui -->|"updates"| node_ai_context
node_frontend_pages -->|"calls through"| node_api_client
node_api_client -->|"HTTP requests"| node_routes
node_backend_entry -->|"serves"| node_routes
node_routes -->|"invokes"| node_domain_services
node_routes -->|"submits AI requests"| node_orchestrator
node_domain_services -->|"reads and writes"| node_repositories
node_domain_services -->|"sends and syncs"| node_external_channels
node_orchestrator -->|"delegates analysis"| node_specialist_agents
node_specialist_agents -->|"grounds with"| node_skills
node_orchestrator -->|"uses"| node_prompts
node_orchestrator -->|"requests inference"| node_model_clients
node_orchestrator -->|"queries business data"| node_repositories
node_scheduler -->|"runs automation"| node_domain_services
node_repositories -->|"maps"| node_domain_models
node_domain_models -->|"persists in"| node_database
node_migrations -->|"evolves schema"| node_database

click node_frontend_entry "https://github.com/surya2406/business_agent/blob/main/frontend/src/main.jsx"
click node_frontend_app "https://github.com/surya2406/business_agent/blob/main/frontend/src/App.jsx"
click node_frontend_pages "https://github.com/surya2406/business_agent/blob/main/frontend/src/pages/Analytics.jsx"
click node_frontend_ai_ui "https://github.com/surya2406/business_agent/blob/main/frontend/src/components/ui/IntentChatHub.jsx"
click node_ai_context "https://github.com/surya2406/business_agent/blob/main/frontend/src/contexts/AIContext.jsx"
click node_api_client "https://github.com/surya2406/business_agent/blob/main/frontend/src/api/index.js"
click node_backend_entry "https://github.com/surya2406/business_agent/blob/main/backend/main.py"
click node_routes "https://github.com/surya2406/business_agent/tree/main/backend/app/api/v1"
click node_domain_services "https://github.com/surya2406/business_agent/blob/main/backend/app/services/dashboard_service.py"
click node_orchestrator "https://github.com/surya2406/business_agent/blob/main/backend/app/ai/orchestrator_agent.py"
click node_specialist_agents "https://github.com/surya2406/business_agent/blob/main/backend/app/ai/multi_agent/descriptive_agent.py"
click node_skills "https://github.com/surya2406/business_agent/blob/main/backend/app/ai/skills/descriptive-analytics/SKILL.md"
click node_prompts "https://github.com/surya2406/business_agent/blob/main/backend/app/prompts/business_assistant.txt"
click node_model_clients "https://github.com/surya2406/business_agent/blob/main/backend/app/ai/openai_client.py"
click node_scheduler "https://github.com/surya2406/business_agent/blob/main/backend/app/scheduler/jobs.py"
click node_repositories "https://github.com/surya2406/business_agent/blob/main/backend/app/repositories/customer_repo.py"
click node_domain_models "https://github.com/surya2406/business_agent/blob/main/backend/app/models/customer.py"
click node_database "https://github.com/surya2406/business_agent/blob/main/backend/app/database/session.py"
click node_migrations "https://github.com/surya2406/business_agent/blob/main/backend/alembic/env.py"
click node_external_channels "https://github.com/surya2406/business_agent/blob/main/backend/app/services/whatsapp_sender.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_frontend_entry,node_frontend_app,node_frontend_pages,node_frontend_ai_ui,node_ai_context,node_api_client toneBlue
class node_backend_entry,node_routes,node_domain_services toneAmber
class node_orchestrator,node_specialist_agents,node_skills,node_prompts,node_model_clients,node_scheduler toneMint
class node_repositories,node_domain_models,node_database,node_migrations toneRose
class node_external_channels toneIndigo
```

## Components

### React SPA

- [Vite entry](https://github.com/surya2406/business_agent/blob/main/frontend/src/main.jsx): React bootstrap · `frontend/src/main.jsx`
- [Application shell](https://github.com/surya2406/business_agent/blob/main/frontend/src/App.jsx): React app · `frontend/src/App.jsx`
- [Workflow pages](https://github.com/surya2406/business_agent/blob/main/frontend/src/pages/Analytics.jsx): Dashboard, analytics & assistant · `frontend/src/pages/Analytics.jsx`
- [AI workflow UI](https://github.com/surya2406/business_agent/blob/main/frontend/src/components/ui/IntentChatHub.jsx): Chat, insights & campaigns · `frontend/src/components/ui/IntentChatHub.jsx`
- [AI client state](https://github.com/surya2406/business_agent/blob/main/frontend/src/contexts/AIContext.jsx): React context · `frontend/src/contexts/AIContext.jsx`
- [API client](https://github.com/surya2406/business_agent/blob/main/frontend/src/api/index.js): Frontend transport · `frontend/src/api/index.js`

### Backend API

- [Backend entry](https://github.com/surya2406/business_agent/blob/main/backend/main.py): FastAPI application · `backend/main.py`
- [Versioned routes](https://github.com/surya2406/business_agent/tree/main/backend/app/api/v1): HTTP domain & AI APIs · Customers, orders, campaigns, follow-ups, AI, and analytics endpoints. · `backend/app/api/v1`
- [Domain intelligence](https://github.com/surya2406/business_agent/blob/main/backend/app/services/dashboard_service.py): Feature services · Dashboard, health, campaigns, and recommendations. · `backend/app/services/dashboard_service.py`

### AI & Automation

- [AI orchestrator](https://github.com/surya2406/business_agent/blob/main/backend/app/ai/orchestrator_agent.py): Agent coordinator · `backend/app/ai/orchestrator_agent.py`
- [Analytics specialists](https://github.com/surya2406/business_agent/blob/main/backend/app/ai/multi_agent/descriptive_agent.py): Descriptive through prescriptive agents · `backend/app/ai/multi_agent/descriptive_agent.py`
- [Analytics skills](https://github.com/surya2406/business_agent/blob/main/backend/app/ai/skills/descriptive-analytics/SKILL.md): Grounding playbooks · Skill files and YAML references constrain analytical behavior. · `backend/app/ai/skills/descriptive-analytics/SKILL.md`
- [Prompt templates](https://github.com/surya2406/business_agent/blob/main/backend/app/prompts/business_assistant.txt): Agent prompts · `backend/app/prompts/business_assistant.txt`
- [Model integrations](https://github.com/surya2406/business_agent/blob/main/backend/app/ai/openai_client.py): OpenAI & ADK boundary · `backend/app/ai/openai_client.py`
- [Background jobs](https://github.com/surya2406/business_agent/blob/main/backend/app/scheduler/jobs.py): Scheduled automation · `backend/app/scheduler/jobs.py`

### Data Platform

- [Repositories](https://github.com/surya2406/business_agent/blob/main/backend/app/repositories/customer_repo.py): Data access layer · `backend/app/repositories/customer_repo.py`
- [Domain & AI models](https://github.com/surya2406/business_agent/blob/main/backend/app/models/customer.py): Relational entities · `backend/app/models/customer.py`
- [Database session](https://github.com/surya2406/business_agent/blob/main/backend/app/database/session.py): Relational persistence · Centralized initialization and session ownership. · `backend/app/database/session.py`
- [Schema migrations](https://github.com/surya2406/business_agent/blob/main/backend/alembic/env.py): Alembic history · `backend/alembic/env.py`

### External Channels

- [Meta & WhatsApp](https://github.com/surya2406/business_agent/blob/main/backend/app/services/whatsapp_sender.py): Channel integrations · `backend/app/services/whatsapp_sender.py`

## Connections

- Vite entry → Application shell: mounts
- Application shell → Workflow pages: composes
- Workflow pages → AI workflow UI: uses
- AI workflow UI → AI client state: updates
- Workflow pages → API client: calls through
- API client → Versioned routes: HTTP requests
- Backend entry → Versioned routes: serves
- Versioned routes → Domain intelligence: invokes
- Versioned routes → AI orchestrator: submits AI requests
- Domain intelligence → Repositories: reads and writes
- Domain intelligence → Meta & WhatsApp: sends and syncs
- AI orchestrator → Analytics specialists: delegates analysis
- Analytics specialists → Analytics skills: grounds with
- AI orchestrator → Prompt templates: uses
- AI orchestrator → Model integrations: requests inference
- AI orchestrator → Repositories: queries business data
- Background jobs → Domain intelligence: runs automation
- Repositories → Domain & AI models: maps
- Domain & AI models → Database session: persists in
- Schema migrations → Database session: evolves schema