# Bjorn Cyberviking Architecture

This document describes the internal workings of **Bjorn Cyberviking**.
> The architecture is designed to be **modular and asynchronous**, using multi-threading to handle the display, web interface, and cyber-security operations (scanning, attacks) simultaneously.

-----

## 1\. High-Level Overview

The system relies on a **"Producer-Consumer"** model orchestrated around shared memory and a central database.

### System Data Flow

  * **User / WebUI**: Interacts with the `WebApp`, which uses `WebUtils` to read/write to the **SQLite DB**.
  * **Kernel (Main Thread)**: `Bjorn.py` initializes the `SharedData` (global state in RAM).
  * **Brain (Logic)**:
      * **Scheduler**: Plans actions based on triggers and writes them to the DB.
      * **Orchestrator**: Reads the queue from the DB, executes scripts from `/actions`, and updates results in the DB.
  * **Output (Display)**: `Display.py` reads the current state from `SharedData` and renders it to the E-Paper Screen.

-----

## 2\. Core Components

### 2.1. The Entry Point (`Bjorn.py`)

This is the global conductor.

  * **Role**: Initializes components, manages the application lifecycle, and handles stop signals.
  * **Workflow**:
    1.  Loads configuration via `SharedData`.
    2.  Starts the display thread (`Display`).
    3.  Starts the web server thread (`WebApp`).
    4.  **Network Monitor**: As soon as an interface (Wi-Fi/Eth) is active, it starts the **Orchestrator** thread (automatic mode). If the network drops, it can pause the orchestrator.

### 2.2. Central Memory (`shared.py`)

This is the backbone of the program.

  * **Role**: Stores the global state of Bjorn, accessible by all threads.
  * **Content**:
      * **Configuration**: Loaded from the DB (`config`).
      * **Runtime State**: Current status (`IDLE`, `SCANNING`...), displayed text, indicators (wifi, bluetooth, battery).
      * **Resources**: File paths, fonts, images loaded into RAM.
      * **Singleton DB**: A unique instance of `BjornDatabase` to avoid access conflicts.

### 2.3. Persistent Storage (`database.py`)

A facade (wrapper) for **SQLite**.

  * **Architecture**: Delegates specific operations to sub-modules (in `db_utils/`) to keep the code clean (e.g., `HostOps`, `QueueOps`, `VulnerabilityOps`).
  * **Role**: Ensures persistence of discovered hosts, vulnerabilities, the action queue, and logs.

-----

## 3\. The Operational Core: Scheduler vs Orchestrator

This is where Bjorn's "intelligence" lies. The system separates **decision** from **action**.

### 3.1. The Scheduler (`action_scheduler.py`)

*It "thinks" but does not act.*

  * **Role**: Analyzes the environment and populates the queue (`action_queue`).
  * **Logic**:
      * It loops regularly to check **Triggers** defined in actions (e.g., `on_new_host`, `on_open_port:80`, `on_interval:600`).
      * If a condition is met (e.g., a new PC is discovered), it inserts the corresponding action into the database with the status `pending`.
      * It manages priorities and avoids duplicates.

### 3.2. The Orchestrator (`orchestrator.py`)

*It acts but does not deliberate on strategic consequences.*

  * **Role**: Consumes the queue.
  * **Logic**:
    1.  Requests the next priority action (`pending`) from the DB.
    2.  Dynamically loads the corresponding Python module from the `/actions` folder (via `importlib`).
    3.  Executes the `run()` or `execute()` method of the action.
    4.  Updates the result (`success`/`failed`) in the DB.
    5.  Updates the status displayed on the screen (via `SharedData`).

-----

## 4\. User Interface

### 4.1. E-Ink Display (`display.py` & `epd_manager.py`)

  * **EPD Manager**: `epd_manager.py` is a singleton handling low-level hardware access (SPI) to prevent conflicts and manage hardware timeouts.
  * **Rendering**: `display.py` constructs the image in memory (**PIL**) by assembling:
      * Bjorn's face (based on current status).
      * Statistics (skulls, lightning bolts, coins).
      * The "catchphrase" (generated by `comment.py`).
  * **Optimization**: Uses partial refresh to avoid black/white flashing, except for periodic maintenance.

### 4.2. Web Interface (`webapp.py`)

  * **Server**: A custom multi-threaded `http.server` (no heavy frameworks like Flask/Django to ensure lightness).
  * **Architecture**:
      * API requests are dynamically routed to `WebUtils` (`utils.py`).
      * The frontend communicates primarily in **JSON**.
      * Handles authentication and GZIP compression of assets.

### 4.3. The Commentator (`comment.py`)

Provides Bjorn's personality. It selects phrases from the database based on context (e.g., *"Bruteforcing SSH..."*) and the configured language, with a weighting and delay system to avoid spamming.

-----

Voici la section mise à jour avec le flux logique pour une attaque SSH sur le port 22 :

***

## 5. Typical Data Flow (Example)

Here is what happens when Bjorn identifies a vulnerable service:

1.  **Scanning (Action)**: The Orchestrator executes a scan. It discovers IP `192.168.1.50` has **port 22 (SSH) open**.
2.  **Storage**: The scanner saves the host and port status to the DB.
3.  **Reaction (Scheduler)**: In the next cycle, the `ActionScheduler` detects the open port. It checks actions that have the `on_open_port:22` trigger.
4.  **Planning**: It adds the `SSHBruteforce` action to the `action_queue` for this IP.
5.  **Execution (Orchestrator)**: The Orchestrator finishes its current task, sees the `SSHBruteforce` in the queue, picks it up, and starts the dictionary attack.
6.  **Feedback (Display)**: `SharedData` is updated. The screen displays *"Cracking 192.168.1.50"* with the corresponding  face.
7.  **Web**: The user sees the attack attempt and real-time logs on the web dashboard.

***

**Would you like me to create a diagram to illustrate this specific attack flow?**
-----

## 6\. Folder Structure

Although not provided here, the architecture implies this structure:

```text
/
├── Bjorn.py           # Root program entry
├── orchestrator.py    # Action consumer
├── shared.py          # Shared memory
├── actions/           # Python modules containing attack/scan logic (dynamically loaded)
├── data/              # Stores bjorn.db and logs
├── web/               # HTML/JS/CSS files for the interface
└── resources/         # Images, fonts (.bmp, .ttf)
```

-----

**Would you like me to generate a Mermaid.js diagram code block (Flowchart) to visualize the Scheduler/Orchestrator loop described in section 3?**