docs: add network architecture overview

[dair7]

Pull Request

Description

Adds docs/network-architecture-overview.md covering node runtime responsibilities,
peer/protocol modules, consensus, and config/diagnostics flow, per issue #302.

Includes a Build Status section at the top documenting that network-node currently
fails to compile: 129 errors per the committed cargo-check-full.log, three of which were
spot-checked and confirmed still live against the current tree (enhanced_server.rs:601,
:665, :682). A fourth failure in the binary target is documented that the log does not
cover — main.rs calls four telemetry:: functions that do not exist. CI never catches any
of this because no workflow builds or-node` package; the only

---

Pull Request

Description

Adds docs/network-architecture-overview.md covering node runtime responsibilities,
peer/protocol modules, consensus, and config/diagnostics flow, per issue #302.

Includes a Build Status section aetwork-nodecurrently fails to compile: 129 errors per the committedcargo-check-full.log, three of which were spot-checked and confirmed still livenhanced_server.rs:601,
:665, :682). A fourth failure in the binary target is documented that the log does not
cover — main.rs calls four telemetxist. CI never catches any of this because no workflow builds or tests the axionvera-network-nodepackage; the only Rust command in CI isnpm run build:onvera-vault-contract`.

Each claim is anchored to file:line and marked with one of four states: Implemented /
Documented but unverified / Present bfindings:

• consensus.rs is a real 605-line quorum-voting engine that is never instantiated —
  ConsensusEngine appears nowhere outside its own definition. Agreement comes from
  Stellar/Soroban, not from this module.
• The peer layer has a working Kademl gRPC P2PService, but no
  peer transport: the crate opens no P2P socket, and bootstrap, handle_ping, and
  sync_chain are stubs.
• 13 crates under contracts/ are in neither the workspace members list nor any member's
  dependency graph, so nothing compils/config, a complete 303-line Soroban contract. Three are additionally broken at the manifest level (contracts/metrics/Cargo.toml` is a 0-byte file).

Cross-checked against ARCHITECTURE.md and docs/architecture.md, correcting outdated
claims: tokio-postgres vs the real sqlx driver, bb8/deadpool pooling that is not a
dependency, a circuit-breaker thresho the default is 3, and the
requests_log/user_cache tables, neither of which exists. The document states plainly that
ARCHITECTURE.md is not wholesale aspirational — Axum, PostgreSQL, Redis, and circuit
breakers are all genuinely present.

Verified that all 78 relative links across both files resolve to existing files or
directories, plus 7 internal anchors broken.

No code files were modified. Only docs/network-architecture-overview.md (new) and
README.md (two links added).

Related Issues

Closes #302

Cleanup Checklist

• I have reviewed the Contributor Cleanup Checklist

  Note: the template links to docs/contributor/cleanup-checklist.md, which does not
  exist in this repository. Leaving u to have read a missing
  document. Worth a separate issue to either add the file or fix the template.

• Documentation is updated

Not applicable — this is a documentatges: module boundaries,
error handling, config value documentation, test coverage, and protocol-sensitive logic.

Type of Change

• Documentation update

Testing

• No breaking changes introduced

No code was changed, so no test run ie that
cargo test -p axionvera-network-node does not currently pass on main either, for the
reasons documented in the new Build Status section — this PR reports that state, it does not
cause it.

Code Quality

No Rust or TypeScript was modified, so cargo fmt and cargo clippy are not applicable
here. For the record, cargo clippy -tly pass on main`.

• No commented-out code

Documentation

• README updated — the overview is linked from both "Start Here" and "More Documentation"
• Architecture docs updated — addRCHITECTURE.mdanddocs/architecture.md` were deliberately left untouched, with their inaccuracies
  documented in the new file instead of edited in place

Notes for Reviewers

The Build Status section is the part eports that the node does
not build, based on a cargo check log committed to the repo that was generated on another
machine at an unrecorded commit. Because a stale log proves nothing on its own, three of its
errors were re-verified by hand again cited with line numbers.
If you believe the node does build, that section is where the disagreement is, and it should
be easy to settle.

Two pre-existing issues were found but deliberately not fixed here, to keep this PR
documentation-only:

• docs/architecture.md lines 12, 13, 14, 15, and 48 contain absolute
  file:///Users/boufdaddy/… paths from a contributor's local machine. Line 73 points at
  ../../ARCHITECTURE.md, one level too high. The new document uses correct relative paths
  and lists the corrections.
• docs/contributor/cleanup-checklist.md, referenced by this PR template, is missing.

One thing that is explicitly not p: ARCHITECTURE.md renders
em-dashes as â€" in some terminals. The file is valid UTF-8 with no BOM and correctly
encoded U+2014 characters — verified at the byte level. That is a console code page issue,
not a file issue, and nothing should