# akshayareddy-1023/canary-token-honey-token-deception-system architecture

> Architecture diagram of the GitHub repository akshayareddy-1023/canary-token-honey-token-deception-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akshayareddy-1023/canary-token-honey-token-deception-system
- Repository: https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system

## Overview

Canary Token is a Flask-based deception and incident-monitoring application. An administrator authenticates and creates URL or file honeytokens; a user encounters a decoy resource, triggering request capture, alerting, and event storage. The administrator dashboard presents incidents and supports application-level IP blocking. The graph preserves the distinct token-generation, detection, alert, persistence, and response stages. Some route and template details are documented in the README but were not fully sampled, so those links cite the README.

Main entry points: [`app/app.py`](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/app/app.py) (Flask routes), [`honeytokens/file_honeytoken.py`](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/honeytokens/file_honeytoken.py) (File token generator), [`templates/dashboard.html`](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/templates/dashboard.html) (Admin dashboard), [`templates/user_dashboard.html`](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/templates/user_dashboard.html) (User dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_flask["Flask routes<br/>[app.py]"]
  node_admin_ui["Admin dashboard<br/>[dashboard.html]"]
  node_user_ui["User dashboard"]
  node_login_ui["Admin login<br/>[admin_login.html]"]
end

subgraph group_tokens["Honeytoken resources"]
  node_url_token["URL token generator<br/>[generator.py]"]
  node_file_token["File token generator<br/>[file_honeytoken.py]"]
  node_token_records[("Token records")]
  node_decoys[("Decoy files")]
end

subgraph group_monitoring["Detection and alerts"]
  node_event_capture["Event capture<br/>[detector.py]"]
  node_alert["Alert generation<br/>[alert_manager.py]"]
  node_geo["IP geolocation<br/>[app.py]"]
end

subgraph group_security["Administration and storage"]
  node_event_store[("Incident and block store<br/>[database.py]")]
  node_auth["Admin authentication<br/>[admin_auth.py]"]
end

node_admin(("Administrator"))
node_user(("User"))
node_geo_service["IP lookup service"]

node_admin -->|"signs in"| node_login_ui
node_admin_ui -->|"requests actions"| node_flask
node_flask -->|"verifies credentials"| node_auth
node_flask -->|"generates URL tokens"| node_url_token
node_flask -->|"generates file tokens"| node_file_token
node_file_token -->|"writes records"| node_token_records
node_url_token -->|"writes records"| node_token_records
node_file_token -->|"creates decoy files"| node_decoys
node_user -->|"views resources"| node_user_ui
node_user_ui -->|"opens decoy"| node_flask
node_flask -->|"captures request"| node_event_capture
node_flask -->|"updates token status"| node_token_records
node_flask -->|"looks up location"| node_geo
node_geo -->|"queries location"| node_geo_service
node_flask -->|"generates alert"| node_alert
node_flask -->|"saves incident"| node_event_store
node_flask -->|"checks blocked IP"| node_event_store
node_flask -->|"blocks or unblocks IP"| node_event_store
node_admin -->|"reviews incidents"| node_admin_ui
node_flask -->|"serves dashboard"| node_admin_ui
node_flask -->|"serves dashboard"| node_user_ui

click node_flask "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/app/app.py"
click node_admin_ui "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/templates/dashboard.html"
click node_user_ui "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/templates/user_dashboard.html"
click node_login_ui "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/templates/admin_login.html"
click node_url_token "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/honeytokens/generator.py"
click node_file_token "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/honeytokens/file_honeytoken.py"
click node_token_records "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/tree/main/honeytokens"
click node_decoys "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/tree/main/decoy_files"
click node_event_capture "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/detection/detector.py"
click node_alert "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/alerts/alert_manager.py"
click node_geo "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/app/app.py"
click node_event_store "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/database/database.py"
click node_auth "https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/database/admin_auth.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_flask,node_admin_ui,node_user_ui,node_login_ui,node_user toneBlue
class node_url_token,node_file_token,node_token_records,node_decoys toneAmber
class node_event_capture,node_alert,node_geo toneMint
class node_event_store,node_auth toneRose
class node_admin,node_geo_service toneIndigo
```

## Components

### Web application

- [Flask routes](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/app/app.py): `app/app.py`
- [Admin dashboard](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/templates/dashboard.html): `templates/dashboard.html`
- [User dashboard](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/templates/user_dashboard.html): `templates/user_dashboard.html`
- [Admin login](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/templates/admin_login.html): `templates/admin_login.html`

### Honeytoken resources

- [URL token generator](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/honeytokens/generator.py): `honeytokens/generator.py`
- [File token generator](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/honeytokens/file_honeytoken.py): `honeytokens/file_honeytoken.py`
- [Token records](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/tree/main/honeytokens): `honeytokens`
- [Decoy files](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/tree/main/decoy_files): `decoy_files`

### Detection and alerts

- [Event capture](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/detection/detector.py): `detection/detector.py`
- [Alert generation](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/alerts/alert_manager.py): `alerts/alert_manager.py`
- [IP geolocation](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/app/app.py): `app/app.py`

### Administration and storage

- [Incident and block store](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/database/database.py): `database/database.py`
- [Admin authentication](https://github.com/akshayareddy-1023/canary-token-honey-token-deception-system/blob/main/database/admin_auth.py): `database/admin_auth.py`

### Other components

- **Administrator**
- **User**
- **IP lookup service**

## Connections

- Administrator → Admin login: signs in (evidence: `README.md`)
- Admin dashboard → Flask routes: requests actions (evidence: `README.md`)
- Flask routes → Admin authentication: verifies credentials (evidence: `app/app.py`)
- Flask routes → URL token generator: generates URL tokens (evidence: `app/app.py`)
- Flask routes → File token generator: generates file tokens (evidence: `app/app.py`)
- File token generator → Token records: writes records (evidence: `honeytokens/file_honeytoken.py`)
- URL token generator → Token records: writes records (evidence: `honeytokens/generator.py`)
- File token generator → Decoy files: creates decoy files (evidence: `honeytokens/file_honeytoken.py`)
- User → User dashboard: views resources (evidence: `README.md`)
- User dashboard → Flask routes: opens decoy (evidence: `README.md`)
- Flask routes → Event capture: captures request (evidence: `app/app.py`)
- Flask routes → Token records: updates token status (evidence: `app/app.py`)
- Flask routes → IP geolocation: looks up location (evidence: `app/app.py`)
- IP geolocation → IP lookup service: queries location (evidence: `app/app.py`)
- Flask routes → Alert generation: generates alert (evidence: `app/app.py`)
- Flask routes → Incident and block store: saves incident (evidence: `app/app.py`)
- Flask routes → Incident and block store: checks blocked IP (evidence: `app/app.py`)
- Flask routes → Incident and block store: blocks or unblocks IP (evidence: `app/app.py`)
- Administrator → Admin dashboard: reviews incidents (evidence: `README.md`)
- Flask routes → Admin dashboard: serves dashboard (evidence: `README.md`)
- Flask routes → User dashboard: serves dashboard (evidence: `README.md`)
