# carlcode-dev/verdant architecture

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

- Interactive diagram: https://gitdiagram.com/carlcode-dev/verdant
- Repository: https://github.com/carlcode-dev/verdant

## Overview

Verdant is a self-hosted Kubernetes deployment for a small Incident Logger API. Its documented path is Terraform-provisioned EC2 running k3s, which runs the containerized Flask API and exposes it through a NodePort service. API requests can check health, create incidents, or list incidents held in an in-memory collection. The README documents the infrastructure and deployment relationships; sampled app.py shows the API’s request and storage behavior. Other implementation details are not inferred from unsampled files.

Main entry points: [`service.yaml`](https://github.com/carlcode-dev/verdant/blob/main/service.yaml) (NodePort Service), [`app.py`](https://github.com/carlcode-dev/verdant/blob/main/app.py) (Flask API), [`deployment.yaml`](https://github.com/carlcode-dev/verdant/blob/main/deployment.yaml) (Kubernetes Deployment), [`main.tf`](https://github.com/carlcode-dev/verdant/blob/main/main.tf) (Terraform)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_infrastructure["Infrastructure"]
  node_terraform["Terraform<br/>[main.tf]"]
  node_aws["AWS EC2"]
end

subgraph group_cluster["Cluster Runtime"]
  node_k3s["k3s Cluster"]
  node_deployment["Kubernetes Deployment<br/>[deployment.yaml]"]
  node_pod["Verdant Pod<br/>[deployment.yaml]"]
  node_service["NodePort Service<br/>[service.yaml]"]
end

subgraph group_api["Incident API"]
  node_api["Flask API<br/>[app.py]"]
  node_health["Health Check<br/>[app.py]"]
  node_incident_routes["Incident Routes<br/>[app.py]"]
  node_incident_list["Incident Collection<br/>[app.py]"]
end

node_operator(("Operator"))
node_dockerhub["Docker Hub"]
node_client(("Internet Client"))

node_operator -->|"runs apply"| node_terraform
node_terraform -->|"provisions"| node_aws
node_aws -->|"runs"| node_k3s
node_dockerhub -->|"image pulled by"| node_k3s
node_operator -->|"applies manifest"| node_deployment
node_operator -->|"applies manifest"| node_service
node_k3s -->|"runs workload"| node_deployment
node_deployment -->|"manages"| node_pod
node_k3s -->|"runs service"| node_service
node_service -->|"exposes API"| node_client
node_service -->|"routes traffic"| node_pod
node_pod -->|"runs"| node_api
node_client -->|"requests health"| node_health
node_client -->|"requests incidents"| node_incident_routes
node_api -->|"dispatches"| node_health
node_api -->|"dispatches"| node_incident_routes
node_incident_routes -->|"writes or reads"| node_incident_list

click node_terraform "https://github.com/carlcode-dev/verdant/blob/main/main.tf"
click node_deployment "https://github.com/carlcode-dev/verdant/blob/main/deployment.yaml"
click node_pod "https://github.com/carlcode-dev/verdant/blob/main/deployment.yaml"
click node_service "https://github.com/carlcode-dev/verdant/blob/main/service.yaml"
click node_api "https://github.com/carlcode-dev/verdant/blob/main/app.py"
click node_health "https://github.com/carlcode-dev/verdant/blob/main/app.py"
click node_incident_routes "https://github.com/carlcode-dev/verdant/blob/main/app.py"
click node_incident_list "https://github.com/carlcode-dev/verdant/blob/main/app.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_terraform,node_aws,node_client toneBlue
class node_k3s,node_deployment,node_pod,node_service toneAmber
class node_api,node_health,node_incident_routes,node_incident_list toneMint
class node_operator,node_dockerhub toneIndigo
```

## Components

### Infrastructure

- [Terraform](https://github.com/carlcode-dev/verdant/blob/main/main.tf): `main.tf`
- **AWS EC2**

### Cluster Runtime

- **k3s Cluster**
- [Kubernetes Deployment](https://github.com/carlcode-dev/verdant/blob/main/deployment.yaml): `deployment.yaml`
- [Verdant Pod](https://github.com/carlcode-dev/verdant/blob/main/deployment.yaml): `deployment.yaml`
- [NodePort Service](https://github.com/carlcode-dev/verdant/blob/main/service.yaml): `service.yaml`

### Incident API

- [Flask API](https://github.com/carlcode-dev/verdant/blob/main/app.py): `app.py`
- [Health Check](https://github.com/carlcode-dev/verdant/blob/main/app.py): `app.py`
- [Incident Routes](https://github.com/carlcode-dev/verdant/blob/main/app.py): `app.py`
- [Incident Collection](https://github.com/carlcode-dev/verdant/blob/main/app.py): `app.py`

### Other components

- **Operator**
- **Docker Hub**
- **Internet Client**

## Connections

- Operator → Terraform: runs apply (evidence: `README.md`)
- Terraform → AWS EC2: provisions (evidence: `README.md`)
- AWS EC2 → k3s Cluster: runs (evidence: `README.md`)
- Docker Hub → k3s Cluster: image pulled by (evidence: `README.md`)
- Operator → Kubernetes Deployment: applies manifest (evidence: `README.md`)
- Operator → NodePort Service: applies manifest (evidence: `README.md`)
- k3s Cluster → Kubernetes Deployment: runs workload (evidence: `README.md`)
- Kubernetes Deployment → Verdant Pod: manages (evidence: `README.md`)
- k3s Cluster → NodePort Service: runs service (evidence: `README.md`)
- NodePort Service → Internet Client: exposes API (evidence: `README.md`)
- NodePort Service → Verdant Pod: routes traffic (evidence: `README.md`)
- Verdant Pod → Flask API: runs (evidence: `README.md`)
- Internet Client → Health Check: requests health (evidence: `README.md`)
- Internet Client → Incident Routes: requests incidents (evidence: `app.py`)
- Flask API → Health Check: dispatches (evidence: `app.py`)
- Flask API → Incident Routes: dispatches (evidence: `app.py`)
- Incident Routes → Incident Collection: writes or reads (evidence: `app.py`)