# b0cal/miel architecture

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

- Interactive diagram: https://gitdiagram.com/b0cal/miel
- Repository: https://github.com/b0cal/miel

## Overview

##### Project type and purpose
- This is a full-stack, modular honeypot framework (“miel”) written in Rust (core engine) with a separate Web UI in JavaScript (src/webui).
- Purpose: expose configurable, containerized honeypot services (SSH, HTTP, etc.), dynamically adapt them to incoming attacker traffic, and record interactions in a database for analysis.

##### File structure
- Top-level directories/files:
- src/core: Rust binary (main.rs) and modules (Cargo.toml, .gitignore)
- src/webui: JavaScript single-page app, package.json, tests
- docs/: extensive design, UML, architecture, workflows, mockups
- scripts/: helper scripts to bootstrap Markdown, Node, Rust environments
- Makefile.toml & tasks.toml: cargo-make or similar task runner setups
- .github/workflows: CI/CD pipelines (lint, test, build, docs publish)
- Key config: .env.example (env vars for DB, ports), rust-toolchain.toml, systemd-nspawn references in docs.

##### Insights from README
- Core uses Tokio async runtime, Rust for safety & performance
- Containerization via systemd-nspawn
- Database to store packet traces, shells, metadata
- Highly modular: new services via config files

##### Main components and interactions
a. Components
1. External Actors: Attackers (network clients)
2. Miel Core (Rust)
– Network Listener(s) (TCP/HTTP/SSH)
– Request Classifier / Router
– Service Manager & Module Loader
– Container Orchestrator (systemd-nspawn)
– Data Layer (DB adapter, schema)
3. Service Containers (honeypot instances: SSH, HTTP, custom)
4. Database (PostgreSQL/MySQL/SQLite)
5. Web UI (frontend SPA)
6. CI/CD & Documentation pipelines (GitHub Actions)
b. Relationships & data flows
- Attackers → Miel Core (listeners)
- Miel Core → Service Manager → Spawn Container via systemd-nspawn
- Container ↔ Miel Core (proxy traffic, instrumentation)
- Miel Core → Database (store traces & metadata)
- Web UI ↔ Miel Core (REST/WebSocket API) → Database (read/write config & analytics)
c. Architectural patterns & principles
- Asynchronous, event-driven I/O (Tokio)
- Modular plugin/config-driven services
- Container orchestration delegated to systemd-nspawn (lightweight VMs)
- Clear separation: core engine vs. frontend vs. persistence
d. Key technologies/frameworks
- Rust & Tokio (core)
- systemd-nspawn (container runtime)
- PostgreSQL/MySQL/SQLite (DB)
- JavaScript (ESModules), Jest (tests), Prettier/ESLint (Web UI)
- cargo-make/Makefile.toml (build & task automation)
- GitHub Actions (CI/CD, docs deploy)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actor
    A["Attackers"]:::external

    %% Backend Layer
    subgraph "Backend (Rust Core)" 
        direction TB
        Core["Miel Core"]:::backend
        subgraph "Core Internals"
            direction TB
            Listener["Network Listener\n(TCP 22/80/etc)"]:::backend
            Classifier["Request Classifier / Router"]:::backend
            Loader["Module Loader"]:::backend
            Manager["Service Manager"]:::backend
            Orchestrator["Container Orchestrator\n(systemd-nspawn)"]:::backend
            DBAdapter["Data Layer (DB Adapter)"]:::backend
        end
    end

    %% Containers & Database
    subgraph "Infra Services"
        direction TB
        Host["systemd-nspawn Host"]:::infra
        DB["Database\n(PostgreSQL/MySQL/SQLite)"]:::db
    end

    %% Frontend Layer
    subgraph "Frontend (Web UI)"
        direction TB
        UI["Web UI (SPA)"]:::frontend
    end

    %% DevOps & Documentation
    subgraph "DevOps & Docs" 
        direction TB
        CI["CI/CD Pipelines\n(GitHub Actions)"]:::infra
        Build["Build & Task Automation"]:::infra
        Scripts["Environment Bootstrap Scripts"]:::infra
        Docs["Architecture & UML Diagrams"]:::infra
        Guidelines["Contribution Guidelines"]:::infra
    end

    %% Connections
    A -->|"network requests"| Listener
    Listener --> Classifier
    Classifier --> Loader
    Loader --> Manager
    Manager --> Orchestrator
    Orchestrator --> Host
    Host -->|"proxied traffic"| Orchestrator
    DBAdapter --> DB
    Orchestrator --> DBAdapter
    UI -->|REST/WebSocket API| Core
    Core -->|serves UI data| UI

    %% Click Events - Backend
    click Core "https://github.com/b0cal/miel/blob/main/src/core/main.rs"
    click Core "https://github.com/b0cal/miel/blob/main/src/core/Cargo.toml"
    click Listener "https://github.com/b0cal/miel/blob/main/src/core/main.rs"
    click Listener "https://github.com/b0cal/miel/blob/main/src/core/Cargo.toml"
    click Classifier "https://github.com/b0cal/miel/blob/main/src/core/main.rs"
    click Loader "https://github.com/b0cal/miel/blob/main/src/core/main.rs"
    click Manager "https://github.com/b0cal/miel/blob/main/src/core/main.rs"
    click Orchestrator "https://github.com/b0cal/miel/blob/main/src/core/main.rs"
    click DBAdapter "https://github.com/b0cal/miel/blob/main/src/core/main.rs"

    %% Click Events - Frontend
    click UI "https://github.com/b0cal/miel/blob/main/src/webui/package.json"
    click UI "https://github.com/b0cal/miel/blob/main/src/webui/main.js"
    click UI "https://github.com/b0cal/miel/blob/main/src/webui/main.test.js"
    click UI "https://github.com/b0cal/miel/blob/main/src/webui/.prettierrc"
    click UI "https://github.com/b0cal/miel/blob/main/src/webui/eslint.config.mjs"

    %% Click Events - Container Docs
    click Orchestrator "https://github.com/b0cal/miel/blob/main/docs/research/honeypot_services.md"
    click Orchestrator "https://github.com/b0cal/miel/blob/main/docs/research/architecture.md"

    %% Click Events - Database Config & Schema
    click DB "https://github.com/b0cal/miel/blob/main/.env.example"
    click DB "https://github.com/b0cal/miel/blob/main/docs/requirements/requirements.md"

    %% Click Events - CI/CD
    click CI "https://github.com/b0cal/miel/blob/main/.github/workflows/ci.yml"
    click CI "https://github.com/b0cal/miel/blob/main/.github/workflows/cd.yml"
    click CI "https://github.com/b0cal/miel/blob/main/.github/workflows/docs.yml"
    click CI "https://github.com/b0cal/miel/blob/main/.github/workflows/gh-pages.yml"

    %% Click Events - Build & Tasks
    click Build "https://github.com/b0cal/miel/blob/main/Makefile.toml"
    click Build "https://github.com/b0cal/miel/blob/main/tasks.toml"

    %% Click Events - Scripts
    click Scripts "https://github.com/b0cal/miel/blob/main/scripts/setup_rust.sh"
    click Scripts "https://github.com/b0cal/miel/blob/main/scripts/setup_node.sh"
    click Scripts "https://github.com/b0cal/miel/blob/main/scripts/setup_markdown.sh"

    %% Click Events - Docs & UML
    click Docs "https://github.com/b0cal/miel/tree/main/docs/design/uml"
    click Docs "https://github.com/b0cal/miel/tree/main/docs/design/mockups"

    %% Click Events - Guidelines
    click Guidelines "https://github.com/b0cal/miel/blob/main/.github/CONTRIBUTING.md"
    click Guidelines "https://github.com/b0cal/miel/blob/main/docs/development/setup.md"
    click Guidelines "https://github.com/b0cal/miel/blob/main/docs/development/ci_cd.md"

    %% Styles
    classDef backend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef frontend fill:#DFFFE0,stroke:#28a745,color:#28a745;
    classDef infra fill:#FFF4D6,stroke:#ff8c00,color:#ff8c00;
    classDef external fill:#FEE2E2,stroke:#d73a49,color:#d73a49;
    classDef db fill:#E2F0CB,stroke:#6f42c1,color:#6f42c1;
```
