# kashish1530/ai-assistant architecture

> Architecture diagram of the GitHub repository kashish1530/ai-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kashish1530/ai-assistant
- Repository: https://github.com/kashish1530/ai-assistant

## Overview

This repository is a Groq-backed assistant served through chat and HTTP interfaces. A request enters either interface, reaches the capstone agent, loads and updates per-user preferences, then runs a tool-calling loop with guardrails and an approval gate for dangerous actions. Tool results inform the final response, which is checked before return. The README also documents request auditing, metrics, and a monitoring dashboard. The sampled source supports the capstone internals and Streamlit wiring; FastAPI and dashboard links follow README documentation, while detailed implementation for those unsampled modules is not established here.

Main entry points: [`day5_s1_capstone.py`](https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py) (Capstone agent), [`day5_s2_fastapi_server.py`](https://github.com/kashish1530/ai-assistant/blob/main/day5_s2_fastapi_server.py) (FastAPI endpoint), [`DAY5/day5_s2_streamlit.py`](https://github.com/kashish1530/ai-assistant/blob/main/DAY5/day5_s2_streamlit.py) (Streamlit chat), [`metrics.py`](https://github.com/kashish1530/ai-assistant/blob/main/metrics.py) (Request metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_streamlit["Streamlit chat"]
  node_fastapi["FastAPI endpoint"]
end

subgraph group_agent["Agent workflow"]
  node_agent_core["Capstone agent"]
  node_memory[("User preferences")]
  node_guardrails["Guardrail checks"]
  node_approval["Approval gate"]
  node_tool_loop["Tool loop"]
end

subgraph group_integrations["Tools and services"]
  node_groq["Groq LLM"]
  node_tools["Assistant tools"]
  node_email["SMTP email"]
  node_memory_files[("JSON memory files")]
end

subgraph group_operations["Monitoring"]
  node_audit[("Audit log<br/>[audit.jsonl]")]
  node_metrics["Request metrics<br/>[metrics.py]"]
  node_dashboard["Monitoring dashboard<br/>[dashboard.py]"]
  node_api_metrics["Metrics endpoint"]
end

node_user(("User"))

node_user -->|"sends message"| node_streamlit
node_user -->|"sends request"| node_fastapi
node_streamlit -->|"calls agent"| node_agent_core
node_fastapi -->|"calls agent"| node_agent_core
node_agent_core -->|"loads and updates"| node_memory
node_memory -->|"reads and writes"| node_memory_files
node_agent_core -->|"checks input"| node_guardrails
node_agent_core -->|"runs agent"| node_tool_loop
node_tool_loop -->|"requests completion"| node_groq
node_groq -->|"returns response"| node_tool_loop
node_tool_loop -->|"dispatches calls"| node_tools
node_tools -.->|"sends email"| node_email
node_tool_loop -->|"requests approval"| node_approval
node_approval -->|"permits action"| node_tools
node_tool_loop -->|"checks output"| node_guardrails
node_agent_core -->|"records events"| node_audit
node_agent_core -->|"records metrics"| node_metrics
node_dashboard -->|"reads metrics"| node_metrics
node_fastapi -->|"serves summary"| node_api_metrics

click node_streamlit "https://github.com/kashish1530/ai-assistant/blob/main/DAY5/day5_s2_streamlit.py"
click node_fastapi "https://github.com/kashish1530/ai-assistant/blob/main/day5_s2_fastapi_server.py"
click node_agent_core "https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py"
click node_memory "https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py"
click node_guardrails "https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py"
click node_approval "https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py"
click node_tool_loop "https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py"
click node_tools "https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py"
click node_memory_files "https://github.com/kashish1530/ai-assistant/tree/main/DAY5/memory_store"
click node_audit "https://github.com/kashish1530/ai-assistant/blob/main/logs/audit.jsonl"
click node_metrics "https://github.com/kashish1530/ai-assistant/blob/main/metrics.py"
click node_dashboard "https://github.com/kashish1530/ai-assistant/blob/main/dashboard.py"
click node_api_metrics "https://github.com/kashish1530/ai-assistant/blob/main/day5_s2_fastapi_server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_streamlit,node_fastapi,node_user toneBlue
class node_agent_core,node_memory,node_guardrails,node_approval,node_tool_loop toneAmber
class node_groq,node_tools,node_email,node_memory_files toneMint
class node_audit,node_metrics,node_dashboard,node_api_metrics toneRose
```

## Components

### User interfaces

- [Streamlit chat](https://github.com/kashish1530/ai-assistant/blob/main/DAY5/day5_s2_streamlit.py): `DAY5/day5_s2_streamlit.py`
- [FastAPI endpoint](https://github.com/kashish1530/ai-assistant/blob/main/day5_s2_fastapi_server.py): `day5_s2_fastapi_server.py`

### Agent workflow

- [Capstone agent](https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py): `day5_s1_capstone.py`
- [User preferences](https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py): `day5_s1_capstone.py`
- [Guardrail checks](https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py): `day5_s1_capstone.py`
- [Approval gate](https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py): `day5_s1_capstone.py`
- [Tool loop](https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py): `day5_s1_capstone.py`

### Tools and services

- **Groq LLM**
- [Assistant tools](https://github.com/kashish1530/ai-assistant/blob/main/day5_s1_capstone.py): `day5_s1_capstone.py`
- **SMTP email**
- [JSON memory files](https://github.com/kashish1530/ai-assistant/tree/main/DAY5/memory_store): `DAY5/memory_store`

### Monitoring

- [Audit log](https://github.com/kashish1530/ai-assistant/blob/main/logs/audit.jsonl): `logs/audit.jsonl`
- [Request metrics](https://github.com/kashish1530/ai-assistant/blob/main/metrics.py): `metrics.py`
- [Monitoring dashboard](https://github.com/kashish1530/ai-assistant/blob/main/dashboard.py): `dashboard.py`
- [Metrics endpoint](https://github.com/kashish1530/ai-assistant/blob/main/day5_s2_fastapi_server.py): `day5_s2_fastapi_server.py`

### Other components

- **User**

## Connections

- User → Streamlit chat: sends message
- User → FastAPI endpoint: sends request
- Streamlit chat → Capstone agent: calls agent
- FastAPI endpoint → Capstone agent: calls agent
- Capstone agent → User preferences: loads and updates
- User preferences → JSON memory files: reads and writes
- Capstone agent → Guardrail checks: checks input
- Capstone agent → Tool loop: runs agent
- Tool loop → Groq LLM: requests completion
- Groq LLM → Tool loop: returns response
- Tool loop → Assistant tools: dispatches calls
- Assistant tools → SMTP email: sends email
- Tool loop → Approval gate: requests approval
- Approval gate → Assistant tools: permits action
- Tool loop → Guardrail checks: checks output
- Capstone agent → Audit log: records events
- Capstone agent → Request metrics: records metrics
- Monitoring dashboard → Request metrics: reads metrics
- FastAPI endpoint → Metrics endpoint: serves summary