feat: implement mqtt ingestion, parsing, and archive pipeline

backend/README.md

@@ -170,3 +170,40 @@ The email templates are in `./backend/app/email-templates/`. Here, there are two
 Before continuing, ensure you have the [MJML extension](https://github.com/mjmlio/vscode-mjml) installed in your VS Code.
 
 Once you have the MJML extension installed, you can create a new email template in the `src` directory. After creating the new email template and with the `.mjml` file open in your editor, open the command palette with `Ctrl+Shift+P` and search for `MJML: Export to HTML`. This will convert the `.mjml` file to a `.html` file and now you can save it in the build directory.
+
+## MQTT Ingestion Pipeline
+
+This project includes a two-stage MQTT pipeline:
+
+- `mqtt-ingestor` subscribes to `terminal/{device_id}/raw` and stores payload bytes losslessly in `terminal_message_raw`.
+- `mqtt-parser-worker` consumes pending rows and writes parsed events/state.
+
+### Run locally with Docker Compose
+
+```console
+$ docker compose up -d db backend mqtt-ingestor mqtt-parser-worker
+```
+
+### Unit tests for MQTT modules
+
+The existing `tests/conftest.py` expects a PostgreSQL connection. For parser/repository unit tests that run with in-memory SQLite fixtures, use:
+
+```console
+$ cd backend
+$ PYTHONPATH=. ../.venv/bin/pytest tests/mqtt --confcutdir=tests/mqtt -q
+```
+
+### Verify end-to-end ingestion quickly
+
+1. Start services (`db`, `backend`, `mqtt-ingestor`, `mqtt-parser-worker`).
+2. Publish a sample message to `terminal/device-001/raw`.
+3. Query PostgreSQL tables:
+   - `terminal_message_raw`
+   - `terminal_observation_event`
+   - `terminal_device_state`
+
+### Archive run (manual trigger)
+
+```console
+$ docker compose run --rm mqtt-parser-worker python -m app.mqtt.archive_job
+```