# tikipiya/entanglekey architecture

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

- Interactive diagram: https://gitdiagram.com/tikipiya/entanglekey
- Repository: https://github.com/tikipiya/entanglekey

## Overview

##### Project Type & Purpose
- EntangleKey is a Python “open-source tool” / library with an accompanying CLI that provides distributed session-key generation based on quantum entanglement simulation.
- It is not a monolithic web app but a modular, event-driven, async framework that orchestrates multiple internal services and communicates peer-to-peer over WebSockets.

##### Directory Structure → Implicit Architecture
- entanglekey/cli.py       → CLI entrypoint
- entanglekey/core.py      → EntangleKeyManager orchestrator
- entanglekey/config*.py   → ConfigLoader & Config model
- entanglekey/network.py   → NetworkManager (WebSocket)
- entanglekey/quantum.py   → QuantumEntanglementSimulator
- entanglekey/crypto.py    → SessionKeyGenerator & low-level crypto primitives
- entanglekey/security_monitor.py → SecurityMonitor
- entanglekey/logging_config.py    → LoggingSystem setup
- examples/                 → Consumer code (demonstrates API usage)
- tests/                    → Unit & integration tests

##### Key README Insights
- Shows six sub-systems under EntangleKeyManager: Quantum Simulator, Security Monitor, Network Manager, Config Loader, Session Key Generator, Logging System.
- Emphasizes async, event-driven, peer synchronization, and plugin-style extensibility (config formats, custom callbacks).

##### Main Components & Interactions

A. User & CLI Layer
- “User” (shell or Python import)
- CLI module → parses args, loads config → calls EntangleKeyManager
- Python API entrypoint: EntangleKeyManager class

B. Core Orchestrator
- EntangleKeyManager
- Initializes sub-components
- Runs event loop (asyncio)
- Provides start/stop, connect_instance, generate_session_key, get_session_key

C. Sub-Components
1. Config Loader
- Reads YAML/JSON/TOML, env vars, defaults
- Provides typed configuration to Manager & other components
2. Logging System
- Structured JSON logs, security vs. general
- Multi-output handlers
3. Quantum Entanglement Simulator
- Simulate Bell states, measurements → quantum entropy
- Exposes async create_entanglement, measure, verify
4. Network Manager
- WebSocket server/client, peer discovery, message routing
- Handles reconnect, broadcast, errors
5. Session Key Generator
- Combines quantum & classical entropy via HKDF, ChaCha20Poly1305, HMAC-SHA256
- Encrypt/decrypt helpers, signature, key hash
6. Security Monitor
- Hooks into quantum & network events
- Records metrics, attack detection, auto-revoke keys, alerts

D. External Entities
- File System for config files & key files
- Environment Variables
- Remote EntangleKey instances over TCP/WebSocket
- Optional TLS/SSL layer for underlying transport
- Downstream application using session keys for encryption

##### Architectural Patterns & Principles
- Layered modular design: CLI/API → Orchestrator → Sub-systems
- Async event-driven choreography (asyncio)
- Single Responsibility per module
- Dependency injection via config object
- Plugins/extensibility: new config formats, alert callbacks

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI / API Layer
    subgraph "CLI/API Layer"
        User["User (Shell / Python)"]:::external
        CLI["cli.py: CLI Module"]:::entrypoint
        User -->|"invoke"| CLI
    end
    click CLI "https://github.com/tikipiya/entanglekey/blob/main/entanglekey/cli.py"

    %% Core Library Boundary
    subgraph "EntangleKey Library Boundary"
        %% Orchestrator and Event Loop
        subgraph "EntangleKeyManager"
            EKM["core.py: EntangleKeyManager"]:::orchestrator
            Async["asyncio Event Loop"]:::mediator
            EKM -->|"runs on"| Async
            EKM -->|"load_config()"| CL
            EKM -->|"log_event()"| LS
            EKM -->|"create_entanglement() (async)"| QE
            EKM -->|"send_message()"| NM
            EKM -->|"generate_session_key()"| SK
            EKM -->|"record_event()"| SM
        end

        %% Sub-Components
        subgraph "Sub-Components"
            CL["config_loader.py: Config Loader"]:::component
            CM["config.py: Config Model"]:::component
            LS["logging_config.py: Logging System"]:::component
            QE["quantum.py: QuantumEntanglementSimulator"]:::component
            NM["network.py: Network Manager (WebSocket)"]:::component
            SK["crypto.py: SessionKeyGenerator"]:::component
            SM["security_monitor.py: Security Monitor"]:::component
            EXC["exceptions.py: Exception Definitions"]:::component
        end

        %% CLI to Orchestrator
        CLI -->|"start() / connect_instance()"| EKM
        CLI -->|"load_config"| CL
        CL -->|"returns Config"| EKM
        CM --> EKM

        %% Event Loop connections
        Async --> QE
        Async --> NM
        Async --> SK
        Async --> SM

        %% Component interactions
        LS -->|"writes to FS"| FS
        CL -->|"reads from FS"| FS
        SK -->|"store key files"| FS
    end

    click CL "https://github.com/tikipiya/entanglekey/blob/main/entanglekey/config_loader.py"
    click CM "https://github.com/tikipiya/entanglekey/blob/main/entanglekey/config.py"
    click LS "https://github.com/tikipiya/entanglekey/blob/main/entanglekey/logging_config.py"
    click QE "https://github.com/tikipiya/entanglekey/blob/main/entanglekey/quantum.py"
    click NM "https://github.com/tikipiya/entanglekey/blob/main/entanglekey/network.py"
    click SK "https://github.com/tikipiya/entanglekey/blob/main/entanglekey/crypto.py"
    click SM "https://github.com/tikipiya/entanglekey/blob/main/entanglekey/security_monitor.py"
    click EXC "https://github.com/tikipiya/entanglekey/blob/main/entanglekey/exceptions.py"

    %% External Systems
    subgraph "External Systems"
        FS["File System"]:::external
        EV["Environment Variables"]:::external
        RI["Remote Instances\n(WebSocket)"]:::external
        TLS["TLS/SSL Transport"]:::external
        DA["Downstream Application"]:::external
        TEST["tests/"]:::external
    end
    click TEST "https://github.com/tikipiya/entanglekey/tree/main/tests/"

    %% External interactions
    EV --> CL
    EKM --> RI
    RI -->|"callback"| EKM
    NM --> RI
    RI --- TLS
    NM --- TLS
    EKM --> DA

    %% Test harness
    TEST --> CL
    TEST --> LS
    TEST --> QE

    %% Class Definitions for Styling
    classDef orchestrator fill:#D6EFFF,stroke:#000,stroke-width:1px
    classDef component fill:#E0F7FA,stroke:#000
    classDef entrypoint fill:#C8E6C9,stroke:#000
    classDef external fill:#FFF9C4,stroke:#000
    classDef mediator fill:#E1BEE7,stroke:#000
```
