citizen: add architecture documentation

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._