RAG AI Portfolio Support Platform: Product And Operations Handbook

A comprehensive agentic RAG platform for portfolio intelligence, evidence-backed chat, and API-enriched responses.

This repository ships a complete application stack:

• frontend (React + Vite + MUI) for chat, strategy controls, sessions, and traceability.
• rag-app (Flask + Socket.IO + LangChain) for retrieval, orchestration, and response generation, with reranking support.
• backend (Express + MongoDB) for structured portfolio data APIs used by tool chaining.
• Deployment and operations assets for Docker, Kubernetes, progressive delivery, and Terraform.

---

Table Of Contents

1. Platform Overview
2. Core Capabilities
3. Technology Stack
4. Architecture Overview
5. Repository Layout
6. Runtime Contracts
7. End-To-End Data Lifecycle
8. Quick Start
9. Configuration And Secrets
10. API Surface
11. Operations Toolkit
12. Deployment And Infrastructure
13. Production Governance And Release Decision Model
14. Testing And Quality Gates
15. Security And Production Notes
16. Further Reading & Resources
17. Documentation Index

---

Platform Overview

The platform is designed around a single product goal: deliver high-confidence assistant responses grounded in retrieved documents and structured backend evidence.

graph LR
    U[End User] --> FE[Frontend UI - React + Socket.IO]
    FE --> RAG[RAG API - Flask + Chat Service]
    RAG --> RET[Retrieval Layer - Chroma + BM25 + Reranker]
    RAG --> ORCH[Agentic Orchestrator]
    ORCH --> BE[Backend API - Express]
    BE --> DB[(MongoDB)]
    RAG --> RESP[Source-backed Response + Trace]
    RESP --> FE

---

Core Capabilities

• Multi-strategy retrieval:
  • semantic
  • hybrid
  • multi_query
  • decomposed
• Hybrid retrieval stack:
  • Chroma vector retrieval
  • BM25 lexical retrieval
  • optional cross-encoder reranking
• Agentic backend tool chaining:
  • team profile + insights
  • investment profile + insights
  • sector profile
  • consultations
  • scrape simulation
• OpenAI-compatible endpoint:
  • POST /api/chat/completions
• Real-time frontend UX:
  • streaming chunks over Socket.IO
  • REST fallback
  • session create/load/delete
  • source cards + tool trace panel
• Production controls:
  • request IDs (X-Request-ID)
  • optional gateway auth
  • in-memory rate limiting for /api/*
  • liveness/readiness/health endpoints

---

Technology Stack

Languages And Formats

RAG, AI, And Python Runtime

Backend API Stack

Frontend Stack

Data, Infra, And Operations

Quality And Developer Tooling

graph LR
  subgraph App
    FE[React + Vite + MUI]
    RAG[Flask + LangChain + Ollama]
    BE[Express + Mongoose]
  end
  subgraph Data
    C[ChromaDB + BM25 + FAISS]
    M[MongoDB]
    R[Redis]
  end
  subgraph Platform
    D[Docker + Compose]
    K[Kubernetes + Kustomize + Argo Rollouts]
    T[Terraform AWS/OCI]
  end
  FE --> RAG
  RAG --> C
  RAG --> BE
  BE --> M
  RAG -. optional .-> R
  D --> K
  T --> K

---

Architecture Overview

High-Level Service Topology

graph TB
  subgraph Client
    Browser[Browser]
  end

  subgraph App
    FE[frontend - Vite/NGINX]
    RAG[rag-app - Flask + Socket.IO]
    BE[backend - Express]
  end

  subgraph Data
    Mongo[(MongoDB)]
    Chroma[(Chroma