anjalilongre9625/capstone-project

Purpose and Runtime

Conversational Context AI is a customer-support resolution engine: persistent customer context, policy-grounded answers, specialist-agent routing, mock order/support actions, and human escalation. It runs as a FastAPI backend plus React/TypeScript SPA, containerized through docker-compose.yml, with backend startup in backend/main.py and frontend bootstrap in frontend/src/main.tsx.

API and Client Boundary

The backend exposes health, authentication, chat, and knowledge-management HTTP surfaces under backend/api/health.py, backend/api/auth.py, backend/api/chat.py, and backend/api/knowledge.py. Dependency wiring belongs in backend/api/deps.py. The SPA’s protected application shell and API clients are centered on frontend/src/App.tsx, frontend/src/context/AuthContext.tsx, and frontend/src/api/client.ts; chat is presented by frontend/src/pages/Chat.tsx.

Authentication and Persistent Domain Data

Authentication is implemented across backend/services/auth_service.py, backend/api/auth.py, and request models in backend/models/auth.py. Relational persistence—including customers, orders, conversations, and related entities—is defined by backend/database/models.py and accessed through backend/database/session.py. Seed data supports local demonstration via backend/database/seed.py.

Conversation Orchestration Graph

The primary control path is a graph-driven conversation run: incoming chat state is represented in backend/graph/state.py, assembled in backend/graph/build.py, and executed by backend/graph/runner.py. Routing decisions are isolated in backend/graph/routing.py; graph event emission is handled by backend/graph/events.py. This is the central boundary between API request handling and autonomous multi-step resolution.

Agents, Tools, and Escalation

A supervisor delegates work to billing, shipping, returns, complaint, and escalation specialists in backend/agents/supervisor.py, backend/agents/billing.py, and backend/agents/shipping.py (with remaining specialist implementations alongside them). Graph specialist/tool stages reside in backend/graph/specialists.py and backend/graph/tool_node.py. Actions are mediated through registered mock business tools—order and support operations—in backend/tools/registry.py, backend/tools/order_tools.py, and backend/tools/support_tools.py, keeping agents separate from operational integrations.

Escalation is a dedicated decision and control path: policy in backend/guardrails/escalation_policy.py, graph transition/node handling in backend/graph/escalate_node.py, and escalation data contracts in backend/models/escalation.py.

Memory and Retrieval-Augmented Knowledge

Session context, durable customer memory, and summarization are separated in backend/memory/session_store.py, backend/memory/long_term_store.py, and backend/memory/manager.py. Policy retrieval flows from document ingestion/chunking through embeddings and vector lookup in backend/rag/ingestion.py, backend/rag/embeddings.py, and backend/rag/retriever.py. The knowledge corpus is local Markdown policy material under backend/rag/knowledge_base/; vector-store integration is encapsulated by backend/rag/chroma_client.py.

Model and Infrastructure Dependencies

LLM access is abstracted behind backend/utils/llm_client.py; the README identifies OpenRouter credentials as the external model dependency. The expected runtime stack is Python/FastAPI, a database selected by DATABASE_URL, Chroma-backed retrieval, and Node/Vite React frontend containers defined by backend/Dockerfile, frontend/Dockerfile, and docker-compose.yml. Analytics has a reserved backend package at backend/analytics/__init__.py and corresponding SPA page at frontend/src/pages/Analytics.tsx.