# popla69/poplashield architecture

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

- Interactive diagram: https://gitdiagram.com/popla69/poplashield
- Repository: https://github.com/popla69/poplashield

## Overview

PoplaShield is an adaptive defense system that analyzes simulated attacks, updates defenses, and saves learned state for later runs. Its main workflow is launched by the training runner: initialize and start the shield, then train it with simulated attacks and optionally run targeted adversarial rounds. The sampled code shows the defense engine’s threat analysis and evolution, plus monitoring and persistence. Training and adversarial behavior are described in the excerpts, but some implementation details are omitted; unsupported internal links are therefore left out.

Main entry points: [`PoplaShield/popla_shield.py`](https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py) (Shield Orchestrator), [`PoplaShield/run_training.py`](https://github.com/popla69/poplashield/blob/main/PoplaShield/run_training.py) (Training Runner), [`PoplaShield/shield_trainer.py`](https://github.com/popla69/poplashield/blob/main/PoplaShield/shield_trainer.py) (Shield Trainer), [`PoplaShield/shield_config.json`](https://github.com/popla69/poplashield/blob/main/PoplaShield/shield_config.json) (Shield Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry_training["Training"]
  node_training_runner["Training Runner<br/>[run_training.py]"]
  node_attack_simulator["Attack Simulator<br/>[shield_trainer.py]"]
  node_shield_trainer["Shield Trainer<br/>[shield_trainer.py]"]
  node_adversarial_trainer["Adversarial Trainer<br/>[shield_trainer.py]"]
end

subgraph group_shield_runtime["Shield Runtime"]
  node_shield["Shield Orchestrator<br/>[popla_shield.py]"]
  node_attack_signature["Attack Signature<br/>[popla_shield.py]"]
  node_defense_engine["Adaptive Defense Engine<br/>[popla_shield.py]"]
end

subgraph group_analysis_evolution["Analysis &amp; Evolution"]
  node_threat_intel["Threat Intelligence<br/>[popla_shield.py]"]
  node_defense_rules["Defense Rules &amp; Evolution<br/>[popla_shield.py]"]
end

subgraph group_state_monitoring["State &amp; Monitoring"]
  node_monitor["Runtime Monitor<br/>[popla_shield.py]"]
  node_config["Shield Configuration<br/>[shield_config.json]"]
  node_state_file[("Saved Defense State<br/>[defense_state.pkl]")]
end

node_operator(("Operator"))

node_operator -->|"starts"| node_training_runner
node_training_runner -->|"initializes"| node_shield
node_training_runner -->|"starts training"| node_shield_trainer
node_training_runner -->|"optionally runs"| node_adversarial_trainer
node_shield_trainer -->|"creates"| node_attack_simulator
node_shield_trainer -->|"submits attacks"| node_shield
node_adversarial_trainer -->|"submits attacks"| node_shield
node_shield -->|"loads"| node_config
node_shield -->|"creates"| node_defense_engine
node_shield -->|"creates"| node_monitor
node_defense_engine -->|"analyzes attacks"| node_threat_intel
node_defense_engine -->|"evolves defenses"| node_defense_rules
node_shield -->|"starts monitoring"| node_monitor
node_defense_engine -->|"loads and saves"| node_state_file

click node_training_runner "https://github.com/popla69/poplashield/blob/main/PoplaShield/run_training.py"
click node_attack_simulator "https://github.com/popla69/poplashield/blob/main/PoplaShield/shield_trainer.py"
click node_shield_trainer "https://github.com/popla69/poplashield/blob/main/PoplaShield/shield_trainer.py"
click node_adversarial_trainer "https://github.com/popla69/poplashield/blob/main/PoplaShield/shield_trainer.py"
click node_shield "https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py"
click node_attack_signature "https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py"
click node_defense_engine "https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py"
click node_threat_intel "https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py"
click node_defense_rules "https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py"
click node_monitor "https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py"
click node_config "https://github.com/popla69/poplashield/blob/main/PoplaShield/shield_config.json"
click node_state_file "https://github.com/popla69/poplashield/blob/main/PoplaShield/defense_state.pkl"

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_training_runner,node_attack_simulator,node_shield_trainer,node_adversarial_trainer toneBlue
class node_shield,node_attack_signature,node_defense_engine toneAmber
class node_threat_intel,node_defense_rules toneMint
class node_monitor,node_config,node_state_file toneRose
class node_operator toneIndigo
```

## Components

### Training

- [Training Runner](https://github.com/popla69/poplashield/blob/main/PoplaShield/run_training.py): `PoplaShield/run_training.py`
- [Attack Simulator](https://github.com/popla69/poplashield/blob/main/PoplaShield/shield_trainer.py): `PoplaShield/shield_trainer.py`
- [Shield Trainer](https://github.com/popla69/poplashield/blob/main/PoplaShield/shield_trainer.py): `PoplaShield/shield_trainer.py`
- [Adversarial Trainer](https://github.com/popla69/poplashield/blob/main/PoplaShield/shield_trainer.py): `PoplaShield/shield_trainer.py`

### Shield Runtime

- [Shield Orchestrator](https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py): `PoplaShield/popla_shield.py`
- [Attack Signature](https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py): `PoplaShield/popla_shield.py`
- [Adaptive Defense Engine](https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py): `PoplaShield/popla_shield.py`

### Analysis & Evolution

- [Threat Intelligence](https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py): `PoplaShield/popla_shield.py`
- [Defense Rules & Evolution](https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py): `PoplaShield/popla_shield.py`

### State & Monitoring

- [Runtime Monitor](https://github.com/popla69/poplashield/blob/main/PoplaShield/popla_shield.py): `PoplaShield/popla_shield.py`
- [Shield Configuration](https://github.com/popla69/poplashield/blob/main/PoplaShield/shield_config.json): `PoplaShield/shield_config.json`
- [Saved Defense State](https://github.com/popla69/poplashield/blob/main/PoplaShield/defense_state.pkl): `PoplaShield/defense_state.pkl`

### Other components

- **Operator**

## Connections

- Operator → Training Runner: starts (evidence: `PoplaShield/run_training.py`)
- Training Runner → Shield Orchestrator: initializes (evidence: `PoplaShield/run_training.py`)
- Training Runner → Shield Trainer: starts training (evidence: `PoplaShield/run_training.py`)
- Training Runner → Adversarial Trainer: optionally runs (evidence: `PoplaShield/run_training.py`)
- Shield Trainer → Attack Simulator: creates (evidence: `PoplaShield/shield_trainer.py`)
- Shield Trainer → Shield Orchestrator: submits attacks (evidence: `PoplaShield/shield_trainer.py`)
- Adversarial Trainer → Shield Orchestrator: submits attacks (evidence: `PoplaShield/shield_trainer.py`)
- Shield Orchestrator → Shield Configuration: loads (evidence: `PoplaShield/popla_shield.py`)
- Shield Orchestrator → Adaptive Defense Engine: creates (evidence: `PoplaShield/popla_shield.py`)
- Shield Orchestrator → Runtime Monitor: creates (evidence: `PoplaShield/popla_shield.py`)
- Adaptive Defense Engine → Threat Intelligence: analyzes attacks (evidence: `PoplaShield/popla_shield.py`)
- Adaptive Defense Engine → Defense Rules & Evolution: evolves defenses (evidence: `PoplaShield/popla_shield.py`)
- Shield Orchestrator → Runtime Monitor: starts monitoring (evidence: `PoplaShield/popla_shield.py`)
- Adaptive Defense Engine → Saved Defense State: loads and saves (evidence: `PoplaShield/popla_shield.py`)
