# yethikrishna/yetr-ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/yethikrishna/yetr-ai-agent
- Repository: https://github.com/yethikrishna/yetr-ai-agent

## Overview

##### Project Type & Purpose
- YETR AI Agent is a full-stack, front-heavy web application providing an interactive AI chat interface.
- Frontend: React + Next.js + TypeScript + Tailwind CSS (deployed via GitHub Pages, Vercel, Netlify).
- Backend (YETR Core): FastAPI + Python, powered by PostgreSQL and Redis (not present in the repo tree but described in README).
- External Integrations: Multiple MCP (Model Context Protocol) servers, third-party APIs (GitHub, GitLab, OpenAI, etc.).

##### File Structure Highlights
- Top-level configs: netlify.toml, vercel.json, docker-compose.yml, DEPLOYMENT.md.
- frontend/: Next.js app code (pages, components/ui, hooks, public/data JSON files).
- src/: A duplicate or static build–oriented copy of the frontend for GitHub Pages (serves index.html + src/pages).
- README & docs/ folder references (architecture.md, deployment.md, etc.) define infrastructure and usage.

##### Key Components
A. Frontend Layer
- Next.js Server & Static Hosting (Vercel/Netlify/GitHub Pages)
- React components, client-side routing, Tailwind CSS styles
- Public/assets & JSON data for MCP tutorials and specs
B. API Layer (YETR Core)
- FastAPI HTTP endpoints (chat, authentication, MCP routing)
- WebSockets or Server-Sent Events for real-time streaming
- JWT-based auth, RBAC
C. Data Layer
- PostgreSQL for persistent storage (conversations, user profiles)
- Redis for caching & pub/sub (context memory, rate-limiting)
D. External Services
- MCP Servers (GitHub, databases, file systems, email/calendar, Slack, OpenAI)
- Third-party AI services (OpenAI, Anthropic, local models)
- CI/CD pipelines (GitHub Actions, Docker Hub, Kubernetes clusters)

##### Component Relationships & Data Flow
- Client → Next.js: initial page load, static assets
- Next.js ↔ FastAPI: REST/GraphQL calls for chat, history, MCP orchestration
- FastAPI ↔ PostgreSQL: CRUD for user data & workflows
- FastAPI ↔ Redis: cache lookups, session storage, pub/sub for streaming responses
- FastAPI ↔ MCP Servers: bidirectional API calls, parallel tool execution, error handling
- CI/CD → Docker & K8s: automated builds, container deployment

##### Architectural Patterns & Principles
- Separation of Concerns: UI vs. API vs. Data
- Micro-orchestration: FastAPI acts as orchestrator for multiple MCP adapters
- Caching & Pub/Sub: Redis for performance & real-time streaming
- Stateless Frontend, Stateful Core: scale frontends horizontally on static hosts, scale API via containers
- Configuration-driven Integrations: JSON/YAML config for dynamic MCP server definitions

## Diagram (Mermaid)

```mermaid
graph TB

  %% Presentation Layer
  subgraph "Presentation Layer"
    P1["Next.js Server & Static Hosting"]:::compute
    P2["React UI Components"]:::compute
    P3["Client-Side Hooks & State"]:::compute
    P4["Next.js Pages & Routing"]:::compute
    P5["Tailwind CSS Configuration"]:::compute
    P6["Static JSON Data for MCP Tutorials & Specs"]:::compute
    P7["Static Build for GitHub Pages"]:::compute
    P8["Netlify Deployment Config"]:::infra
    P9["Vercel Deployment Config"]:::infra
    P10["GitHub Actions CI for GitHub Pages"]:::infra
  end

  %% API Layer
  subgraph "API Layer"
    A1["FastAPI (YETR Core)"]:::compute
  end

  %% Data Layer
  subgraph "Data Layer"
    D1["PostgreSQL"]:::db
    D2["Redis (Cache & Pub/Sub)"]:::db
  end

  %% External Services Layer
  subgraph "External Services"
    E1["MCP Servers"]:::external
    E2["Third-Party AI Services"]:::external
  end

  %% CI/CD & Infrastructure
  subgraph "CI/CD & Infra"
    I1["Docker Compose Setup"]:::infra
    I2["Kubernetes Cluster"]:::infra
    I3["Docs & Deployment Guides"]:::infra
  end

  %% Connections
  P1 -->|"HTTPS"| A1
  P6 -->|"Static Assets"| P1
  A1 -->|"SQL / ORM"| D1
  A1 -->|"Cache / Pub-Sub"| D2
  A1 -->|"MCP Protocol"| E1
  A1 -->|"API Calls"| E2
  A1 -.->|"WSS / SSE"| P1

  I1 -->|"Deploy Containers"| A1
  I1 -->|"Includes DB & Redis"| D1
  I1 -->|"Includes DB & Redis"| D2
  P10 -->|"Deploy Static Build"| P7
  I3 -.->|"Guides"| I1

  %% Click Events
  click P1 "https://github.com/yethikrishna/yetr-ai-agent/tree/main/frontend/"
  click P2 "https://github.com/yethikrishna/yetr-ai-agent/tree/main/frontend/src/components/ui/"
  click P3 "https://github.com/yethikrishna/yetr-ai-agent/tree/main/frontend/src/hooks/"
  click P4 "https://github.com/yethikrishna/yetr-ai-agent/tree/main/frontend/src/pages/"
  click P5 "https://github.com/yethikrishna/yetr-ai-agent/blob/main/frontend/tailwind.config.js"
  click P6 "https://github.com/yethikrishna/yetr-ai-agent/tree/main/frontend/public/data/"
  click P7 "https://github.com/yethikrishna/yetr-ai-agent/tree/main/src/"
  click P10 "https://github.com/yethikrishna/yetr-ai-agent/blob/main/.github/workflows/pages.yml"
  click P8 "https://github.com/yethikrishna/yetr-ai-agent/blob/main/netlify.toml"
  click P9 "https://github.com/yethikrishna/yetr-ai-agent/blob/main/vercel.json"
  click I1 "https://github.com/yethikrishna/yetr-ai-agent/blob/main/docker-compose.yml"
  click I3 "https://github.com/yethikrishna/yetr-ai-agent/blob/main/DEPLOYMENT.md"
  click I3 "https://github.com/yethikrishna/yetr-ai-agent/tree/main/docs/"

  %% Styles
  classDef compute fill:#cfe2f3,stroke:#000,stroke-width:1px;
  classDef db fill:#d9ead3,stroke:#000,stroke-width:1px;
  classDef external fill:#f9cb9c,stroke:#000,stroke-width:1px;
  classDef infra fill:#d9d2e9,stroke:#000,stroke-width:1px;
```
