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