# aplonks/ether-compose architecture

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

- Interactive diagram: https://gitdiagram.com/aplonks/ether-compose
- Repository: https://github.com/aplonks/ether-compose

## Overview

##### Project Type and Purpose
- This is a Docker-Compose-orchestrated, multi-container Ethereum Proof-of-Stake (PoS) development network.
- It spawns an execution client (Geth), a consensus client (Prysm Beacon Chain & Validator), optional block explorer, and an Ether-faucet service on a single Docker network (`bcnetwork`) for local dev and testing.

##### File-Tree / Directory Analysis
- Top-level:
- `.env`, `docker-compose.yml`, `clean.sh` – config & orchestration
- `consensus/` – Prysm beacon-chain genesis & config
- `execution/` – Geth genesis, keystore, JWT secret
- Directories separate “execution” vs “consensus” layers, plus optional “explorer” & “faucet” profiles.

##### Key README Insights
- Starts from PoS genesis (Deneb fork).
- 64 pre-generated validators seeded.
- Exposes JSON-RPC/Websocket (Geth), Engine API auth port (JWT), Prysm REST & gRPC, explorer UI, faucet frontend/backend + Redis.

a. Docker Host & `bcnetwork` bridge
b. Execution Layer:
– Container “geth” (go-ethereum)
– Genesis init tasks (`geth-genesis-pos`, `create-beacon-chain-genesis`)
c. Consensus Layer:
– Container “beacon-chain” (Prysm beacon client)
– Container “validator-1” (Prysm validator client)
d. Developer Tools / Services Layer (optional profiles):
– “lite-explorer” UI (8081)
– “ether-faucet-frontend” (5001) & “ether-faucet-backend” (5002) + “redis-stack” (8001)
e. External Interfaces:
– Host ports mapped to containers (e.g. 8545, 3500, 4000, etc.)

##### Interactions & Data Flows
- Geth ←→ Prysm Beacon Chain via JWT-secured Engine API (port 8551)
- Beacon Chain exposes REST (3500) & gRPC (4000) to Validator
- Validator duties orchestrated by Beacon Chain over gRPC
- Explorer ↔ Geth JSON-RPC (8545/8546) and Beacon REST for chain data
- Faucet Backend ↔ Geth JSON-RPC to submit transactions; Frontend ↔ Backend over HTTP; Backend ↔ Redis for state

##### Architectural Patterns & Principles
- Layered architecture: Execution vs Consensus layers clearly separated
- Microservices / containerization: each component in its own Docker container
- Configuration-as-code: genesis files & YAML drive initialization
- Docker network isolation (`bcnetwork`) enforces service-to-service communication

##### Technologies & Frameworks
- Docker & Docker-Compose
- go-ethereum (Geth) for execution client
- Prysm (beacon & validator) for consensus
- Alethio Lite Explorer for block visualization
- Custom Ether-faucet (Node.js + Redis)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Host & bcnetwork"
        direction TB

        subgraph "Initialization Tasks"
            direction TB
            GenesisPOS["geth-genesis-pos"]:::init
            GenesisBeacon["create-beacon-chain-genesis"]:::init
        end

        subgraph "Execution Layer" 
            direction TB
            Geth["geth:latest"]:::exec
        end

        subgraph "Consensus Layer"
            direction TB
            Beacon["beacon-chain:latest"]:::consensus
            Validator["validator-1:latest"]:::consensus
        end

        subgraph "Supporting Services (Optional Profiles)"
            direction TB
            Explorer["lite-explorer UI"]:::explorer
            FaucetFE["ether-faucet-frontend"]:::faucet
            FaucetBE["ether-faucet-backend"]:::faucet
            Redis["redis-stack"]:::faucet
        end
    end

    %% Initialization links
    GenesisPOS -->|seeds| Geth
    GenesisBeacon -->|seeds| Beacon

    %% Core interactions
    Geth <-->|"Engine API (JWT,8551)"| Beacon
    Beacon -->|"gRPC (4000)"| Validator
    Beacon -->|"REST (3500)"| Validator

    %% Explorer interactions
    Explorer -->|"JSON-RPC (8545/8546)"| Geth
    Explorer -->|"Beacon REST (3500)"| Beacon

    %% Faucet interactions
    FaucetBE -->|"JSON-RPC (8545)"| Geth
    FaucetFE -->|"HTTP (5002)"| FaucetBE
    FaucetBE -->|"Redis (8001)"| Redis

    %% Click Events
    click docker-compose.yml "https://github.com/aplonks/ether-compose/blob/main/docker-compose.yml"
    click .env "https://github.com/aplonks/ether-compose/blob/main/.env"
    click clean.sh "https://github.com/aplonks/ether-compose/blob/main/clean.sh"
    click GenesisPOS "https://github.com/aplonks/ether-compose/blob/main/execution/genesis.json"
    click GenesisBeacon "https://github.com/aplonks/ether-compose/blob/main/execution/genesis-poa.json"
    click Geth "https://github.com/aplonks/ether-compose/tree/main/execution/"
    click Geth "https://github.com/aplonks/ether-compose/tree/main/execution/jwtsecret"
    click Geth "https://github.com/aplonks/ether-compose/blob/main/execution/keystore/UTC--2022-08-19T17-38-31.257380510Z--123463a4b065722e99115d6c222f267d9cabb524"
    click Geth "https://github.com/aplonks/ether-compose/blob/main/execution/geth_password.txt"
    click Geth "https://github.com/aplonks/ether-compose/blob/main/execution/sk.json"
    click Beacon "https://github.com/aplonks/ether-compose/blob/main/consensus/config.yml"
    click README.md "https://github.com/aplonks/ether-compose/blob/main/README.md"
    click Documentation/Resources.md "https://github.com/aplonks/ether-compose/blob/main/Documentation/Resources.md"
    click images/ "https://github.com/aplonks/ether-compose/tree/main/images/"

    %% Styling
    classDef init fill:#cdeafe,stroke:#006f9e,stroke-width:1px;
    classDef exec fill:#d0e7ff,stroke:#1f70b8,stroke-width:1px;
    classDef consensus fill:#d6f5d6,stroke:#2d9a2d,stroke-width:1px;
    classDef explorer fill:#ffe0b3,stroke:#ff9900,stroke-width:1px;
    classDef faucet fill:#fff1b3,stroke:#ffcc00,stroke-width:1px;
```
