adding template for architecture section

mpoke · mpoke · commit be0d30f1f349 · 2025-11-26T18:34:41.000+01:00
diff --git a/README.md b/README.md
@@ -24,16 +24,15 @@ Emerald empowers institutions to build production-ready networks with tailored g
 
 ## Architecture
 
-Emerald's architecture is intentionally clean and composable, consisting of four key components: 
+Emerald's architecture is intentionally clean and composable, consisting of three key components: 
 
 - The [Malachite][malachite] consensus engine
-- An Ethereum execution client (currently [Reth][reth])
-- A lightweight shim layer that connects consensus and execution via [Engine API][engine-api]
+- An Ethereum execution client (currently [Reth][reth]) integrated via [Engine API][engine-api]
 - A proof-of-authority (PoA) module
 
 This modular design keeps the system easy to understand, maintain, and extend while providing full EVM compatibility, predictable PoA consensus, and simple deployment and operation.
 
-For more details, check out the [Architecture section of the docs](https://emerald-docs.informalsystems.io/architecture.html).
+For more details, please refer to the [Architecture](https://emerald-docs.informalsystems.io/architecture/index.html) section of the docs.
 
 ## Getting Started
 
@@ -51,17 +50,17 @@ cd emerald
 make build
 ```
 
-### Launching a Local Network
+### Deploying a Local Testnet
 
-For instructions on how to launch a local Emerald network, please refer to the [Running a Local Tesnet section of the docs](https://emerald-docs.informalsystems.io/local-testnet.html).
+For instructions on how to deploy a local Emerald testnet, please refer to the [Deploy Local Tesnet](https://emerald-docs.informalsystems.io/local-devnet/index.html) section of the docs.
 
-### Launching a Testnet
+### Launching a Production Network
 
-For instructions on how to launch am Emerald testnet, please refer to the [Creating a Production Network section of the docs](https://emerald-docs.informalsystems.io/production-network.html).
+For instructions on how to launch am Emerald production-grade network, please refer to the [Launch Production Network](https://emerald-docs.informalsystems.io/production-network/index.html) section of the docs.
 
 ## Performance Evaluation
 
-> TODO: how to run benchmarks
+> TODO: some performance number and link to how to run benchmarks
 
 ## Contributing
 
diff --git a/docs/operational-docs/src/SUMMARY.md b/docs/operational-docs/src/SUMMARY.md
@@ -10,21 +10,27 @@
 
 # Architecture
 
-- [Architecture](./architecture.md)
+
+- [Architecture](./architecture/index.md)
+  - [Consensus Engine](./architecture/consensus.md)
+  - [Ethereum Execution Client](./architecture/execution-client.md)
+  - [PoA Module](./architecture/poa.md)
+
+- [Old Architecture](./architecture.md)
 
 ---
 
 # Guides
 
-- [Local Devnet](local-devnet/README.md)
-  - [Creating a Devnet](local-devnet/create-network.md)
+- [Deploy Local Testnet](local-devnet/index.md)
+  - [Creating a Testnet](local-devnet/create-network.md)
   - [Managing Validators](local-devnet/membership-changes.md)
   - [Network Configuration](local-devnet/network-config.md)
-  - [Interacting With the Devnet](local-devnet/interactions.md)
+  - [Interacting With the Testnet](local-devnet/interactions.md)
   - [Monitoring](local-devnet/monitoring.md)
   - [Troubleshooting](local-devnet/troubleshooting.md)
   - [Common Workflows](local-devnet/workflows.md)
-- [Production Network](production-network/README.md)
+- [Launch Production Network](production-network/index.md)
   - [Network Overview](production-network/network-overview.md)
   - [Installation](production-network/installation.md)
   - [Creating Network Genesis](production-network/genesis.md)
diff --git a/docs/operational-docs/src/architecture/consensus.md b/docs/operational-docs/src/architecture/consensus.md
@@ -0,0 +1,11 @@
+# Consensus Engine
+
+Emerald leverages [Malachite](https://github.com/circlefin/malachite) as its consensus engine. 
+Malachite is the most optimized and lightweight evolution of the [Tendermint](https://arxiv.org/abs/1807.04938) Byzantine Fault Tolerant (BFT) protocol, 
+which is the most battle-tested consensus protocol in blockchain today. 
+It separates consensus from execution, allowing modular development and easy component customization.
+
+> TODO
+> - what is a consensus engine providing 
+> - what are the benefits of Malachite 
+> - how is Malachite integrated in Emerald (Channel API)
diff --git a/docs/operational-docs/src/architecture/execution-client.md b/docs/operational-docs/src/architecture/execution-client.md
@@ -0,0 +1,9 @@
+# Ethereum Execution Client
+
+Emerald integrates with Ethereum execution clients through the [Engine API](https://github.com/ethereum/execution-apis/tree/main/src/engine), allowing it to plug into a mature execution ecosystem.
+Currently, Emerald integrates with [Reth](https://github.com/paradigmxyz/reth) and we plan to support additional clients.
+
+> TODO
+> - what is an exec client providing 
+> - what are the benefits of an Ethereum exec client  
+> - how is Reth integrated in Emerald (Engine API)
diff --git a/docs/operational-docs/src/architecture/index.md b/docs/operational-docs/src/architecture/index.md
@@ -0,0 +1,12 @@
+# Architecture
+
+Emerald is a modular framework designed with simplicity at its core, enabling users to deploy reliable, easy to operate, high performance, EVM-compatible networks. 
+Its architecture is intentionally clean and composable, consisting of three key components. 
+
+- [Consensus Engine](consensus.md)  
+- [Ethereum Execution Client](execution-client.md)
+- [PoA Module](poa.md)
+
+<div style="text-align: center;">  
+    <img src="../images/emerald-architecture.png" width="40%" />
+</div>
diff --git a/docs/operational-docs/src/architecture/poa.md b/docs/operational-docs/src/architecture/poa.md
@@ -0,0 +1,8 @@
+# PoA Module
+
+Emerald adopts a proof-of-authority (PoA) model. 
+This model fits naturally with institutional networks of trust, where participants are well-known organizations that can use their reputations as stake.
+This approach prioritizes accountability and identity over anonymous resource competition, enabling predictable performance, clear governance, and a security model rooted in real-world credibility.
+
+> TODO
+> - how does the PoA module work
diff --git a/docs/operational-docs/src/introduction.md b/docs/operational-docs/src/introduction.md
@@ -1,6 +1,6 @@
 # Introducing Emerald
 
-Emerald is an open-source, modular framework designed with simplicity at its core, enabling users to deploy reliable, easy to operate, high performance, EVM-compatible networks. 
+Emerald is an open-source, modular framework for deploying reliable, easy to operate, high performance, EVM-compatible networks. 
 
 ## The Case for Emerald
 
@@ -20,10 +20,12 @@ Emerald's architecture is intentionally clean and composable, consisting of thre
 - The [Malachite](https://github.com/circlefin/malachite) consensus engine
 - An Ethereum execution client (currently [Reth](https://github.com/paradigmxyz/reth)) integrated via [Engine API](https://github.com/ethereum/execution-apis/tree/main/src/engine)
 - A proof-of-authority (PoA) module
-  
-<img src="images/emerald-architecture.png" width="40%" />
 
-> TODO: For more details, please have a look at the Emerald architecture. 
+For more details, please refer to the [Architecture](./architecture/index.md) section.
+
+<div style="text-align: center;">  
+    <img src="images/emerald-architecture.png" width="40%" />
+</div>
 
 ## Key Features
 
@@ -32,10 +34,10 @@ Emerald's modular design keeps the system easy to understand, maintain, and exte
 - **EVM Compatibility.** Full EVM compatibility enables seamless integration with existing developer workflows, libraries, and infrastructure, making it easy to build, deploy, and maintain applications.
   It also means Emerald networks can tap directly into Ethereum’s thriving DeFi landscape and the wide range of applications already built for it, including bridges, explorers, indexers, and interoperability protocols.
 - **Instant Finality.** Emerald leverages [Malachite](https://github.com/circlefin/malachite) as its consensus engine. 
-  As an implementation of the [Tendermint](https://arxiv.org/abs/1807.04938) consensus protocol, Malachite provides **single-slot finality**, meaning that transactions are finalized immediately once a block is committed.
+  As a high-performance implementation of the [Tendermint](https://arxiv.org/abs/1807.04938) Byzantine Fault Tolerant (BFT) protocol, Malachite provides _instant finality_, meaning that transactions are finalized immediately once a block is committed.
 - **Predictable Performance.** Emerald's PoA-based model not only fits naturally with institutional networks of trust (where participants are well-known organizations that can use their reputations as stake), but it enables predictable performance. With a fixed, accountable validator set and instant finality consensus, block times remain stable, latency is low, and throughput is consistent.
 - **Simple Deployment and Operation.** Emerald is built on battle-tested technology: Malachite is a formally verified Tendermint consensus implementation and Reth is a high-performance Ethereum execution client. 
-  In addition, Emerald comes with a state-of-the-art [runbook on how to operate a production network](../production-network/README.md). 
+  In addition, Emerald comes with a state-of-the-art [runbook on how to operate a production network](../production-network/index.md). 
 
 ## Use Cases
 
diff --git a/docs/operational-docs/src/local-devnet/create-network.md b/docs/operational-docs/src/local-devnet/create-network.md
@@ -1,4 +1,4 @@
-# Creating a Devnet
+# Creating a Testnet
 
 ## Prerequisites
 
@@ -27,9 +27,9 @@ make
 
 This single command performs all setup automatically:
 
-1. **Cleans previous devnet data** - Removes any old network state
+1. **Cleans previous testnet data** - Removes any old network state
 2. **Builds the project** - Compiles Solidity contracts and Rust binaries
-3. **Generates devnet configuration** - Creates network parameters for 3 nodes
+3. **Generates testnet configuration** - Creates network parameters for 3 nodes
 4. **Creates validator keys** - Generates private keys for each validator
 5. **Creates node directories** - Sets up `nodes/0/`, `nodes/1/`, `nodes/2/`
 6. **Extracts validator public keys** - Collects pubkeys into `nodes/validator_public_keys.txt`
@@ -125,6 +125,6 @@ make clean
 
 - All node data (`nodes/`)
 - Genesis file (`assets/genesis.json`)
-- Devnet config (`.testnet/`)
+- Testnet config (`.testnet/`)
 - Docker volumes (Reth databases)
 - Prometheus/Grafana data
diff --git a/docs/operational-docs/src/local-devnet/index.md b/docs/operational-docs/src/local-devnet/index.md
@@ -1,18 +1,18 @@
-# Local Devnet
+# Deploy Local Testnet
 
-This guide explains how to create and manage a local Emerald devnet.
+This guide explains how to create and manage a local Emerald testnet.
 The goal is to enable developers and testers to run an Emerald network on their machine for development, testing, and experimentation.
 
-A local devnet is a fully functional blockchain network running entirely on your computer. It provides:
+A local testnet is a fully functional blockchain network running entirely on your computer. It provides:
 
 - **Fast iteration**: Test smart contracts and applications without waiting for public networks
 - **Complete control**: Add/remove validators, modify network parameters, reset state anytime
 - **No cost**: No real tokens required for testing
 - **Privacy**: All transactions and data stay on your machine
 
-**Local Devnets vs Production Networks**
+**Local Testnet vs Production Network**
 
-| Feature | Local Devnet | Production Network |
+| Feature | Local Testnet | Production Network |
 |---------|---------------|-------------------|
 | Validators | All on your machine | Distributed across organizations |
 | Data persistence | Can reset anytime | Permanent blockchain history |
diff --git a/docs/operational-docs/src/local-devnet/interactions.md b/docs/operational-docs/src/local-devnet/interactions.md
@@ -1,6 +1,6 @@
-# Interacting With the Devnet
+# Interacting With the Testnet
 
-Once your local Emerald devnet is running, you can interact with it like any Ethereum network.
+Once your local Emerald testnet is running, you can interact with it like any Ethereum network.
 
 ## Using `curl` (JSON-RPC)
 
diff --git a/docs/operational-docs/src/local-devnet/membership-changes.md b/docs/operational-docs/src/local-devnet/membership-changes.md
@@ -19,13 +19,13 @@ Emerald's PoA tooling provides support for the following use cases.
 
 ## Prerequisites
 
-- Running devnet (see [Create a New Network](create-network.md))
+- Running testnet (see [Create a New Network](create-network.md))
 - RPC endpoint (default `http://127.0.0.1:8545`)
 - Contract owner key (see below for default test key)
 
-## Devnet Accounts
+## Testnet Accounts
 
-The local devnet uses a well-known test mnemonic for pre-funded accounts:
+The local testnet uses a well-known test mnemonic for pre-funded accounts:
 
 **Mnemonic**: `test test test test test test test test test test test junk`
 
diff --git a/docs/operational-docs/src/local-devnet/workflows.md b/docs/operational-docs/src/local-devnet/workflows.md
@@ -1,6 +1,6 @@
 # Common Workflows
 
-Here are some typical workflows for using the local devnet during development.
+Here are some typical workflows for using the local testnet during development.
 
 ## Smart Contract Deployment
 
diff --git a/docs/operational-docs/src/production-network/index.md b/docs/operational-docs/src/production-network/index.md
@@ -1,4 +1,4 @@
-# Production Network
+# Launch Production Network
 
 This guide is designed for network coordinator (companies, foundations, or organizations) that want to launch a new production-grade Emerald network.
 
@@ -12,7 +12,7 @@ Network coordinators are typically responsible for:
 Starting a new network involves coordinating with external validator operators:
 
 1. **Recruit Validators**: Identify organizations or individuals who will run validator nodes on the network
-2. **Distribute Instructions**: Share the key generation steps with each validator (see [Creating Network Genesis]() section below)
+2. **Distribute Instructions**: Share the key generation steps with each validator (see [Creating Network Genesis](genesis.md#creating-network-genesis))
 3. **Collect Public Keys**: Each validator generates their private keys securely on their own infrastructure and provides the coordinate with their **public key only**
 4. **Generate Genesis Files**: Use the collected public keys to create the network genesis files
 5. **Distribute Genesis Files**: Share the genesis files with all validators so they can start their nodes
