Add architecture map and contribution guidance for REALITY fork

ARCHITECTURE.md

@@ -0,0 +1,45 @@
+# REALITY repository map and improvement ideas
+
+This fork of Go's `crypto/tls` implements the REALITY handshake profile while keeping the upstream TLS surface (`tls.Config`, `tls.Conn`, QUIC hooks, certificate handling). Use this document as a quick map of the codebase and a list of high-impact contribution ideas.
+
+## Layout at a glance
+
+- **TLS entrypoints and record layer:** `tls.go`, `conn.go`, `record_detect.go`, `cipher_suites.go`, `common*.go`, `defaults*.go`
+- **Handshake state machines:** `handshake_client*.go`, `handshake_server*.go`, `handshake_messages.go`
+- **Key schedule & crypto helpers:** `key_agreement.go`, `key_schedule.go`, `prf.go`, plus subpackages `tls13/` (TLS 1.3 key schedule) and `tls12/` (TLS 1.2 PRF/EMS)
+- **REALITY/ECH plumbing:** `ech.go` drives Encrypted ClientHello/REALITY flows and depends on `hpke/` (RFC 9180 primitives)
+- **Auth, certs, and tickets:** `auth.go`, `generate_cert.go`, `ticket.go`, `cache.go`
+- **QUIC integration:** `quic.go` exposes the QUIC-specific handshake hooks
+- **FIPS controls:** `fips140tls/` toggles FIPS-only behavior
+
+## Relationships (Mermaid)
+
+```mermaid
+graph TD
+    App[Consumers (Xray-core, proxies, QUIC)] --> TLSAPI[tls.Conn API / tls.Config]
+    TLSAPI --> Defaults[defaults*.go & cipher_suites.go]
+    TLSAPI --> Record[conn.go & record_detect.go]
+    TLSAPI --> Auth[auth.go, generate_cert.go, ticket.go, cache.go]
+    TLSAPI --> Handshake[Handshake engines]
+
+    Handshake --> ClientHS[handshake_client*.go]
+    Handshake --> ServerHS[handshake_server*.go]
+    Handshake --> Messages[handshake_messages.go]
+    Handshake --> ECH[ech.go / REALITY]
+    Handshake --> KeySched[key_schedule.go]
+
+    KeySched --> TLS13[tls13/]
+    KeySched --> TLS12[tls12/]
+    ECH --> HPKE[hpke/]
+    Record --> Quic[quic.go]
+    Defaults --> FIPS[fips140tls/]
+```
+
+## Where to practice and help the project
+
+- **Module hygiene:** In this checkout `go test ./...` asks for `go mod tidy`; align `go.mod`/`go.sum` and add a pre-commit/CI check to keep dependencies in sync.
+- **Handshake coverage:** add unit and integration tests for REALITY/ECH paths (ClientHello encoding, certificate spoofing rules, key schedule derivations) and QUIC handshake shims.
+- **Fuzzing and robustness:** fuzz parsers for handshake messages, HPKE contexts, and record detection to harden against crafted traffic.
+- **Interop matrix:** Document supported cipher suites, fingerprints, and minimum client versions; add fixtures that mirror `Xray-core` expectations.
+- **Observability:** optional debug/trace hooks for REALITY negotiations (timings, selected SNI/short IDs) gated behind a build tag or config flag.
+- **Performance baselines:** benches for handshake/resumption latency and HPKE operations to track regressions when tuning crypto or defaults.

README.md

@@ -5,6 +5,8 @@
 Server side implementation of REALITY protocol, a fork of package tls in latest [Go](https://github.com/golang/go/tree/master/src/crypto/tls).
 For client side, please follow https://github.com/XTLS/Xray-core/blob/main/transport/internet/reality/reality.go.  
 
+For a code map, relationships, and contribution ideas, see [ARCHITECTURE.md](ARCHITECTURE.md).
+
 TODO List: TODO
 
 ## Donation & NFTs