Initial curated CertScope source from fe2bbe3ca5c98bf64be26a09c6c58ee805a7f87e

docs/ARCHITECTURE.md

@@ -0,0 +1,45 @@
+# Architecture
+
+```text
+Browser -> /api/inspect -> hostname normalization and policy
+                         -> DNS A/AAAA + mail-record collectors
+                         -> validate every resolved public address
+                         -> TLS and HTTP(S) collectors
+                              -> direct IP connection with hostname SNI/Host
+                              -> bounded, revalidated redirect hops
+                         -> normalized evidence + collector metadata
+                         -> deterministic diagnostics
+                         -> category scores + equal-weighted overall score
+                         -> dashboard, JSON and Markdown exports
+```
+
+## Boundaries
+
+All probing is server-side. The API accepts a hostname rather than an arbitrary URL. `policy.ts` normalizes lower-case DNS/IDN names and rejects URL/IP input; it validates every A/AAAA answer as public unicast before a connection. Collectors receive validated candidate addresses and connect directly to those addresses while retaining the normalized hostname for TLS SNI and the HTTP Host header.
+
+DNS runs the six required record queries under one four-second aggregate deadline. A or AAAA can be absent or fail independently; one working family is retained as partial evidence. No usable safe address is a hard resolution error. HTTP and TLS try multiple validated candidates with bounded attempts and total budgets. HTTP has a 15-second budget, TLS an eight-second budget, and DNS a four-second budget. HTTP response bodies are destroyed after headers, and TLS sockets are destroyed after each result or failure.
+
+Each redirect is parsed as a URL, restricted to HTTP(S) and default ports, normalized into a visited set, checked for loops, and re-resolved before its direct connection. Policy-rejected targets become `http.redirect_blocked` evidence without a request being made. HTTPS-to-HTTP redirects are stopped before the downgraded request and become `http.https_downgrade` evidence. Redirect depth is capped at three.
+
+Redirect `Location` values are retained in raw form only while the next target is validated; returned evidence removes URL userinfo so credentials cannot appear in reports. Certificate validity dates are checked for parseability and chronological order, and MX answer shape is checked before mail posture findings are derived.
+
+## Evidence and scoring
+
+Collectors return normalized evidence and `_meta` status (`ok`, `partial` or `failed`) with safe probe errors. Diagnostics only score observations that exist; collector incompleteness is shown separately. Category scores are clamped after their own negative findings, then the overall score is:
+
+```text
+DNS = clamp(100 + DNS finding impacts, 0, 100)
+TLS = clamp(100 + TLS finding impacts, 0, 100)
+HTTP = clamp(100 + HTTP finding impacts, 0, 100)
+overall = round((DNS + TLS + HTTP) / 3)
+```
+
+Thus an HTTP deduction is not subtracted a second time from the global score. Stable finding IDs, deterministic severity/impact ordering and evidence pointers keep reports reproducible.
+
+## Presentation and runtime
+
+`app/page.tsx` owns the landing, request state, validated active report, demo and re-inspection states. It promotes a demo/live report only after a structurally valid successful response; an error preserves the prior report and provenance. Its capability, public-boundary and demo-preview content is static product explanation or derived from the deterministic fixture; it does not imply scan history or hidden services. `app/report-view.tsx` orchestrates report-local state, contextual navigation and the accessible diagnostic drawer. `app/components/report/` contains focused actions, shared display utilities and structured DNS/TLS/HTTP evidence views; none performs probes or reimplements header policy. `app/api/health` is a side-effect-free runtime check exposing status, package version and the build revision.
+
+Header parsing produces typed control posture for HSTS, CSP, `nosniff`, Referrer-Policy and frame protection. Diagnostics and the HTTP evidence view consume that same model, so the aggregate is derived from evaluated controls rather than display text. Missing evidence from a partial collector is represented as unavailable rather than a negative observation.
+
+The production image uses Next.js standalone output. The local start helper stages generated static assets into `.next/standalone`; Docker copies those assets directly into the final non-root runtime image. `package.json` is the version source for the application and health response; deployment supplies the same release version and exact commit as image build metadata.