readme, claude mds update info

readme.md

@@ -10,24 +10,50 @@ A FastAPI project combining Excel and digital data ("The Great Excel project tha
 - PostgreSQL (asyncpg, psycopg2)
 - Pydantic 2 / Pydantic Settings
 - Poetry — dependency management
+- Redis — caching, rate limiting, token revocation
+- RabbitMQ (aio-pika) — background email workers
+- Jinja2 — HTML email templates
 - Docker, Ansible — deployment
 
 ## Architecture
 
 ```
 src/
+├── cache/       # Redis client, rate limiting
+├── daemons/     # background worker entrypoints (BaseDaemon, registry)
 ├── database/    # DB CRUD operations
 ├── errors/      # HTTP errors
-├── logging/     # logging middleware
+├── logging/     # queue-based logging infra + HTTP middleware
+├── messaging/   # RabbitMQ client, producers, consumers, topology
 ├── migrations/  # Alembic migrations
-├── models/      # Pydantic and SQLAlchemy models, configs
+├── models/      # Pydantic and SQLAlchemy models, configs, RabbitMQ topology
 ├── reports/     # reports
-├── service/     # business logic (auth, users_crud)
+├── service/     # business logic (auth, users_crud, email sending)
 └── web/         # routes (protected_routes)
 ```
 
 Layers are connected top to bottom: `web → service → database → models`.
 
+## Background workers (RabbitMQ)
+
+Email sending (welcome / password-reset) runs as separate daemon processes,
+decoupled from the web API via a RabbitMQ topic exchange:
+
+```
+main.py / daemon_run.py → apply_topology() → RabbitMQ ("email" exchange)
+                                                   ├── queue_welcome_email → WelcomeEmailConsumer
+                                                   └── queue_reset_email  → ResetEmailConsumer
+```
+
+Each queue has a matching dead-letter queue for messages that fail
+permanently (bad data, non-retryable errors) instead of retrying forever.
+Run a worker locally with:
+
+```bash
+python daemon_run.py welcome_email   # single daemon
+python daemon_run.py --all           # all daemons enabled in configs/daemons.json
+```
+
 ## Authentication
 
 - JWT access + refresh tokens
@@ -46,8 +72,42 @@ tests/
 
 Uses pytest, pytest-asyncio, pytest-cov, pytest-mock, allure-pytest.
 
+### Allure report
+
+`make allure` needs the Allure **command-line tool** (Java-based, not a pip
+package) — `allure-pytest` only writes raw result files, the CLI turns them
+into an HTML report.
+
+1. Download Allure **2.44.0** from
+   [github.com/allure-framework/allure2/releases](https://github.com/allure-framework/allure2/releases).
+2. Extract it into `.venv/allure-2.44.0/` so that `.venv/allure-2.44.0/bin/allure`
+   exists — this matches the `ALLURE` variable already set in `makefile`.
+3. If you install it somewhere else (or on Windows), update the `ALLURE`
+   variable at the top of `makefile` to point to your actual `allure`
+   binary path — the Windows path is already there, commented out.
+
+```bash
+make test     # runs pytest, writes results to tests/allure-results/reports
+make allure   # builds tests/allure-results/html/index.html from those results
+```
+
 ## Installation
 
+Requires Poetry itself to be installed first (it's a global tool, not a
+project dependency). Recommended via [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install poetry
+```
+
+or via the official installer:
+
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+Then install the project dependencies:
+
 ```bash
 poetry install
 ```