# raflfaisal/agentsmithy architecture

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

- Interactive diagram: https://gitdiagram.com/raflfaisal/agentsmithy
- Repository: https://github.com/raflfaisal/agentsmithy

## Overview

##### Project Type & Purpose
- AgentSmithy is a full-stack AI agent starter kit for Google Cloud. It provides:
- A frontend Chatbot UI (Angular) for end-user interaction
- A backend Python API (FastAPI/Cloud Run) that hosts agent orchestration, RAG, and custom tools
- Infrastructure-as-code (Terraform) and CI/CD pipelines to deploy to Cloud Run and Vertex AI services

##### File Structure Analysis
- Top level
- .github/workflows: CI definitions
- build.py, download_wheels.py, license_check.sh: build & release scripts
- Runtime_env/: Python backend + deployment infra
- ChatbotUI/: Angular frontend
- ChatbotUI/
- src/app/components, services, models, environments → MVC-style Angular app
- Dockerfile, nginx.conf, deployment/cd/dev.yaml → containerized, statically served + CI/CD
- Runtime_env/
- app/orchestration: agent control loops (LangChain/LangGraph/LlamaIndex)
- app/rag: retrieval templates backed by Vertex AI Search
- app/server.py: FastAPI server entrypoint
- deployment/terraform: GCP infra modules (Cloud Run, Artifact Registry, IAM, etc.)
- deployment/cd/dev.yaml: Cloud Build / GitHub Actions triggers

##### README Insights
- Three main components:
A. Agent Orchestration (selectable frameworks + models + tools)
B. Backend API Server (FastAPI on Cloud Run)
C. Frontend App Server (Angular on Cloud Run or static hosting)

a. Main Components & Packaging
1. User’s Browser / Client
2. ChatbotUI Service
- Angular SPA served via Nginx in a container on Cloud Run
- Components: chat UI, suggestion cards, speech-to-text, toast messages
3. Backend API Service
- FastAPI app on Cloud Run (Runtime_env/app/server.py)
- Endpoints for conversational requests, health checks, metrics
4. Agent Orchestration Layer
- Python modules orchestrating LLM calls, state management
- Configurable frameworks: LangChain, LangGraph, LlamaIndex
5. Tools & RAG
- RAG retriever using Vertex AI Search
- OOTB LangChain tools (YahooFinance, PubMed, etc.)
6. Foundation Models
- Google Gemini, Claude, Llama models via Vertex AI APIs or Agent Engine
7. Infrastructure & CI/CD
- Terraform modules: Cloud Run, Artifact Registry, IAM
- GitHub Actions / Cloud Build pipelines for build, test, deploy
8. External Services
- Vertex AI Search / Agent Engine
- Google Cloud IAM, Cloud Logging, Monitoring

b. Relationships & Data Flows

c. Architectural Patterns & Principles
- Microservices: frontend and backend as separate Cloud Run services
- Layered architecture: UI → API → Orchestration → External tools/models
- Infrastructure-as-code and GitOps for repeatable deployments
- Pluggable strategy pattern for orchestration frameworks and foundation models
- Twelve-factor app compliance: config via environment variables, stateless containers

d. Key Technologies & Libraries
- Angular, Nginx
- FastAPI, Uvicorn
- LangChain / LangGraph / LlamaIndex
- Vertex AI Search (RAG), Vertex AI Agent Engine
- Terraform, Cloud Build, GitHub Actions
- Docker, Python 3.10+, Poetry

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User"
        Browser["User Browser"]:::user
    end

    subgraph "Frontend: ChatbotUI Service"
        UI["Angular SPA"]:::frontend
        Nginx["Nginx"]:::frontend
        UI -->|"served via Nginx"| Nginx
    end

    subgraph "Backend: API Service"
        API["FastAPI Server"]:::internal
    end

    subgraph "Orchestration Layer"
        Orch["Agent Orchestration"]:::internal
    end

    subgraph "RAG & Tools"
        RAG["RAG Retriever"]:::internal
        Tools["LLM Tools"]:::external
    end

    subgraph "Utility Functions"
        Utils["Utility Functions"]:::internal
    end

    subgraph "Foundation Models"
        Models["Foundation Models"]:::external
    end

    subgraph "Infrastructure & CI/CD"
        GitHub["GitHub Actions"]:::infra
        CloudBuild["Cloud Build"]:::infra
        Terraform["Terraform Modules"]:::infra
    end

    subgraph "Build & Release"
        BuildScripts["Build & Release Scripts"]:::infra
        DockerUI["UI Docker Image"]:::infra
        DockerAPI["API Docker Image"]:::infra
        ArtReg["Artifact Registry"]:::infra
    end

    subgraph "External Services"
        VertexSearch["Vertex AI Search"]:::external
        AgentEngine["Vertex AI Agent Engine"]:::external
        PubMed["PubMed API"]:::external
    end

    Browser -->|"HTTPS POST"| UI
    UI -->|"HTTPS REST"| API
    API -->|"invoke"| Orch
    Orch -->|"RAG call"| RAG
    Orch -->|"Tool calls"| Tools
    Orch -->|"invoke model"| Models
    RAG -->|"search"| VertexSearch
    Tools -->|"API calls"| PubMed
    Models -->|"response"| API
    RAG -->|"response"| API
    Tools -->|"response"| API
    API -->|"JSON"| UI
    UI -->|"render"| Browser

    GitHub -->|"trigger"| CloudBuild
    CloudBuild -->|"run"| BuildScripts
    BuildScripts -->|"build"| DockerUI
    BuildScripts -->|"build"| DockerAPI
    DockerUI -->|"push"| ArtReg
    DockerAPI -->|"push"| ArtReg
    ArtReg -->|"deploy UI"| UI
    ArtReg -->|"deploy API"| API
    Terraform -->|"provision"| UI
    Terraform -->|"provision"| API
    Terraform -->|"provision infra"| Infrastructure & CI/CD

    classDef user fill:#a2f5a2,stroke:#333
    classDef frontend fill:#a2f5a2,stroke:#333
    classDef internal fill:#a2c8f5,stroke:#333
    classDef external fill:#f5c77a,stroke:#333
    classDef infra fill:#d3d3d3,stroke:#333

    click UI "https://github.com/raflfaisal/agentsmithy/tree/main/ChatbotUI/"
    click UI "https://github.com/raflfaisal/agentsmithy/tree/main/ChatbotUI/src/app/components"
    click UI "https://github.com/raflfaisal/agentsmithy/tree/main/ChatbotUI/src/app/services"
    click UI "https://github.com/raflfaisal/agentsmithy/tree/main/ChatbotUI/Dockerfile"
    click UI "https://github.com/raflfaisal/agentsmithy/blob/main/ChatbotUI/nginx.conf"
    click UI "https://github.com/raflfaisal/agentsmithy/blob/main/ChatbotUI/deployment/cd/dev.yaml"

    click API "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/server.py"
    click API "https://github.com/raflfaisal/agentsmithy/tree/main/Runtime_env/Dockerfile"
    click API "https://github.com/raflfaisal/agentsmithy/tree/main/Runtime_env/Makefile"
    click API "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/pyproject.toml"

    click Orch "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/orchestration/agent.py"
    click Orch "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/orchestration/config.py"
    click Orch "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/orchestration/constants.py"
    click Orch "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/orchestration/enums.py"
    click Orch "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/orchestration/server_utils.py"
    click Orch "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/orchestration/tools.py"

    click RAG "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/rag/retriever.py"
    click RAG "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/rag/templates.py"

    click Utils "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/utils/decorators.py"
    click Utils "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/utils/input_types.py"
    click Utils "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/utils/output_types.py"
    click Utils "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/utils/tracing.py"
    click Utils "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/app/utils/utils.py"

    click Terraform "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/deployment/terraform/apis.tf"
    click Terraform "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/deployment/terraform/artifact_registry.tf"
    click Terraform "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/deployment/terraform/cloud_run.tf"
    click Terraform "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/deployment/terraform/iam.tf"
    click Terraform "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/deployment/terraform/storage.tf"
    click Terraform "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/deployment/terraform/service_accounts.tf"
    click Terraform "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/deployment/terraform/variables.tf"
    click Terraform "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/deployment/terraform/locals.tf"
    click Terraform "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/deployment/terraform/counter.tf"
    click Terraform "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/deployment/terraform/vars/env.tfvars"

    click GitHub "https://github.com/raflfaisal/agentsmithy/blob/main/.github/workflows/.github-ci.yml"
    click CloudBuild "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/deployment/cd/dev.yaml"
    click GitHub "https://github.com/raflfaisal/agentsmithy/blob/main/ChatbotUI/deployment/cd/dev.yaml"

    click BuildScripts "https://github.com/raflfaisal/agentsmithy/blob/main/build.py"
    click BuildScripts "https://github.com/raflfaisal/agentsmithy/blob/main/license_check.sh"
    click BuildScripts "https://github.com/raflfaisal/agentsmithy/blob/main/Runtime_env/download_wheels.py"
```
