surya2406/business_agent

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.