# cortside/guidelines-agent architecture

> Architecture diagram of the GitHub repository cortside/guidelines-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cortside/guidelines-agent
- Repository: https://github.com/cortside/guidelines-agent

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Chatbot UI (React/TS)"]:::service
    end
    Browser -->|"HTTP/WebSocket"| Ingress["K8s Ingress / Load Balancer"]:::service

    %% Backend Services
    subgraph "Backend Services"
        direction TB
        subgraph "Chatbot Service (K8s Deployment)"
            Chatbot["Chatbot UI Service"]:::service
        end
        Ingress -->|"HTTP REST"| Chatbot

        subgraph "Agent Service (K8s Deployment)"
            AgentAPI["Agent API (FastAPI)"]:::service
            DocumentLoader["Document Loader"]:::service
            Workflow["Workflow Orchestration"]:::service
            AgentAPI --> DocumentLoader
            AgentAPI --> Workflow

            subgraph "Vector Store"
                Chroma["Chroma DB (SQLite)"]:::db
            end
            DocumentLoader --> Chroma
            Workflow --> Chroma

            subgraph "Temporal Reasoner"
                Temporal["Temporalagent Library"]:::service
                TemporalDB["Temporal SQLite DB"]:::db
            end
            Workflow --> Temporal
            Temporal --> TemporalDB
        end
        Chatbot -->|"HTTP REST"| AgentAPI
    end

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI LLM"]:::external
        MCP["MCP Server"]:::external
        OIDC["OpenID Connect"]:::external
    end
    AgentAPI -->|"HTTPS API"| OpenAI
    AgentAPI -->|"HTTP RPC"| MCP
    Chatbot -->|"Auth via OIDC"| OIDC

    %% Alternate Implementation
    subgraph "Alternate Agent Implementation"
        AgentTS["AgentTS (TypeScript Agent)"]:::service
    end
    AgentTS --> Chroma
    AgentTS --> Temporal

    %% Observability
    subgraph "Observability"
        Prometheus["Prometheus"]:::external
        Otel["OpenTelemetry Collector"]:::external
    end
    AgentAPI -->|"Metrics/Traces"| Prometheus
    AgentAPI -->|"Traces"| Otel

    %% Documentation
    subgraph "Documentation & Instructions"
        Docs["docs/"]:::external
        AGInst["Agent Instructions"]:::external
        CBInst["Chatbot Instructions"]:::external
        Docs --> AGInst
        Docs --> CBInst
    end

    %% Styles
    classDef service fill:#D6EAF8,stroke:#1B4F72;
    classDef db fill:#D5F5E3,stroke:#196F3D;
    classDef external fill:#FAD7A0,stroke:#B9770E;

    %% Click Events
    click AgentAPI "https://github.com/cortside/guidelines-agent/blob/master/agent/main.py"
    click AgentAPI "https://github.com/cortside/guidelines-agent/blob/master/agent/mcp_client.py"
    click AgentAPI "https://github.com/cortside/guidelines-agent/blob/master/agent/requirements.txt"
    click AgentAPI "https://github.com/cortside/guidelines-agent/tree/master/agent/Dockerfile"
    click AgentAPI "https://github.com/cortside/guidelines-agent/blob/master/agent/k8s-deployment.yaml"
    click AgentAPI "https://github.com/cortside/guidelines-agent/blob/master/agent/k8s-service.yaml"
    click Chatbot "https://github.com/cortside/guidelines-agent/blob/master/chatbot/src/components/ChatPage.tsx"
    click Chatbot "https://github.com/cortside/guidelines-agent/blob/master/chatbot/src/components/Sidebar.tsx"
    click Chatbot "https://github.com/cortside/guidelines-agent/blob/master/chatbot/src/lib/api.ts"
    click Chatbot "https://github.com/cortside/guidelines-agent/blob/master/chatbot/src/App.tsx"
    click Chatbot "https://github.com/cortside/guidelines-agent/blob/master/chatbot/index.html"
    click Chatbot "https://github.com/cortside/guidelines-agent/blob/master/chatbot/package.json"
    click Chatbot "https://github.com/cortside/guidelines-agent/blob/master/chatbot/vite.config.mjs"
    click Chatbot "https://github.com/cortside/guidelines-agent/tree/master/chatbot/Dockerfile"
    click Chatbot "https://github.com/cortside/guidelines-agent/blob/master/chatbot/k8s-deployment.yaml"
    click Chatbot "https://github.com/cortside/guidelines-agent/blob/master/chatbot/k8s-service.yaml"
    click AgentTS "https://github.com/cortside/guidelines-agent/blob/master/agentts/main.ts"
    click AgentTS "https://github.com/cortside/guidelines-agent/blob/master/agentts/DocumentLoader.ts"
    click AgentTS "https://github.com/cortside/guidelines-agent/blob/master/agentts/Workflow.ts"
    click AgentTS "https://github.com/cortside/guidelines-agent/blob/master/agentts/PromptTemplates.ts"
    click AgentTS "https://github.com/cortside/guidelines-agent/blob/master/agentts/db/chroma.sqlite3"
    click AgentTS "https://github.com/cortside/guidelines-agent/blob/master/agentts/package.json"
    click Chroma "https://github.com/cortside/guidelines-agent/blob/master/chromadb/requirements.txt"
    click Chroma "https://github.com/cortside/guidelines-agent/blob/master/chromadb/run.ps1"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/main.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/Entity.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/GraphState.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/Predicate.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/RawEntity.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/RawExtraction.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/RawStatement.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/RawStatementList.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/RawTriplet.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/StatementType.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/TemporalEvent.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/TemporalType.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/Triplet.py"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/db/entities.db"
    click Temporal "https://github.com/cortside/guidelines-agent/blob/master/temporalagent/requirements.txt"
    click Docs "https://github.com/cortside/guidelines-agent/tree/master/docs/"
    click AGInst "https://github.com/cortside/guidelines-agent/blob/master/.github/instructions/Agent.instructions.md"
    click AGInst "https://github.com/cortside/guidelines-agent/blob/master/instructions/agent_instructions.md"
    click CBInst "https://github.com/cortside/guidelines-agent/blob/master/instructions/chatbot_instructions.md"
```
