# luciana-okorie/kubeshield architecture

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

- Interactive diagram: https://gitdiagram.com/luciana-okorie/kubeshield
- Repository: https://github.com/luciana-okorie/kubeshield

## Overview

KubeShield is a prototype with two distinct products: a multi-tenant platform API for identity, organizations, cluster registration, and agent scan jobs; and an earlier single-operator scanner API that scans Kubernetes and stores findings. The documented agent connects the platform API to a cluster scanner, but the README explicitly says this workflow is not yet integrated with the platform’s organization-scoped registration. The graph preserves both paths and their separate persistence. Some subsystem links are based on README documentation because their implementations were not sampled; unsampled internals are not inferred.

Main entry points: [`internal/storage/storage.go`](https://github.com/luciana-okorie/kubeshield/blob/main/internal/storage/storage.go) (Platform Store), [`internal/api/routes/routes.go`](https://github.com/luciana-okorie/kubeshield/blob/main/internal/api/routes/routes.go) (Platform Routes), [`internal/httpapi/server.go`](https://github.com/luciana-okorie/kubeshield/blob/main/internal/httpapi/server.go) (Scanner API Server), [`internal/kube/scanner.go`](https://github.com/luciana-okorie/kubeshield/blob/main/internal/kube/scanner.go) (Cluster Scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform API"]
  node_platform_server["Platform Server<br/>[main.go]"]
  node_platform_routes["Platform Routes<br/>[routes.go]"]
  node_identity["Identity &amp; Sessions<br/>[auth.go]"]
  node_org_ops["Organizations &amp; Clusters<br/>[resources.go]"]
  node_agent_ops["Agent &amp; Scan Jobs<br/>[agents.go]"]
  node_platform_auth["Request Authentication<br/>[auth.go]"]
end

subgraph group_agent["Cluster Agent"]
  node_agent_process["Agent Poll &amp; Submit<br/>[main.go]"]
end

subgraph group_scanner_api["Scanner API"]
  node_scanner_server["Scanner API Server<br/>[server.go]"]
  node_scanner_entry["Scanner API Runtime<br/>[main.go]"]
end

subgraph group_scanning["Kubernetes Scanning"]
  node_cluster_scanner["Cluster Scanner<br/>[scanner.go]"]
end

subgraph group_persistence["Persistence"]
  node_platform_store["Platform Store<br/>[storage.go]"]
  node_memory_store[("Memory Backend<br/>[memory.go]")]
  node_platform_postgres[("Platform PostgreSQL<br/>[store.go]")]
  node_scanner_repository["Finding Repository<br/>[interface.go]"]
  node_scanner_postgres[("Scanner PostgreSQL<br/>[postgres.go]")]
end

node_engineer(("Platform Engineer"))
node_kubernetes[("Kubernetes Cluster")]

node_engineer -->|"uses platform"| node_platform_server
node_platform_server -->|"builds routes"| node_platform_routes
node_platform_routes -->|"routes auth"| node_identity
node_platform_routes -->|"routes org operations"| node_org_ops
node_platform_routes -->|"routes agent operations"| node_agent_ops
node_platform_routes -->|"applies authentication"| node_platform_auth
node_identity -->|"reads and writes"| node_platform_store
node_org_ops -->|"reads and writes"| node_platform_store
node_agent_ops -->|"reads and writes"| node_platform_store
node_platform_auth -->|"validates tokens"| node_platform_store
node_platform_server -->|"opens backend"| node_platform_store
node_platform_store -->|"selects fallback"| node_memory_store
node_platform_store -->|"selects PostgreSQL"| node_platform_postgres
node_engineer -->|"uses scanner API"| node_scanner_server
node_scanner_entry -->|"serves routes"| node_scanner_server
node_scanner_entry -->|"initializes scanner"| node_cluster_scanner
node_scanner_entry -->|"opens repository"| node_scanner_repository
node_scanner_server -->|"runs scans"| node_cluster_scanner
node_scanner_server -->|"reads and updates findings"| node_scanner_repository
node_scanner_repository -->|"implemented by"| node_scanner_postgres
node_cluster_scanner -->|"inspects resources"| node_kubernetes
node_agent_process -->|"runs scan"| node_cluster_scanner
node_agent_process -->|"polls and submits results"| node_platform_routes

click node_platform_server "https://github.com/luciana-okorie/kubeshield/blob/main/cmd/api/main.go"
click node_platform_routes "https://github.com/luciana-okorie/kubeshield/blob/main/internal/api/routes/routes.go"
click node_identity "https://github.com/luciana-okorie/kubeshield/blob/main/internal/api/handlers/auth.go"
click node_org_ops "https://github.com/luciana-okorie/kubeshield/blob/main/internal/api/handlers/resources.go"
click node_agent_ops "https://github.com/luciana-okorie/kubeshield/blob/main/internal/api/handlers/agents.go"
click node_platform_auth "https://github.com/luciana-okorie/kubeshield/blob/main/internal/api/middleware/auth.go"
click node_agent_process "https://github.com/luciana-okorie/kubeshield/blob/main/cmd/kubeshield-agent/main.go"
click node_scanner_server "https://github.com/luciana-okorie/kubeshield/blob/main/internal/httpapi/server.go"
click node_scanner_entry "https://github.com/luciana-okorie/kubeshield/blob/main/cmd/kubeshield-api/main.go"
click node_cluster_scanner "https://github.com/luciana-okorie/kubeshield/blob/main/internal/kube/scanner.go"
click node_platform_store "https://github.com/luciana-okorie/kubeshield/blob/main/internal/storage/storage.go"
click node_memory_store "https://github.com/luciana-okorie/kubeshield/blob/main/internal/storage/memory/memory.go"
click node_platform_postgres "https://github.com/luciana-okorie/kubeshield/blob/main/internal/storage/postgres/store.go"
click node_scanner_repository "https://github.com/luciana-okorie/kubeshield/blob/main/internal/store/interface.go"
click node_scanner_postgres "https://github.com/luciana-okorie/kubeshield/blob/main/internal/store/postgres.go"

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_platform_server,node_platform_routes,node_identity,node_org_ops,node_agent_ops,node_platform_auth toneBlue
class node_agent_process,node_kubernetes toneAmber
class node_scanner_server,node_scanner_entry toneMint
class node_cluster_scanner toneRose
class node_platform_store,node_memory_store,node_platform_postgres,node_scanner_repository,node_scanner_postgres,node_engineer toneIndigo
```

## Components

### Platform API

- [Platform Server](https://github.com/luciana-okorie/kubeshield/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Platform Routes](https://github.com/luciana-okorie/kubeshield/blob/main/internal/api/routes/routes.go): `internal/api/routes/routes.go`
- [Identity & Sessions](https://github.com/luciana-okorie/kubeshield/blob/main/internal/api/handlers/auth.go): `internal/api/handlers/auth.go`
- [Organizations & Clusters](https://github.com/luciana-okorie/kubeshield/blob/main/internal/api/handlers/resources.go): `internal/api/handlers/resources.go`
- [Agent & Scan Jobs](https://github.com/luciana-okorie/kubeshield/blob/main/internal/api/handlers/agents.go): `internal/api/handlers/agents.go`
- [Request Authentication](https://github.com/luciana-okorie/kubeshield/blob/main/internal/api/middleware/auth.go): `internal/api/middleware/auth.go`

### Cluster Agent

- [Agent Poll & Submit](https://github.com/luciana-okorie/kubeshield/blob/main/cmd/kubeshield-agent/main.go): `cmd/kubeshield-agent/main.go`

### Scanner API

- [Scanner API Server](https://github.com/luciana-okorie/kubeshield/blob/main/internal/httpapi/server.go): `internal/httpapi/server.go`
- [Scanner API Runtime](https://github.com/luciana-okorie/kubeshield/blob/main/cmd/kubeshield-api/main.go): `cmd/kubeshield-api/main.go`

### Kubernetes Scanning

- [Cluster Scanner](https://github.com/luciana-okorie/kubeshield/blob/main/internal/kube/scanner.go): `internal/kube/scanner.go`

### Persistence

- [Platform Store](https://github.com/luciana-okorie/kubeshield/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [Memory Backend](https://github.com/luciana-okorie/kubeshield/blob/main/internal/storage/memory/memory.go): `internal/storage/memory/memory.go`
- [Platform PostgreSQL](https://github.com/luciana-okorie/kubeshield/blob/main/internal/storage/postgres/store.go): `internal/storage/postgres/store.go`
- [Finding Repository](https://github.com/luciana-okorie/kubeshield/blob/main/internal/store/interface.go): `internal/store/interface.go`
- [Scanner PostgreSQL](https://github.com/luciana-okorie/kubeshield/blob/main/internal/store/postgres.go): `internal/store/postgres.go`

### Other components

- **Platform Engineer**
- **Kubernetes Cluster**

## Connections

- Platform Engineer → Platform Server: uses platform (evidence: `README.md`)
- Platform Server → Platform Routes: builds routes (evidence: `cmd/api/main.go`)
- Platform Routes → Identity & Sessions: routes auth (evidence: `internal/api/routes/routes.go`)
- Platform Routes → Organizations & Clusters: routes org operations (evidence: `internal/api/routes/routes.go`)
- Platform Routes → Agent & Scan Jobs: routes agent operations (evidence: `internal/api/routes/routes.go`)
- Platform Routes → Request Authentication: applies authentication (evidence: `internal/api/routes/routes.go`)
- Identity & Sessions → Platform Store: reads and writes (evidence: `internal/api/handlers/auth.go`)
- Organizations & Clusters → Platform Store: reads and writes (evidence: `internal/api/handlers/resources.go`)
- Agent & Scan Jobs → Platform Store: reads and writes (evidence: `internal/api/handlers/agents.go`)
- Request Authentication → Platform Store: validates tokens (evidence: `internal/api/middleware/auth.go`)
- Platform Server → Platform Store: opens backend
- Platform Store → Memory Backend: selects fallback
- Platform Store → Platform PostgreSQL: selects PostgreSQL
- Platform Engineer → Scanner API Server: uses scanner API (evidence: `README.md`)
- Scanner API Runtime → Scanner API Server: serves routes (evidence: `cmd/kubeshield-api/main.go`)
- Scanner API Runtime → Cluster Scanner: initializes scanner (evidence: `cmd/kubeshield-api/main.go`)
- Scanner API Runtime → Finding Repository: opens repository (evidence: `cmd/kubeshield-api/main.go`)
- Scanner API Server → Cluster Scanner: runs scans (evidence: `internal/httpapi/server.go`)
- Scanner API Server → Finding Repository: reads and updates findings (evidence: `internal/httpapi/server.go`)
- Finding Repository → Scanner PostgreSQL: implemented by (evidence: `internal/store/postgres.go`)
- Cluster Scanner → Kubernetes Cluster: inspects resources (evidence: `README.md`)
- Agent Poll & Submit → Cluster Scanner: runs scan (evidence: `cmd/kubeshield-agent/main.go`)
- Agent Poll & Submit → Platform Routes: polls and submits results (evidence: `README.md`)