# jay240322/kubesense architecture

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

- Interactive diagram: https://gitdiagram.com/jay240322/kubesense
- Repository: https://github.com/jay240322/kubesense

## Overview

KubeSense is a web-based Kubernetes troubleshooting assistant. Users sign in, configure a Gemini key, inspect pod details, logs, and events, and request pod-level or cluster-wide AI analysis. The dashboard-facing hooks call the frontend API service; backend routes dispatch to Kubernetes access or analysis, and AI generation uses Gemini. Authentication and database access form supporting internal layers. README documents these major capabilities; some implementation files were not sampled, so uncertain connections are omitted.

Main entry points: [`frontend/services/api.ts`](https://github.com/jay240322/kubesense/blob/main/frontend/services/api.ts) (API service), [`backend/app/main.py`](https://github.com/jay240322/kubesense/blob/main/backend/app/main.py) (FastAPI routes), [`frontend/app/dashboard/page.tsx`](https://github.com/jay240322/kubesense/blob/main/frontend/app/dashboard/page.tsx) (Dashboard), [`backend/app/ai/service.py`](https://github.com/jay240322/kubesense/blob/main/backend/app/ai/service.py) (AI response service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web dashboard"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_podview["Pod explorer<br/>[podTable.tsx]"]
  node_podinfo["Pod details<br/>[PodDetails.tsx]"]
  node_logs["Pod logs<br/>[PodLogs.tsx]"]
  node_events["Pod events<br/>[PodEvents.tsx]"]
  node_clusterui["Cluster analysis UI"]
  node_authui["Login form<br/>[LoginForm.tsx]"]
  node_authstate["Auth context<br/>[AuthContext.tsx]"]
  node_keyui["Gemini settings UI<br/>[GeminiApiModal.tsx]"]
  node_hooks["Analysis hooks<br/>[useAI.ts]"]
  node_clusterhook["Cluster hook<br/>[useClusterAI.ts]"]
  node_keyhook["Settings hook"]
  node_http["API service<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_app["FastAPI routes<br/>[main.py]"]
end

subgraph group_diagnostics["Cluster diagnostics"]
  node_podaccess["Pod operations<br/>[pods.py]"]
  node_k8sclient["Kubernetes client<br/>[client.py]"]
end

subgraph group_identity["Identity and settings"]
  node_settingsrouter["Settings routes<br/>[router.py]"]
  node_settingsservice["Key lookup<br/>[service.py]"]
  node_authrouter["Auth routes<br/>[router.py]"]
  node_authservice["Login service<br/>[service.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
end

subgraph group_analysis["AI analysis"]
  node_podanalyzer["Pod analyzer<br/>[analyzer.py]"]
  node_clusteranalyzer["Cluster analyzer"]
  node_airesponse["AI response service<br/>[service.py]"]
end

node_operator(("Engineer"))
node_kubernetes{{"Kubernetes cluster"}}
node_gemini{{"Google Gemini"}}

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"shows"| node_podview
node_dashboard -->|"shows"| node_clusterui
node_dashboard -->|"offers login"| node_authui
node_authui -->|"stores token"| node_authstate
node_podview -->|"requests pod data"| node_http
node_podinfo -->|"requests details"| node_http
node_logs -->|"requests logs"| node_http
node_events -->|"requests events"| node_http
node_hooks -->|"requests analysis"| node_http
node_clusterhook -->|"requests analysis"| node_http
node_keyui -->|"configures key"| node_keyhook
node_keyhook -->|"requests settings"| node_http
node_http -->|"calls API"| node_app
node_app -->|"dispatches pod requests"| node_podaccess
node_podaccess -->|"creates client"| node_k8sclient
node_k8sclient -->|"queries cluster"| node_kubernetes
node_app -->|"dispatches pod analysis"| node_podanalyzer
node_app -->|"dispatches cluster analysis"| node_clusteranalyzer
node_podanalyzer -->|"generates analysis"| node_airesponse
node_clusteranalyzer -->|"generates analysis"| node_airesponse
node_airesponse -->|"loads fallback key"| node_settingsservice
node_airesponse -->|"sends prompt"| node_gemini
node_app -->|"includes routes"| node_authrouter
node_authrouter -->|"calls login"| node_authservice
node_authservice -->|"queries users"| node_database
node_app -->|"includes routes"| node_settingsrouter
node_settingsrouter -->|"validates key"| node_gemini
node_settingsservice -->|"reads settings"| node_database

click node_dashboard "https://github.com/jay240322/kubesense/blob/main/frontend/app/dashboard/page.tsx"
click node_podview "https://github.com/jay240322/kubesense/blob/main/frontend/components/podTable/podTable.tsx"
click node_podinfo "https://github.com/jay240322/kubesense/blob/main/frontend/components/PodDetails/PodDetails.tsx"
click node_logs "https://github.com/jay240322/kubesense/blob/main/frontend/components/PodLogs/PodLogs.tsx"
click node_events "https://github.com/jay240322/kubesense/blob/main/frontend/components/PodEvents/PodEvents.tsx"
click node_clusterui "https://github.com/jay240322/kubesense/blob/main/frontend/components/ClusterAnalysis/ClusterAnalysis.tsx"
click node_authui "https://github.com/jay240322/kubesense/blob/main/frontend/components/auth/LoginForm.tsx"
click node_authstate "https://github.com/jay240322/kubesense/blob/main/frontend/context/AuthContext.tsx"
click node_keyui "https://github.com/jay240322/kubesense/blob/main/frontend/components/GeminiApiModal/GeminiApiModal.tsx"
click node_hooks "https://github.com/jay240322/kubesense/blob/main/frontend/hooks/useAI.ts"
click node_clusterhook "https://github.com/jay240322/kubesense/blob/main/frontend/hooks/useClusterAI.ts"
click node_keyhook "https://github.com/jay240322/kubesense/blob/main/frontend/hooks/useGeminiSettings.ts"
click node_http "https://github.com/jay240322/kubesense/blob/main/frontend/services/api.ts"
click node_app "https://github.com/jay240322/kubesense/blob/main/backend/app/main.py"
click node_podaccess "https://github.com/jay240322/kubesense/blob/main/backend/app/kubernetes/pods.py"
click node_k8sclient "https://github.com/jay240322/kubesense/blob/main/backend/app/kubernetes/client.py"
click node_podanalyzer "https://github.com/jay240322/kubesense/blob/main/backend/app/ai/analyzer.py"
click node_clusteranalyzer "https://github.com/jay240322/kubesense/blob/main/backend/app/ai/cluster_analyzer.py"
click node_airesponse "https://github.com/jay240322/kubesense/blob/main/backend/app/ai/service.py"
click node_settingsrouter "https://github.com/jay240322/kubesense/blob/main/backend/app/settings/router.py"
click node_settingsservice "https://github.com/jay240322/kubesense/blob/main/backend/app/settings/service.py"
click node_authrouter "https://github.com/jay240322/kubesense/blob/main/backend/app/auth/router.py"
click node_authservice "https://github.com/jay240322/kubesense/blob/main/backend/app/auth/service.py"
click node_database "https://github.com/jay240322/kubesense/blob/main/backend/app/database.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_dashboard,node_podview,node_podinfo,node_logs,node_events,node_clusterui,node_authui,node_authstate,node_keyui,node_hooks,node_clusterhook,node_keyhook,node_http toneBlue
class node_app toneAmber
class node_podaccess,node_k8sclient toneMint
class node_settingsrouter,node_settingsservice,node_authrouter,node_authservice,node_database toneRose
class node_podanalyzer,node_clusteranalyzer,node_airesponse,node_operator,node_kubernetes,node_gemini toneIndigo
```

## Components

### Web dashboard

- [Dashboard](https://github.com/jay240322/kubesense/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Pod explorer](https://github.com/jay240322/kubesense/blob/main/frontend/components/podTable/podTable.tsx): `frontend/components/podTable/podTable.tsx`
- [Pod details](https://github.com/jay240322/kubesense/blob/main/frontend/components/PodDetails/PodDetails.tsx): `frontend/components/PodDetails/PodDetails.tsx`
- [Pod logs](https://github.com/jay240322/kubesense/blob/main/frontend/components/PodLogs/PodLogs.tsx): `frontend/components/PodLogs/PodLogs.tsx`
- [Pod events](https://github.com/jay240322/kubesense/blob/main/frontend/components/PodEvents/PodEvents.tsx): `frontend/components/PodEvents/PodEvents.tsx`
- [Cluster analysis UI](https://github.com/jay240322/kubesense/blob/main/frontend/components/ClusterAnalysis/ClusterAnalysis.tsx): `frontend/components/ClusterAnalysis/ClusterAnalysis.tsx`
- [Login form](https://github.com/jay240322/kubesense/blob/main/frontend/components/auth/LoginForm.tsx): `frontend/components/auth/LoginForm.tsx`
- [Auth context](https://github.com/jay240322/kubesense/blob/main/frontend/context/AuthContext.tsx): `frontend/context/AuthContext.tsx`
- [Gemini settings UI](https://github.com/jay240322/kubesense/blob/main/frontend/components/GeminiApiModal/GeminiApiModal.tsx): `frontend/components/GeminiApiModal/GeminiApiModal.tsx`
- [Analysis hooks](https://github.com/jay240322/kubesense/blob/main/frontend/hooks/useAI.ts): `frontend/hooks/useAI.ts`
- [Cluster hook](https://github.com/jay240322/kubesense/blob/main/frontend/hooks/useClusterAI.ts): `frontend/hooks/useClusterAI.ts`
- [Settings hook](https://github.com/jay240322/kubesense/blob/main/frontend/hooks/useGeminiSettings.ts): `frontend/hooks/useGeminiSettings.ts`
- [API service](https://github.com/jay240322/kubesense/blob/main/frontend/services/api.ts): `frontend/services/api.ts`

### Backend API

- [FastAPI routes](https://github.com/jay240322/kubesense/blob/main/backend/app/main.py): `backend/app/main.py`

### Cluster diagnostics

- [Pod operations](https://github.com/jay240322/kubesense/blob/main/backend/app/kubernetes/pods.py): `backend/app/kubernetes/pods.py`
- [Kubernetes client](https://github.com/jay240322/kubesense/blob/main/backend/app/kubernetes/client.py): `backend/app/kubernetes/client.py`

### Identity and settings

- [Settings routes](https://github.com/jay240322/kubesense/blob/main/backend/app/settings/router.py): `backend/app/settings/router.py`
- [Key lookup](https://github.com/jay240322/kubesense/blob/main/backend/app/settings/service.py): `backend/app/settings/service.py`
- [Auth routes](https://github.com/jay240322/kubesense/blob/main/backend/app/auth/router.py): `backend/app/auth/router.py`
- [Login service](https://github.com/jay240322/kubesense/blob/main/backend/app/auth/service.py): `backend/app/auth/service.py`
- [PostgreSQL](https://github.com/jay240322/kubesense/blob/main/backend/app/database.py): `backend/app/database.py`

### AI analysis

- [Pod analyzer](https://github.com/jay240322/kubesense/blob/main/backend/app/ai/analyzer.py): `backend/app/ai/analyzer.py`
- [Cluster analyzer](https://github.com/jay240322/kubesense/blob/main/backend/app/ai/cluster_analyzer.py): `backend/app/ai/cluster_analyzer.py`
- [AI response service](https://github.com/jay240322/kubesense/blob/main/backend/app/ai/service.py): `backend/app/ai/service.py`

### Other components

- **Engineer**
- **Kubernetes cluster**
- **Google Gemini**

## Connections

- Engineer → Dashboard: uses
- Dashboard → Pod explorer: shows
- Dashboard → Cluster analysis UI: shows
- Dashboard → Login form: offers login
- Login form → Auth context: stores token
- Pod explorer → API service: requests pod data
- Pod details → API service: requests details
- Pod logs → API service: requests logs
- Pod events → API service: requests events
- Analysis hooks → API service: requests analysis
- Cluster hook → API service: requests analysis
- Gemini settings UI → Settings hook: configures key
- Settings hook → API service: requests settings
- API service → FastAPI routes: calls API
- FastAPI routes → Pod operations: dispatches pod requests
- Pod operations → Kubernetes client: creates client
- Kubernetes client → Kubernetes cluster: queries cluster
- FastAPI routes → Pod analyzer: dispatches pod analysis
- FastAPI routes → Cluster analyzer: dispatches cluster analysis
- Pod analyzer → AI response service: generates analysis
- Cluster analyzer → AI response service: generates analysis
- AI response service → Key lookup: loads fallback key
- AI response service → Google Gemini: sends prompt
- FastAPI routes → Auth routes: includes routes
- Auth routes → Login service: calls login
- Login service → PostgreSQL: queries users
- FastAPI routes → Settings routes: includes routes
- Settings routes → Google Gemini: validates key
- Key lookup → PostgreSQL: reads settings