How cortside/guidelines-agent works
Project type and purpose
• This is a full-stack, microservice-style Q&A system for REST API and architecture guidelines.
• Two primary services:
• agent/ – a Python 3.11 FastAPI “agent” that orchestrates document retrieval, embedding, search, LLM calls, and temporal reasoning.
• chatbot/ – a React+TypeScript front-end (Vite) that provides a streaming, threaded chat UI.
• Supporting pieces:
• agentts/ – a TypeScript variant of the agent logic showing DocumentLoader.ts, Workflow.ts, etc.
• chromadb/ – a small service or script for the Chroma vector store.
• temporalagent/ – a Python library for temporal extraction and reasoning (used by agent).
File structure
• Top-level folders:
• .github, docs/, instructions/ – CI, documentation, example prompts.
• agent/ – FastAPI service with Dockerfile, k8s manifests, main.py, mcp_client.py, requirements.txt.
• agentts/ – TS alternative, with its own package.json, main.ts, a local SQLite chroma.db, and utility modules.
• chatbot/ – React UI with Dockerfile, k8s manifests, tsconfig, Vite config, src/components, lib/api.ts.
• chromadb/ – Python requirements for vector DB service.
• temporalagent/ – Python modules for temporal reasoning, uses its own SQLite DB.
README for additional insights
• The README clearly states:
• agent handles “document loading, semantic search, workflow orchestration” via LangChain/LangGraph and OpenAI.
• chatbot is “React 19 + TypeScript chat UI” hitting the agent API.
• Observability: Prometheus metrics, OpenTelemetry tracing.
• Infrastructure: Docker Compose & Kubernetes (manifests under agent/ and chatbot/).
• Authentication: OpenID Connect.
Main components & their relationships
a. Components:
• Client Browser (React Chat UI)
• Chatbot Service (serving static assets or container)
• Kubernetes Ingress / Load Balancer
• Agent API (FastAPI container)
• Document Loader & Workflow (LangChain, LangGraph modules inside agent)
• Vector Store (Chroma DB – SQLite or separate sidecar service)
• Temporal Reasoner (temporalagent library)
• External Services:
– OpenAI LLM endpoints
– MCP Server (over HTTP, via mcp_client.py)
• Observability Backends: Prometheus, OpenTelemetry Collector
b. Interactions / Data flows:
1. User types query → React UI (via WebSocket or HTTP POST to agent endpoint).
2. UI calls Agent API (/chat) through k8s Ingress (HTTP/REST).
3. Agent API:
– Loads & splits markdown docs (from GitHub or local docs/)
– Embeds chunks → queries Chroma DB for top-k relevant chunks
– Optionally invokes temporalagent to post-process extractions
– Calls OpenAI to generate or refine an answer
– Streams response back to UI
4. Agent API exports metrics/traces to Prometheus/OTel.
5. Agent may call MCP Server for grading or rewriting operations.
c. Architectural patterns & design principles
• Microservices / separation of concerns: front-end UI vs. back-end logic
• Layered architecture: presentation (React), application (FastAPI workflows), data (vector DB, temporal DB)
• Asynchronous streaming for chat responses
• Dependency inversion: agentts shows how TS services could replace Python agent
• Infrastructure as code: Dockerfiles + Kubernetes manifests
d. Key technologies & frameworks
• Frontend: React 19, TypeScript, Vite, Tailwind CSS
• Backend: Python 3.11, FastAPI, LangChain, LangGraph
• Vector DB: Chroma (SQLite-backed or separate container)
• Temporal reasoning: custom temporalagent Python library
• External APIs: OpenAI, MCP Server, OpenID Connect (auth)
• Infra & Observability: Docker, Kubernetes, Prometheus, OpenTelemetry