Navigating go-ethereum: Architecture Overview and Directory Map

Ethereum's execution layer has a reference implementation, and it's written in Go. The go-ethereum repository — universally called "Geth" — is over a decade old, spans roughly a million lines of code, and remains the most widely deployed Ethereum client. If you want to understand how Ethereum actually works at the implementation level, this is the codebase to read. But walking into a million-line project without a map is a recipe for frustration. This article gives you that map.

We'll cover what Geth is and isn't, how its directory tree organizes concerns, the clean split between library and application code, and the interface-driven design philosophy that keeps a codebase this large manageable. By the end, you'll know exactly where to look for any subsystem you want to explore.

What Is Geth and Where Does It Fit?

Geth is the official Go implementation of the Ethereum execution layer protocol. Since The Merge (September 2022), Ethereum runs on a two-client architecture: a consensus layer client (like Prysm, Lighthouse, or Teku) handles proof-of-stake consensus, while an execution layer client like Geth handles transaction execution, state management, and the EVM.

flowchart TD
    CL["Consensus Layer Client<br/>(Prysm, Lighthouse, etc.)"]
    EL["Execution Layer Client<br/>(Geth)"]
    CL -->|Engine API| EL
    EL -->|State, Blocks, Receipts| DB[(LevelDB / Pebble)]
    EL <-->|devp2p| PEERS["Peer Nodes"]
    CL <-->|libp2p| CL_PEERS["CL Peers"]

The consensus layer tells Geth which blocks to produce and when — Geth handles the how. This communication happens through the Engine API, a set of authenticated JSON-RPC endpoints that we'll cover in detail in Part 6.

Critically, go-ethereum is both a runnable client (the geth binary) and a reusable Go library. External projects routinely import github.com/ethereum/go-ethereum to access its types, RLP encoding, cryptography, and even embed full blockchain functionality. The module declaration in go.mod shows this is a single Go module targeting Go 1.24.

Directory Structure: The Complete Package Map

The repository follows Go conventions strictly — every directory is a package, and dependencies flow downward from high-level application code to low-level primitives. Here's the complete map:

Directory	Domain	Description
cmd/	Application	CLI entry points: geth, clef, evm, devp2p, abigen, rlpdump, etc.
node/	Infrastructure	Protocol-agnostic service container — manages P2P, RPC, databases, lifecycles
eth/	Protocol	Ethereum protocol service — wires blockchain, tx pool, handler, miner, APIs
core/	Blockchain	Block processing, state transitions, genesis, tx pool, types
core/vm/	Execution	EVM implementation — interpreter, jump tables, opcodes, precompiles
core/state/	State	StateDB — in-memory world state cache with journal-based snapshots
core/types/	Data	Canonical types: Block, Transaction, Receipt, Header, Log
core/txpool/	Mempool	Transaction pool aggregator with SubPool interface
consensus/	Consensus	Pluggable consensus engines (beacon, clique, ethash)
p2p/	Networking	devp2p stack — encrypted connections, peer management, discovery
trie/	Data Structure	Merkle Patricia Trie implementation
triedb/	Trie Storage	Trie database with hash-based and path-based backends
ethdb/	Storage	Database interface abstractions — backed by LevelDB or Pebble
rpc/	API Framework	JSON-RPC server with reflection-based method registration
internal/ethapi/	API Handlers	Implementation of eth_*, debug_*, txpool_* RPC methods
accounts/	Key Management	Account management, keystore, hardware wallet support
params/	Configuration	Chain config, fork schedule, gas costs, network definitions
miner/	Block Building	Post-Merge payload builder for Engine API
crypto/	Cryptography	secp256k1, SHA3, BLS, KZG support
rlp/	Serialization	Recursive Length Prefix encoding/decoding
common/	Utilities	Shared types (Hash, Address), math helpers, caching
log/	Logging	Structured logging framework
metrics/	Observability	Metrics collection and reporting
event/	Pub/Sub	Internal event subscription system

flowchart TD
    CMD["cmd/geth"] --> ETH["eth/"]
    CMD --> NODE["node/"]
    ETH --> CORE["core/"]
    ETH --> CONSENSUS["consensus/"]
    ETH --> MINER["miner/"]
    CORE --> VM["core/vm/"]
    CORE --> STATE["core/state/"]
    CORE --> TYPES["core/types/"]
    CORE --> TXPOOL["core/txpool/"]
    STATE --> TRIE["trie/"]
    TRIE --> TRIEDB["triedb/"]
    TRIEDB --> ETHDB["ethdb/"]
    NODE --> P2P["p2p/"]
    NODE --> RPC["rpc/"]
    ETH --> ETHAPI["internal/ethapi/"]

Tip: When exploring an unfamiliar subsystem, start from the cmd/ layer and trace downward. The dependency flow is strictly cmd/ → eth/ → core/ → trie/ → ethdb/. You'll never see a lower-level package importing a higher-level one.

Library vs. Application: The cmd/ Split

One of Geth's most important architectural decisions is the clean separation between application code in cmd/ and library code everywhere else. The Makefile reveals all the executables:

flowchart LR
    subgraph "cmd/ — Application Layer"
        GETH["geth<br/>Full node client"]
        EVM["evm<br/>Standalone EVM"]
        DEVP2P["devp2p<br/>Protocol testing"]
        CLEF["clef<br/>External signer"]
        ABIGEN["abigen<br/>ABI bindings"]
        RLPDUMP["rlpdump<br/>RLP inspector"]
    end
    subgraph "Library Packages"
        LIB["eth/, core/, p2p/, trie/,<br/>rpc/, consensus/, ..."]
    end
    GETH --> LIB
    EVM --> LIB
    DEVP2P --> LIB

This split means that third-party Go projects can import "github.com/ethereum/go-ethereum" and use any library package without pulling in CLI concerns. The ethclient package, for example, provides a typed Go client that implements the root-level interfaces — something only possible because the library boundary is rigorously maintained.

The main Geth binary is defined in cmd/geth/main.go, where main() is just five lines that call app.Run(os.Args). All the real work happens in library packages.

Interface-Driven Design Philosophy

What keeps a million-line codebase from becoming an unmaintainable monolith? Interfaces. Go-ethereum relies on a consistent pattern: define narrow interfaces at package boundaries, implement them in concrete types, and never depend on concrete types across packages.

Here are the key abstraction boundaries:

classDiagram
    class Lifecycle {
        <<interface>>
        +Start() error
        +Stop() error
    }
    class Engine {
        <<interface>>
        +Author(header) address
        +VerifyHeader(chain, header) error
        +VerifyHeaders(chain, headers) chan
        +Prepare(chain, header) error
        +Finalize(chain, header, state, body)
        +Seal(chain, block, results, stop) error
    }
    class Database {
        <<interface>>
        KeyValueStore
        AncientStore
    }
    class SubPool {
        <<interface>>
        +Filter(tx) bool
        +Init(gasTip, head, reserver) error
        +Add(txs, sync) errors
        +Pending(filter) map
    }
    class Backend {
        <<interface>>
        +HeaderByNumber(ctx, number)
        +StateAndHeaderByNumber(ctx, number)
        +SendTx(ctx, tx) error
        +ChainConfig() ChainConfig
    }

The Lifecycle interface is perhaps the most elegant — just Start() and Stop(). Any service that needs managed start/stop behavior implements these two methods and registers with the Node container. The Ethereum service, the local transaction tracker, and other components all use this same minimal contract.

The consensus.Engine interface lets the same core execution pipeline work with proof-of-stake (beacon), proof-of-authority (clique), or even the legacy proof-of-work (ethash) — though Geth now requires all networks to have passed The Merge.

The ethdb.Database interface composes KeyValueStore and AncientStore, allowing LevelDB, Pebble, or in-memory backends to be swapped seamlessly — critical for testing.

The Root-Level Public API

At the very root of the repository sits interfaces.go, which defines the stable public Go API for external consumers. This is the ethereum package — the one that ethclient implements.

The interfaces defined here include:

• ChainReader — access blocks and headers by hash or number
• TransactionReader — retrieve past transactions and receipts
• ChainStateReader — query balances, storage, code, nonces
• ContractCaller — execute read-only contract calls
• LogFilterer — query and subscribe to event logs
• TransactionSender — submit signed transactions
• GasPricer / GasPricer1559 — gas price recommendations
• Subscription — the universal event subscription contract

These interfaces are intentionally narrow and stable. They represent the public API contract that Geth maintains for external Go consumers. Breaking changes here would affect every downstream project that imports go-ethereum.

Tip: If you're building a Go application that interacts with Ethereum, program against the interfaces in interfaces.go — not against concrete Geth types. This gives you the flexibility to swap backends (e.g., from ethclient to a mock in tests).

Build System and Orientation Tips

Geth uses a two-tier build system. The Makefile provides the developer-facing interface — make geth, make all, make test. Under the hood, most targets delegate to build/ci.go, a Go-based build orchestrator that handles cross-compilation, testing, packaging, and CI tasks.

flowchart LR
    DEV["Developer"] -->|make geth| MK["Makefile"]
    MK -->|go run build/ci.go install| CI["build/ci.go"]
    CI -->|go build| BIN["build/bin/geth"]
    DEV -->|make test| MK
    MK -->|go run build/ci.go test| CI
    CI -->|go test| TESTS["Test Suite"]

This pattern — using a Go program as the build orchestrator — ensures consistent behavior across Linux, macOS, and Windows without requiring shell-specific scripts.

For navigating the codebase day-to-day, keep these heuristics in mind:

1. Types live in core/types/ — Block, Transaction, Receipt, Header, Log
2. Configuration lives in params/ — fork schedules, gas costs, chain IDs
3. RPC handlers live in internal/ethapi/ — every eth_* method maps to a Go method here
4. The EVM lives in core/vm/ — opcodes, gas tables, interpreter loop
5. State management is core/state/ → trie/ → triedb/ → ethdb/ — four layers deep

Now that you have the map, the next article traces the journey from main() to a running node — following the boot sequence through CLI parsing, Node construction, and service initialization.