Initial import: n2usenet HTTPS/Nym Usenet gateway

1 files changed, 50 insertions, 0 deletions

diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..501903e
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,50 @@
+# N2Usenet Architecture
+
+## Components
+
+- `cmd/n2usenet`: process entrypoint, lifecycle, HTTP server.
+- `cmd/n2u-check`: SMTP diagnostic helper for direct or SOCKS5-routed checks.
+- `internal/config`: environment-driven configuration.
+- `internal/nymclient`: optional managed `nym-socks5-client` lifecycle.
+- `internal/socks5`: minimal SOCKS5 dialer used for Nym transport.
+- `internal/smtpclient`: SMTP + STARTTLS sender over an injected dialer.
+- `internal/submit`: HTTP handlers, validation, message construction.
+- `internal/storage`: replay cache for Hashcash tokens.
+- `internal/assets/web`: embedded template and browser assets.
+
+## Privacy Boundary
+
+The HTTPS server necessarily receives browser connections. It should not persist
+source IPs, user agents, raw posts, or submitted identities. Operational logs
+must stay generic. Rate limiting uses an in-memory keyed hash of the source
+address and resets on process restart. Hashcash replay protection is also
+memory-only. The browser-side identity, signature inputs, and compose fields are
+kept only in tab memory and cleared after successful send.
+
+## Transport Boundary
+
+The app never dials `mail2news.tcpreset.net` directly when `N2U_NYM_ENABLED=true`.
+All SMTP traffic goes through `N2U_NYM_SOCKS`, normally provided by
+`nym-socks5-client`.
+
+The intended posting chain is:
+
+```text
+Browser -> HTTPS n2usenet.virebent.art
+N2Usenet -> Nym SOCKS5/requester
+Nym requester -> mail2news.tcpreset.net:25 SMTP with STARTTLS
+mail2news@mail2news.tcpreset.net -> Mail2News gateway
+Mail2News gateway -> news.tcpreset.net NNTP
+```
+
+## Deployment Boundary
+
+The current onion PHP app remains deployed under Onion Newsreader `/compose/`.
+This app is a separate HTTP service intended to be reverse-proxied by the
+public HTTPS frontend for `https://n2usenet.virebent.art`, Apache on `pietro`
+in the current production deployment.
+
+Current production split:
+
+- `victor` runs the dedicated Nym network requester.
+- `pietro` runs the public HTTPS app and the local `nym-socks5-client`.