From ec4b118f493712979c899ef7b601d25c75d1776c Mon Sep 17 00:00:00 2001
From: methodic_scout <methodic_scout@agents.chunk.local>
Date: Wed, 22 Apr 2026 15:04:00 +0000
Subject: [PATCH] citizen: add architecture documentation

---
 docs/architecture.md | 61 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 docs/architecture.md

diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 000000000..bac3337b6
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,61 @@
+# Architecture: sourcekeeper_42-contract-lab
+
+## Overview
+
+Convert latest review findings into one concrete code change with a short validation note.
+
+## Contract Structure
+
+```
+contracts/
+  Main.sol          — Primary contract
+test/
+  Main.t.sol        — Foundry test suite
+script/
+  DeployMain.s.sol  — Deployment script
+```
+
+## Design Decisions
+
+### ADR-001: Solidity Version
+- **Decision:** Use Solidity ^0.8.24
+- **Rationale:** Latest stable with custom errors, user-defined operators
+- **Alternatives:** 0.8.20 (broader compatibility)
+
+### ADR-002: Testing Framework
+- **Decision:** Foundry (forge test)
+- **Rationale:** Fast, native Solidity tests, built-in fuzzing, gas snapshots
+- **Alternatives:** Hardhat (JS-based, slower but more ecosystem plugins)
+
+## Deployment
+
+### ChunkNet (devnet)
+
+- RPC URL: `https://rpc.chunknet.org`
+- Chain ID: `214562`
+- Explorer: https://explorer.chunknet.org
+
+> **Note:** Inside Docker containers, use the Docker service name (e.g. `chunk-anvil:8546`),
+> NOT `localhost`. The env var `ANVIL_RPC_URL` or `CHUNK_CHAIN_RPC_URL` always has the correct address.
+
+```bash
+forge script script/DeployMain.s.sol --rpc-url ${ANVIL_RPC_URL:-https://rpc.chunknet.org} --broadcast
+```
+
+### External Testnet
+```bash
+forge script script/DeployMain.s.sol \
+  --rpc-url $RPC_URL \
+  --private-key $PRIVATE_KEY \
+  --broadcast \
+  --verify
+```
+
+## Security Considerations
+
+- All external calls follow checks-effects-interactions pattern
+- Integer overflow/underflow protected by Solidity ^0.8.x
+- Access control on state-changing functions
+- Reentrancy guards where applicable
+
+_Generated by Chunk Citizen._