vijayb-exl/complai

Purpose and Entry Points

complAI is a compliance-analysis application: it ingests policy documents, retrieves relevant clauses, queries business metrics through natural-language-to-SQL, evaluates compliance, and produces remediation workflows. The backend service starts at backend/app/main.py; API boundaries are backend/app/api/routes_run.py for analysis/simulation runs and backend/app/api/routes_rag.py for document/RAG operations. The Next.js client begins at frontend/app/page.tsx and provides a dedicated RAG workspace at frontend/app/rag/page.tsx.

API and Execution Boundary

Request/response contracts are centralized in backend/app/api/schemas.py. Run APIs hand work to backend/app/run_manager.py, separating HTTP lifecycle/status handling from agent execution. RAG routes delegate to the RAG subsystem rather than exposing vector-store details directly. Browser-to-backend calls are encapsulated in frontend/lib/api.ts and frontend/lib/rag-api.ts.

LangGraph Compliance Pipeline

backend/app/graph/builder.py compiles the multi-agent workflow, with shared execution state in backend/app/graph/state.py. The supervisor in backend/app/graph/nodes/supervisor.py routes work across stages:

• policy retrieval: backend/app/graph/nodes/retrieve_policies.py

• structured-data querying: backend/app/graph/nodes/text_to_sql.py

• policy-versus-metric evaluation: backend/app/graph/nodes/compliance_reasoning.py

• remediation-plan production: backend/app/graph/nodes/remediation_workflow.py

This graph is the principal control-flow boundary: nodes exchange typed state such as retrieved policies, SQL, results, analysis, and workflow rather than calling UI code.

Document Ingestion and RAG

Document ingestion is represented as both a graph stage, backend/app/graph/nodes/ingest_document.py, and a reusable service pipeline in backend/app/rag/ingestion_service.py. It loads documents, chunks content, extracts entities, and persists embeddings through backend/app/rag/loaders.py, backend/app/rag/chunking.py, and backend/app/rag/vector_store.py. At query time, backend/app/rag/retrieval_service.py retrieves candidate policy content; backend/app/rag/reranker.py and backend/app/rag/prompt_builder.py refine context for RAG responses. ChromaDB is the vector-store infrastructure boundary.

LLM and Structured Data Integrations

LLM access is abstracted by backend/app/connectors/llm.py, with OpenRouter-specific implementation in backend/app/connectors/openrouter_llm.py. SQL generation/execution is isolated in backend/app/connectors/sql_connector.py, supporting the Databricks/SQL Server structured-data boundary. The text-to-SQL node should remain the only graph stage that turns user language into database access, preserving read-only and dialect-validation controls.

Simulation and Client Visualization

The backend supports dependency-free dummy/live behavior through backend/app/simulation/engine.py and backend/app/simulation/fixtures.py; this enables streamed synthetic progress without external database access. On the client, frontend/components/SimulationStreamer.tsx presents run updates, while frontend/components/LinearWorkflowMap.tsx renders the sequential remediation workflow and compliance status lights. RAG interaction, uploads, citations, and agent progress are composed under frontend/components/rag/RagChat.tsx and frontend/components/rag/DocumentUploadPanel.tsx.

Runtime Shape

Backend runtime is Python with LangGraph/LangChain, ChromaDB, LLM-provider connectivity, and optional Databricks or SQL Server credentials configured via backend/app/config.py. Frontend runtime is Next.js/React App Router. The frontend is a consumer of backend API and streaming status contracts; it does not own compliance reasoning, embedding, SQL access, or workflow generation.