Imported from yashthakur-01/FoxxNuts (
AGENTS.md). Install upstream withnpx skills add yashthakur-01/FoxxNuts. Copyright stays with the author.
AGENTS.md ā Codebase Architecture & Technical Context
This document serves as the authoritative context map for AI coding agents working in this repository.
š Repository Structure
e:\cb\
āāā client\ # Next.js 16 Frontend Application
ā āāā src\
ā ā āāā app\
ā ā ā āāā api\customer\ # Next.js Backend API Routes
ā ā ā ā āāā createWorkspace\route.ts # Creates workspace entry in Supabase
ā ā ā ā āāā deleteFile\route.ts # Removes DB row, R2 object, & triggers Celery delete task
ā ā ā ā āāā getFiles\route.ts # Lists workspace files & statuses
ā ā ā ā āāā logout\route.ts # Invalidates user auth session cache
ā ā ā ā āāā observability\
ā ā ā ā ā āāā metrics\route.ts # Calculates RPM, TPM, RPD, TPD & timeline series
ā ā ā ā ā āāā traces\route.ts # Returns paginated traces with Redis Set tracker
ā ā ā ā āāā reprocessDocument\route.ts # Triggers Celery reprocess task
ā ā ā ā āāā updateConfig\route.ts # Updates workspace LLM settings & purges workspace cache
ā ā ā ā āāā uploadFile\route.ts # Generates R2 presigned upload URL
ā ā ā āāā chat\page.tsx # RAG Chat & File Management Dashboard
ā ā ā āāā observability\page.tsx # Observability Analytics Dashboard
ā ā āāā components\
ā ā ā āāā ObservabilitySection.tsx # KPI Rate Cards, SVG Charts, & Trace Inspection Table
ā ā āāā lib\
ā ā ā āāā authCache.ts # 60s In-Memory Auth Session Cache
ā ā ā āāā redisClient.ts # Next.js ioredis Singleton Instance
ā ā āāā supabase\
ā ā āāā adminClient.ts # Supabase Service Role Admin Client
ā ā āāā schema.sql # Database SQL DDL & Row Level Security Policies
ā āāā package.json
ā
āāā rag-backend\server\ # Python FastAPI & LangGraph RAG Service
āāā app\
āāā main.py # FastAPI Application Entry & CORS Setup
āāā celery_app.py # Celery Worker Configuration & Redis Broker Init
āāā tasks.py # Celery Tasks (process_document, reprocess_document, delete_document)
āāā controllers\
ā āāā 0_pdf_parsing.py # PyMuPDF / PDF Plumber extraction logic
ā āāā 1_embedding_pipeline.py # Chunking with page headers, Cohere embeddings, Pinecone upsert
ā āāā 2_query_pipeline.py # Vector similarity search & metadata filtering
ā āāā agent_engine.py # LangGraph Workflow Definition & Node Trajectories
āāā helpers\
ā āāā cache.py # Redis Cache Helpers & Set Tracker Invalidation
āāā routes\
āāā FileProcessRoute.py # /api/process-document, /api/reprocess-document, /api/delete-document
āāā MessageRoute.py # /api/chat (Streaming SSE response & trace recording)
š Execution Trajectories & Data Flows
1. RAG Chat Query Trajectory (/api/chat)
Client Request āā> Next.js (/api/chat/sendMessage) āā> Supabase DB (Inserts Human Message)
ā
ā¼
FastAPI (/api/chat in MessageRoute.py)
ā
āāāāāāāāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāāāāāā
ā¼ ā¼
[1. Fetch Redis History] [2. Append Human Msg to Redis]
`chat_history:{session_id}` `chat_history:{session_id}`
ā
ā¼
[3. Run LangGraph Engine (agent_engine.py)]
āāā Step A: genuine_generic_router
ā āāā If casual/greeting āā> generic_response_node āā> Return LLM Answer
ā āāā If domain/policy āā> genuine_query
ā
āāā Step B: context_retriever
ā āāā Dense/Sparse Hybrid Query in Pinecone āā> Extract matching text chunks
ā
āāā Step C: chatbot_node
āāā Grounded Prompt Generation āā> LLM Completion Stream
ā
ā¼
[4. Post-Stream Operations]
āāā Append AI Message to Redis (`chat_history:{session_id}`)
āāā Insert Execution Trace to Supabase `agent_traces` table
āāā ā” Invalidate Observability Cache (`invalidate_observability_cache(workspace_id)`)
āāā Clears `observability_metrics:{workspace_id}` & Set tracker `workspace_trace_keys:{workspace_id}`
2. Document Processing & Ingestion Trajectory
1. React Frontend sends file āā> Next.js (/api/customer/uploadFile) āā> Returns Presigned R2 URL
2. XHR Uploads file (0%-100% loader) directly to Cloudflare R2 Bucket
3. Upon 100% completion āā> Next.js creates record in Supabase `files` table (status: 'uploaded')
4. Next.js calls FastAPI (/api/process-document)
5. FastAPI enqueues `process_document_task.delay(...)` to Celery Broker (< 10ms HTTP 200 response)
6. Celery Worker picks up task:
- Updates Supabase status to 'processing'
- Downloads PDF from R2
- Extracts text and formats chunks with headers: "[Page X] [File: doc.pdf] [Section: title]\n<content>"
- Generates Cohere embeddings & upserts vectors to Pinecone
- Updates Supabase status to 'completed'
š Redis Cache Key Specification
| Cache Key Pattern | TTL | Data Type | Purpose |
|---|---|---|---|
workspace_config:{workspace_id} |
300s (5m) | String (JSON) | Caches system prompt, temperature, provider, model name, and similarity threshold. |
chat_history:{session_id} |
3600s (1h) | List (JSON) | Caches last 20 alternating human/AI messages for instant history retrieval. |
observability_metrics:{workspace_id} |
600s (10m) | String (JSON) | Caches summary KPIs, RPM/TPM/RPD/TPD rate metrics, and time-series timelines. |
observability_traces:{workspace_id}:{page}:{limit} |
600s (10m) | String (JSON) | Caches paginated execution trace records. |
workspace_trace_keys:{workspace_id} |
600s (10m) | Set (Strings) | Tracker Set: Stores all active observability_traces:... key names for $O(1)$ instant invalidation. |
āļø Environment Variables Contract
# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-supabase-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
# Cloudflare R2 / AWS S3
R2_BUCKET_NAME=your-bucket-name
R2_ACCOUNT_ID=your-account-id
R2_ACCESS_KEY_ID=your-access-key
R2_SECRET_ACCESS_KEY=your-secret-key
# Vector DB & LLM Providers
PINECONE_API_KEY=your-pinecone-api-key
PINECONE_INDEX=your-index-name
COHERE_API_KEY=your-cohere-api-key
GROQ_API_KEY=your-groq-api-key
OPENAI_API_KEY=your-openai-api-key
# Cache & Backend Secrets
REDIS_URL=redis://localhost:6379/0
FASTAPI_URL=http://127.0.0.1:8000
FASTAPI_SECRET_KEY=your-secret-api-key