# daxeel/blockshell architecture

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

- Interactive diagram: https://gitdiagram.com/daxeel/blockshell
- Repository: https://github.com/daxeel/blockshell

## Overview

##### Project type and purpose
- BlockShell is a Python-based educational tool combining a command-line interface (CLI) and a lightweight web explorer. Its core purpose is to let users interactively learn blockchain fundamentals (block creation, chaining, hashing, mining, proof of work).

##### File structure
- Top-level:
- bscli.py – entry point for the CLI
- web.py – entry point for the web explorer
- setup.py, .gitignore, LICENSE, docs files – build and project metadata
- _config.yml – configuration (likely for documentation or GitHub Pages)
- Package “blockchain/”:
- chain.py – implements the Block and Blockchain logic
- templates/:
- HTML templates (blockdata.html, blocks.html, guide.html) used by web.py

##### README insights
- No external database—blockchain state is managed in memory or local files by the core library.
- Uses standard Python packages (templating engine, HTTP server) injected by setup.py dependencies.

a. Main Components
- User Interfaces
– CLI Application (bscli.py)
– Web Explorer (web.py + templates + HTTP server)
- Core Business Logic
– Blockchain module (blockchain/chain.py)
- Data Store
– In-memory or flat-file persistence managed by chain.py
- External Dependencies
– Python runtime, virtualenv/pip, templating engine (e.g., Jinja2), HTTP framework (Flask or built-in)
b. Relationships & Interactions
- CLI → Core: invokes create-block, mine, inspect commands in the blockchain module
- Web Explorer → Core: on HTTP requests, reads chain state, renders via HTML templates
- Core → Data Store: reads/writes block list to memory or disk
c. Architectural Patterns & Principles
- Monolithic modular design: distinct “presentation” (CLI & web) and “domain” (blockchain core) layers
- Separation of concerns: UI layers never implement block logic—they defer to chain.py
- Lightweight server: embedded web server with templating, no heavy frameworks or microservices
d. Key Technologies & Frameworks
- Python 2.7+ with virtualenv
- Setup via setuptools (setup.py) for CLI entry point (“blockshell”) and web entry point (“blockshell-web” or similar)
- Template engine (Jinja2) for HTML views
- HTTP server (Flask or Bottle) for the explorer

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::user
    CLI["CLI Application (blockshell CLI)"]:::ui
    Web["Web Explorer (web.py)"]:::ui

    subgraph "HTML Templates"
        T1["blockdata.html"]:::ui
        T2["blocks.html"]:::ui
        T3["guide.html"]:::ui
    end

    subgraph "Blockchain Core Library"
        Init["__init__.py"]:::core
        Chain["chain.py"]:::core
    end

    DataStore(["In-memory / Flat File Store"]):::storage

    subgraph "Project Config & Metadata"
        Setup["setup.py"]:::ext
        Config["_config.yml"]:::ext
        License["LICENSE"]:::ext
    end

    User -->|"interacts with"| CLI
    User -->|"visits"| Web
    CLI -->|"function calls"| Chain
    Web -->|"HTTP request/response"| Chain
    Web -->|"renders via"| T1
    Web -->|"renders via"| T2
    Web -->|"renders via"| T3
    Chain -->|"read/write blocks"| DataStore

    click CLI "https://github.com/daxeel/blockshell/blob/master/bscli.py"
    click Web "https://github.com/daxeel/blockshell/blob/master/web.py"
    click T1 "https://github.com/daxeel/blockshell/blob/master/templates/blockdata.html"
    click T2 "https://github.com/daxeel/blockshell/blob/master/templates/blocks.html"
    click T3 "https://github.com/daxeel/blockshell/blob/master/templates/guide.html"
    click Chain "https://github.com/daxeel/blockshell/blob/master/blockchain/chain.py"
    click Init "https://github.com/daxeel/blockshell/blob/master/blockchain/__init__.py"
    click Setup "https://github.com/daxeel/blockshell/blob/master/setup.py"
    click Config "https://github.com/daxeel/blockshell/blob/master/_config.yml"
    click License "https://github.com/daxeel/blockshell/tree/master/LICENSE"

    classDef user fill:#f9f,stroke:#333,stroke-width:1px
    classDef ui fill:#9f9,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef storage fill:#ddd,stroke:#333,stroke-width:1px
    classDef ext fill:#fdb,stroke:#333,stroke-width:1px
```
