# koushik-1230/devsecops-stack architecture

> Architecture diagram of the GitHub repository koushik-1230/devsecops-stack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/koushik-1230/devsecops-stack
- Repository: https://github.com/koushik-1230/devsecops-stack

## Overview

devsecops-stack is a Kubernetes metrics collection and retrieval stack. Its agent periodically gathers node metrics from the Kubernetes metrics API and Prometheus, then posts them to a FastAPI backend. The backend authenticates the agent, records incoming metrics in an in-memory list, and serves organization-scoped metric queries to authenticated users. Login issues user tokens. Helm chart templates indicate a deployment/configuration subsystem, but their contents were not sampled, so its runtime wiring is not asserted.

Main entry points: [`backend/main.py`](https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py) (FastAPI endpoints), [`agent/agent.py`](https://github.com/koushik-1230/devsecops-stack/blob/main/agent/agent.py) (Metric assembly), [`helm/devsecops-stack`](https://github.com/koushik-1230/devsecops-stack/tree/main/helm/devsecops-stack) (Helm chart)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Metric collection"]
  node_agent_loop["Agent loop<br/>[agent.py]"]
  node_k8s_metrics["Node metrics<br/>[agent.py]"]
  node_prom_metrics["Prometheus metrics<br/>[agent.py]"]
  node_metric_assembly["Metric assembly<br/>[agent.py]"]
  node_metric_sender["Metric sender<br/>[agent.py]"]
end

subgraph group_backend["Metrics API"]
  node_backend_api["FastAPI endpoints<br/>[main.py]"]
  node_login["Login<br/>[main.py]"]
  node_token_creation["Token creation<br/>[main.py]"]
  node_agent_auth["Agent verification<br/>[main.py]"]
  node_ingestion["Metric ingestion<br/>[main.py]"]
  node_metrics_store[("Metrics list<br/>[main.py]")]
  node_user_auth["User verification<br/>[main.py]"]
  node_metrics_queries["Metrics queries<br/>[main.py]"]
end

subgraph group_deployment["Kubernetes deployment"]
  node_helm_chart["Helm chart"]
end

node_kubernetes_api{{"Kubernetes metrics API"}}
node_prometheus{{"Prometheus"}}
node_user(("User"))

node_agent_loop -->|"calls"| node_metric_sender
node_metric_sender -->|"calls"| node_metric_assembly
node_metric_assembly -->|"calls"| node_k8s_metrics
node_metric_assembly -->|"calls"| node_prom_metrics
node_k8s_metrics -->|"queries"| node_kubernetes_api
node_prom_metrics -->|"queries"| node_prometheus
node_metric_sender -->|"posts metrics"| node_backend_api
node_user -.->|"submits credentials"| node_login
node_login -->|"creates token"| node_token_creation
node_user -.->|"requests metrics"| node_metrics_queries
node_backend_api -->|"routes login"| node_login
node_backend_api -->|"routes ingest"| node_ingestion
node_backend_api -->|"routes queries"| node_metrics_queries
node_ingestion -->|"verifies agent"| node_agent_auth
node_ingestion -->|"appends records"| node_metrics_store
node_metrics_queries -->|"requires user"| node_user_auth
node_metrics_queries -->|"filters records"| node_metrics_store
node_helm_chart -.->|"may deploy"| node_agent_loop
node_helm_chart -.->|"may configure"| node_backend_api

click node_agent_loop "https://github.com/koushik-1230/devsecops-stack/blob/main/agent/agent.py"
click node_k8s_metrics "https://github.com/koushik-1230/devsecops-stack/blob/main/agent/agent.py"
click node_prom_metrics "https://github.com/koushik-1230/devsecops-stack/blob/main/agent/agent.py"
click node_metric_assembly "https://github.com/koushik-1230/devsecops-stack/blob/main/agent/agent.py"
click node_metric_sender "https://github.com/koushik-1230/devsecops-stack/blob/main/agent/agent.py"
click node_backend_api "https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py"
click node_login "https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py"
click node_token_creation "https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py"
click node_agent_auth "https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py"
click node_ingestion "https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py"
click node_metrics_store "https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py"
click node_user_auth "https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py"
click node_metrics_queries "https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py"
click node_helm_chart "https://github.com/koushik-1230/devsecops-stack/tree/main/helm/devsecops-stack"

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_agent_loop,node_k8s_metrics,node_prom_metrics,node_metric_assembly,node_metric_sender,node_user toneBlue
class node_backend_api,node_login,node_token_creation,node_agent_auth,node_ingestion,node_metrics_store,node_user_auth,node_metrics_queries toneAmber
class node_helm_chart,node_kubernetes_api toneMint
class node_prometheus toneIndigo
```

## Components

### Metric collection

- [Agent loop](https://github.com/koushik-1230/devsecops-stack/blob/main/agent/agent.py): `agent/agent.py`
- [Node metrics](https://github.com/koushik-1230/devsecops-stack/blob/main/agent/agent.py): `agent/agent.py`
- [Prometheus metrics](https://github.com/koushik-1230/devsecops-stack/blob/main/agent/agent.py): `agent/agent.py`
- [Metric assembly](https://github.com/koushik-1230/devsecops-stack/blob/main/agent/agent.py): `agent/agent.py`
- [Metric sender](https://github.com/koushik-1230/devsecops-stack/blob/main/agent/agent.py): `agent/agent.py`

### Metrics API

- [FastAPI endpoints](https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py): `backend/main.py`
- [Login](https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py): `backend/main.py`
- [Token creation](https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py): `backend/main.py`
- [Agent verification](https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py): `backend/main.py`
- [Metric ingestion](https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py): `backend/main.py`
- [Metrics list](https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py): `backend/main.py`
- [User verification](https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py): `backend/main.py`
- [Metrics queries](https://github.com/koushik-1230/devsecops-stack/blob/main/backend/main.py): `backend/main.py`

### Kubernetes deployment

- [Helm chart](https://github.com/koushik-1230/devsecops-stack/tree/main/helm/devsecops-stack): `helm/devsecops-stack`

### Other components

- **Kubernetes metrics API**
- **Prometheus**
- **User**

## Connections

- Agent loop → Metric sender: calls (evidence: `agent/agent.py`)
- Metric sender → Metric assembly: calls (evidence: `agent/agent.py`)
- Metric assembly → Node metrics: calls (evidence: `agent/agent.py`)
- Metric assembly → Prometheus metrics: calls (evidence: `agent/agent.py`)
- Node metrics → Kubernetes metrics API: queries (evidence: `agent/agent.py`)
- Prometheus metrics → Prometheus: queries (evidence: `agent/agent.py`)
- Metric sender → FastAPI endpoints: posts metrics (evidence: `agent/agent.py`)
- User → Login: submits credentials
- Login → Token creation: creates token (evidence: `backend/main.py`)
- User → Metrics queries: requests metrics
- FastAPI endpoints → Login: routes login (evidence: `backend/main.py`)
- FastAPI endpoints → Metric ingestion: routes ingest (evidence: `backend/main.py`)
- FastAPI endpoints → Metrics queries: routes queries (evidence: `backend/main.py`)
- Metric ingestion → Agent verification: verifies agent (evidence: `backend/main.py`)
- Metric ingestion → Metrics list: appends records (evidence: `backend/main.py`)
- Metrics queries → User verification: requires user (evidence: `backend/main.py`)
- Metrics queries → Metrics list: filters records (evidence: `backend/main.py`)
- Helm chart → Agent loop: may deploy
- Helm chart → FastAPI endpoints: may configure
