documentation md files

documentation/backend/README.md

@@ -0,0 +1,39 @@
+# Backend documentation
+
+This directory documents the Python service in `backend/src`. It is written for
+developers and operators of the inline MITM test system. The source code remains
+the implementation authority; this documentation records the externally useful
+contracts, lifecycle, Linux integration, and data semantics that are easy to lose
+when reading individual modules.
+
+## Reading order
+
+1. [Architecture](architecture.md) explains the process, responsibilities, and
+   lifecycle.
+2. [Sniffing modes](sniffing.md) gives the complete technical behavior and
+   implications of AF_PACKET and TC/eBPF capture.
+3. [Capture pipeline](capture-pipeline.md) follows a packet from observation to
+   persistence and realtime delivery.
+4. [HTTP and WebSocket API](api.md) lists every router mounted by the application.
+5. [Data and analysis](data-and-analysis.md) describes the packet record, database
+   operations, and derived analysis views.
+6. [Host integration](host-integration.md) covers network, eBPF, nftables, tshark,
+   and systemd side effects.
+7. [Configuration and deployment](configuration.md) records dependencies and all
+   `BACKEND_*` settings.
+8. [Source reference](source-reference.md) documents every backend source module,
+   including modules not mounted by the current application.
+
+## Scope and conventions
+
+All HTTP paths below include the FastAPI `root_path`, `/api`. The interactive
+schema is available at `/api/docs`, the alternative reference UI at `/api/redoc`,
+and the machine-readable contract at `/api/openapi.json`.
+
+"Live" means a router is included by `src.main`. `nft_api.py` and
+`nftables_api.py` contain independent routers but are not included by the current
+entrypoint; they are documented as available-but-unmounted implementation paths.
+
+Packet capture, firewall changes, bridge changes, and script deployment alter the
+host system. They must be used only in a controlled environment with explicit
+operator authorization.