# sadvik-asus/self-evolving-ai-honeypot architecture

> Architecture diagram of the GitHub repository sadvik-asus/self-evolving-ai-honeypot, 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/sadvik-asus/self-evolving-ai-honeypot
- Repository: https://github.com/sadvik-asus/self-evolving-ai-honeypot

## Overview

The product is an AI-driven SSH honeypot with a web dashboard. Attackers connect over SSH, are accepted into a simulated shell, and receive AI-generated command output; connection and interaction records support the dashboard and persona evolution. The browser dashboard also offers a demo terminal and an evolution trigger. The README documents these capabilities; sampled source confirms the main handlers and calls, while some database lifecycle details and dashboard markup were not sampled.

Main entry points: [`backend/api/web_app.py`](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/api/web_app.py) (Web API), [`backend/ssh/server.py`](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/ssh/server.py) (SSH Server), [`backend/core/ai_engine.py`](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/core/ai_engine.py) (AI Engine), [`backend/core/db.py`](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/core/db.py) (SQLite Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access Surfaces"]
  node_ssh["SSH Server<br/>[server.py]"]
  node_web["Web API<br/>[web_app.py]"]
end

subgraph group_simulation["Honeypot Simulation"]
  node_ai["AI Engine<br/>[ai_engine.py]"]
  node_persona["Persona Prompt<br/>[persona.txt]"]
  node_evolution["Evolution Engine<br/>[evolution.py]"]
end

subgraph group_intelligence["Threat Intelligence"]
  node_geoip["GeoIP Lookup<br/>[geoip.py]"]
  node_store[("SQLite Store<br/>[db.py]")]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_js["Dashboard Client<br/>[app.js]"]
  node_dashboard_html["Dashboard Page<br/>[index.html]"]
end

node_attacker(("SSH Attacker"))
node_operator(("Dashboard User"))
node_gemini["Google Gemini"]
node_geo_service["IP Geolocation Service"]
node_map_tiles["CARTO Map Tiles"]

node_attacker -->|"connects via SSH"| node_ssh
node_ssh -->|"looks up location"| node_geoip
node_geoip -->|"requests IP data"| node_geo_service
node_ssh -->|"logs connection"| node_store
node_ssh -->|"requests command output"| node_ai
node_ai -->|"reads prompt"| node_persona
node_ai -->|"sends command context"| node_gemini
node_gemini -->|"returns generated output"| node_ai
node_ssh -->|"logs interaction"| node_store
node_operator -->|"uses dashboard"| node_dashboard_js
node_dashboard_js -->|"calls dashboard APIs"| node_web
node_dashboard_html -->|"loads client"| node_dashboard_js
node_dashboard_js -.->|"loads map tiles"| node_map_tiles
node_web -->|"queries and logs"| node_store
node_store -->|"returns dashboard records"| node_web
node_web -->|"requests terminal output"| node_ai
node_web -->|"triggers evolution"| node_evolution
node_evolution -->|"reads recent commands"| node_store
node_evolution -->|"generates updated persona"| node_gemini
node_evolution -->|"writes updated prompt"| node_persona
node_web -->|"reads current prompt"| node_persona

click node_ssh "https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/ssh/server.py"
click node_web "https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/api/web_app.py"
click node_ai "https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/core/ai_engine.py"
click node_persona "https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/data/persona.txt"
click node_evolution "https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/core/evolution.py"
click node_geoip "https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/core/geoip.py"
click node_store "https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/core/db.py"
click node_dashboard_js "https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/frontend/static/app.js"
click node_dashboard_html "https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/frontend/templates/index.html"

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_ssh,node_web,node_operator toneBlue
class node_ai,node_persona,node_evolution toneAmber
class node_geoip,node_store toneMint
class node_dashboard_js,node_dashboard_html toneRose
class node_attacker,node_gemini,node_geo_service,node_map_tiles toneIndigo
```

## Components

### Access Surfaces

- [SSH Server](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/ssh/server.py): `backend/ssh/server.py`
- [Web API](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/api/web_app.py): `backend/api/web_app.py`

### Honeypot Simulation

- [AI Engine](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/core/ai_engine.py): `backend/core/ai_engine.py`
- [Persona Prompt](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/data/persona.txt): `data/persona.txt`
- [Evolution Engine](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/core/evolution.py): `backend/core/evolution.py`

### Threat Intelligence

- [GeoIP Lookup](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/core/geoip.py): `backend/core/geoip.py`
- [SQLite Store](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/backend/core/db.py): `backend/core/db.py`

### Dashboard

- [Dashboard Client](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/frontend/static/app.js): `frontend/static/app.js`
- [Dashboard Page](https://github.com/sadvik-asus/self-evolving-ai-honeypot/blob/main/frontend/templates/index.html): `frontend/templates/index.html`

### Other components

- **SSH Attacker**
- **Dashboard User**
- **Google Gemini**
- **IP Geolocation Service**
- **CARTO Map Tiles**

## Connections

- SSH Attacker → SSH Server: connects via SSH
- SSH Server → GeoIP Lookup: looks up location
- GeoIP Lookup → IP Geolocation Service: requests IP data
- SSH Server → SQLite Store: logs connection
- SSH Server → AI Engine: requests command output
- AI Engine → Persona Prompt: reads prompt
- AI Engine → Google Gemini: sends command context
- Google Gemini → AI Engine: returns generated output
- SSH Server → SQLite Store: logs interaction
- Dashboard User → Dashboard Client: uses dashboard
- Dashboard Client → Web API: calls dashboard APIs
- Dashboard Page → Dashboard Client: loads client
- Dashboard Client → CARTO Map Tiles: loads map tiles
- Web API → SQLite Store: queries and logs
- SQLite Store → Web API: returns dashboard records
- Web API → AI Engine: requests terminal output
- Web API → Evolution Engine: triggers evolution
- Evolution Engine → SQLite Store: reads recent commands
- Evolution Engine → Google Gemini: generates updated persona
- Evolution Engine → Persona Prompt: writes updated prompt
- Web API → Persona Prompt: reads current prompt