# kiurakku/dracolure architecture

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

- Interactive diagram: https://gitdiagram.com/kiurakku/dracolure
- Repository: https://github.com/kiurakku/dracolure

## Overview

#### Purpose and deployment shape
DracoLure is a defensive, HTTP-focused deception honeypot and reusable threat-classification service. It receives probes, serves fabricated decoys, classifies malicious content, maintains per-source risk/quarantine state, and exposes events and metrics. The primary local/full-stack entry point is `docker-compose.yml`; the application server starts from `app/main.py`. Edge routing is handled by `nginx/default.conf`.

#### Flask sentinel and deception surface
The Python/Flask service is the central control plane and public honeypot surface. A request-wide pre-route sentinel checks quarantine status before application routes execute; quarantined sources receive delayed 403 responses. Non-blocked requests are analyzed and then routed to bait or normal error responses. Deceptive endpoint content is isolated from detection and state logic.
- `app/main.py`
- `app/decoys.py`
- `app/Dockerfile`

#### Detection and threat-state pipeline
Detection normalizes request material—including encoded forms—and examines path, query, body, and user agent against attack signatures. It produces categories and weighted scores, capped at 100 with severity bands. Threat state aggregates scores over a rolling window per source IP, triggers TTL-based quarantine at the configured threshold, and drives tarpit behavior.
- `app/detection.py`
- `app/threat.py`
- `app/main.py`

#### Persistence and event boundary
Classified malicious events are persisted to PostgreSQL while the service remains fail-open if the database is unavailable. The relational schema, indexes, and honeypot-event evolution are versioned independently of Python code. This is the durable boundary for attack records, logs, and dashboard-oriented querying.
- `app/database.py`
- `db/init.sql`
- `db/migrations/003_honeypot_events.sql`

#### Integration and operator APIs
The Flask service exposes `/api/v1` as a remote ingestion/verdict interface plus operational stats, event retrieval, and block/unblock controls. API-key enforcement is optional. External applications can submit request metadata via the stdlib Python client or WSGI/ASGI middleware; middleware is fail-open so caller availability does not depend on DracoLure.
- `app/api.py`
- `integrations/python-sdk/dracolure/client.py`
- `integrations/python-sdk/dracolure/middleware.py`

#### Supporting services and observability
nginx fronts HTTP traffic and routes honeypot versus Go logging traffic. The Go service independently records raw request logs to PostgreSQL. Prometheus scrapes service metrics; provisioned Grafana dashboards visualize categories, severity, scores, and quarantines. A Tkinter desktop console operates against the Flask API rather than directly accessing storage.
- `backend/go-service/main.go`
- `monitoring/prometheus.yml`
- `monitoring/grafana/dashboards/honeypot-dashboard.json`

#### Polyglot and infrastructure boundaries
The runnable stack uses Python 3.11/Flask, Go 1.21, C++17, PostgreSQL 15, Docker Compose, nginx, Prometheus, and Grafana. The C++ analyzer is a sidecar/demo-oriented log analyzer, separate from the live Flask classification path. Terraform provides optional cloud infrastructure provisioning; CI/CD workflows build, test, containerize, deploy, and apply infrastructure.
- `backend/cpp-analyzer/main.cpp`
- `infrastructure/terraform/main.tf`
- `.github/workflows/ci-cd.yml`

Main entry points: [`app/main.py`](https://github.com/kiurakku/dracolure/blob/main/app/main.py) (Flask honeypot server), [`docker-compose.yml`](https://github.com/kiurakku/dracolure/blob/main/docker-compose.yml) (Docker Compose stack), [`backend/go-service/main.go`](https://github.com/kiurakku/dracolure/blob/main/backend/go-service/main.go) (Go raw logger), [`db/init.sql`](https://github.com/kiurakku/dracolure/blob/main/db/init.sql) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge & Deception"]
  node_compose{{"Docker Compose stack<br/>orchestration<br/>[docker-compose.yml]"}}
  node_nginx["nginx router<br/>reverse proxy<br/>[default.conf]"]
end

subgraph group_flask["Flask Control Plane"]
  node_flask["Flask honeypot server<br/>Python/Flask<br/>[main.py]"]
  node_sentinel["Pre-route sentinel<br/>request guard<br/>[main.py]"]
  node_detection["Threat detection<br/>classifier<br/>[detection.py]"]
  node_threat["Threat state<br/>risk state<br/>[threat.py]"]
  node_decoys["Decoy endpoints<br/>deception content<br/>[decoys.py]"]
  node_api["Operator &amp; ingestion API<br/>Flask API<br/>[api.py]"]
end

subgraph group_data["Data &amp; Observability"]
  node_persistence["Event persistence<br/>database adapter<br/>[database.py]"]
  node_postgres[("PostgreSQL<br/>durable event store<br/>[init.sql]")]
  node_event_migration["Honeypot event schema<br/>SQL migration"]
  node_go_logger["Go raw logger<br/>Go service<br/>[main.go]"]
  node_prometheus["Prometheus<br/>metrics collector<br/>[prometheus.yml]"]
  node_grafana["Grafana dashboard<br/>observability UI"]
end

subgraph group_integrations["Clients &amp; Integrations"]
  node_python_client["Python SDK client<br/>stdlib client<br/>[client.py]"]
  node_middleware["WSGI/ASGI middleware<br/>integration middleware<br/>[middleware.py]"]
end

subgraph group_delivery["Delivery &amp; Optional Tools"]
  node_cpp_analyzer["C++ log analyzer<br/>sidecar/demo analyzer<br/>[main.cpp]"]
  node_terraform["Terraform provisioning<br/>infrastructure as code<br/>[main.tf]"]
  node_ci_cd["CI/CD workflow<br/>automation pipeline<br/>[ci-cd.yml]"]
end

node_compose -->|"starts"| node_nginx
node_compose -->|"starts"| node_flask
node_compose -->|"starts"| node_postgres
node_compose -->|"starts"| node_go_logger
node_nginx -->|"honeypot HTTP"| node_flask
node_nginx -->|"logging traffic"| node_go_logger
node_flask -->|"pre-route check"| node_sentinel
node_sentinel -->|"quarantine lookup"| node_threat
node_flask -->|"analyzes non-blocked requests"| node_detection
node_detection -->|"score and category"| node_threat
node_threat -->|"quarantine state"| node_sentinel
node_flask -->|"serves bait"| node_decoys
node_flask -->|"exposes API"| node_api
node_detection -->|"malicious event"| node_persistence
node_persistence -->|"persist events"| node_postgres
node_event_migration -.->|"evolves schema"| node_postgres
node_go_logger -->|"raw logs"| node_postgres
node_prometheus -->|"scrapes metrics"| node_flask
node_prometheus -->|"scrapes metrics"| node_go_logger
node_grafana -->|"queries metrics"| node_prometheus
node_python_client -->|"ingestion and verdicts"| node_api
node_middleware -->|"uses"| node_python_client
node_ci_cd -.->|"containerizes and deploys"| node_compose
node_ci_cd -.->|"applies infrastructure"| node_terraform

click node_compose "https://github.com/kiurakku/dracolure/blob/main/docker-compose.yml"
click node_nginx "https://github.com/kiurakku/dracolure/blob/main/nginx/default.conf"
click node_flask "https://github.com/kiurakku/dracolure/blob/main/app/main.py"
click node_sentinel "https://github.com/kiurakku/dracolure/blob/main/app/main.py"
click node_detection "https://github.com/kiurakku/dracolure/blob/main/app/detection.py"
click node_threat "https://github.com/kiurakku/dracolure/blob/main/app/threat.py"
click node_decoys "https://github.com/kiurakku/dracolure/blob/main/app/decoys.py"
click node_api "https://github.com/kiurakku/dracolure/blob/main/app/api.py"
click node_persistence "https://github.com/kiurakku/dracolure/blob/main/app/database.py"
click node_postgres "https://github.com/kiurakku/dracolure/blob/main/db/init.sql"
click node_event_migration "https://github.com/kiurakku/dracolure/blob/main/db/migrations/003_honeypot_events.sql"
click node_go_logger "https://github.com/kiurakku/dracolure/blob/main/backend/go-service/main.go"
click node_prometheus "https://github.com/kiurakku/dracolure/blob/main/monitoring/prometheus.yml"
click node_grafana "https://github.com/kiurakku/dracolure/blob/main/monitoring/grafana/dashboards/honeypot-dashboard.json"
click node_python_client "https://github.com/kiurakku/dracolure/blob/main/integrations/python-sdk/dracolure/client.py"
click node_middleware "https://github.com/kiurakku/dracolure/blob/main/integrations/python-sdk/dracolure/middleware.py"
click node_cpp_analyzer "https://github.com/kiurakku/dracolure/blob/main/backend/cpp-analyzer/main.cpp"
click node_terraform "https://github.com/kiurakku/dracolure/blob/main/infrastructure/terraform/main.tf"
click node_ci_cd "https://github.com/kiurakku/dracolure/blob/main/.github/workflows/ci-cd.yml"

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_compose,node_nginx toneBlue
class node_flask,node_sentinel,node_detection,node_threat,node_decoys,node_api toneAmber
class node_persistence,node_postgres,node_event_migration,node_go_logger,node_prometheus,node_grafana toneMint
class node_python_client,node_middleware toneRose
class node_cpp_analyzer,node_terraform,node_ci_cd toneIndigo
```

## Components

### Edge & Deception

- [Docker Compose stack](https://github.com/kiurakku/dracolure/blob/main/docker-compose.yml): orchestration · Primary local full-stack entry point. · `docker-compose.yml`
- [nginx router](https://github.com/kiurakku/dracolure/blob/main/nginx/default.conf): reverse proxy · Routes honeypot and Go logging traffic. · `nginx/default.conf`

### Flask Control Plane

- [Flask honeypot server](https://github.com/kiurakku/dracolure/blob/main/app/main.py): Python/Flask · Public deception surface and control plane. · `app/main.py`
- [Pre-route sentinel](https://github.com/kiurakku/dracolure/blob/main/app/main.py): request guard · Checks quarantine and tarpits blocked sources. · `app/main.py`
- [Threat detection](https://github.com/kiurakku/dracolure/blob/main/app/detection.py): classifier · Normalizes request material and assigns categories, scores, and severity. · `app/detection.py`
- [Threat state](https://github.com/kiurakku/dracolure/blob/main/app/threat.py): risk state · Maintains rolling per-IP scores and TTL quarantine. · `app/threat.py`
- [Decoy endpoints](https://github.com/kiurakku/dracolure/blob/main/app/decoys.py): deception content · Fabricated bait responses isolated from detection logic. · `app/decoys.py`
- [Operator & ingestion API](https://github.com/kiurakku/dracolure/blob/main/app/api.py): Flask API · Provides verdicts, events, stats, and block controls under /api/v1. · `app/api.py`

### Data & Observability

- [Event persistence](https://github.com/kiurakku/dracolure/blob/main/app/database.py): database adapter · Persists malicious events and fails open on database outage. · `app/database.py`
- [PostgreSQL](https://github.com/kiurakku/dracolure/blob/main/db/init.sql): durable event store · Stores attack records, logs, and dashboard query data. · `db/init.sql`
- [Honeypot event schema](https://github.com/kiurakku/dracolure/blob/main/db/migrations/003_honeypot_events.sql): SQL migration · `db/migrations/003_honeypot_events.sql`
- [Go raw logger](https://github.com/kiurakku/dracolure/blob/main/backend/go-service/main.go): Go service · Independently records raw request logs. · `backend/go-service/main.go`
- [Prometheus](https://github.com/kiurakku/dracolure/blob/main/monitoring/prometheus.yml): metrics collector · Scrapes service metrics. · `monitoring/prometheus.yml`
- [Grafana dashboard](https://github.com/kiurakku/dracolure/blob/main/monitoring/grafana/dashboards/honeypot-dashboard.json): observability UI · Visualizes categories, severity, scores, and quarantines. · `monitoring/grafana/dashboards/honeypot-dashboard.json`

### Clients & Integrations

- [Python SDK client](https://github.com/kiurakku/dracolure/blob/main/integrations/python-sdk/dracolure/client.py): stdlib client · Submits request metadata for remote classification. · `integrations/python-sdk/dracolure/client.py`
- [WSGI/ASGI middleware](https://github.com/kiurakku/dracolure/blob/main/integrations/python-sdk/dracolure/middleware.py): integration middleware · Fail-open caller-side ingestion integration. · `integrations/python-sdk/dracolure/middleware.py`

### Delivery & Optional Tools

- [C++ log analyzer](https://github.com/kiurakku/dracolure/blob/main/backend/cpp-analyzer/main.cpp): sidecar/demo analyzer · Separate from the live Flask classification path. · `backend/cpp-analyzer/main.cpp`
- [Terraform provisioning](https://github.com/kiurakku/dracolure/blob/main/infrastructure/terraform/main.tf): infrastructure as code · Optional cloud infrastructure provisioning. · `infrastructure/terraform/main.tf`
- [CI/CD workflow](https://github.com/kiurakku/dracolure/blob/main/.github/workflows/ci-cd.yml): automation pipeline · Builds, tests, containerizes, deploys, and applies infrastructure. · `.github/workflows/ci-cd.yml`

## Connections

- Docker Compose stack → nginx router: starts
- Docker Compose stack → Flask honeypot server: starts
- Docker Compose stack → PostgreSQL: starts
- Docker Compose stack → Go raw logger: starts
- nginx router → Flask honeypot server: honeypot HTTP
- nginx router → Go raw logger: logging traffic
- Flask honeypot server → Pre-route sentinel: pre-route check
- Pre-route sentinel → Threat state: quarantine lookup
- Flask honeypot server → Threat detection: analyzes non-blocked requests
- Threat detection → Threat state: score and category
- Threat state → Pre-route sentinel: quarantine state
- Flask honeypot server → Decoy endpoints: serves bait
- Flask honeypot server → Operator & ingestion API: exposes API
- Threat detection → Event persistence: malicious event
- Event persistence → PostgreSQL: persist events
- Honeypot event schema → PostgreSQL: evolves schema
- Go raw logger → PostgreSQL: raw logs
- Prometheus → Flask honeypot server: scrapes metrics
- Prometheus → Go raw logger: scrapes metrics
- Grafana dashboard → Prometheus: queries metrics
- Python SDK client → Operator & ingestion API: ingestion and verdicts
- WSGI/ASGI middleware → Python SDK client: uses
- CI/CD workflow → Docker Compose stack: containerizes and deploys
- CI/CD workflow → Terraform provisioning: applies infrastructure