Add developer documentation

2026-05-15 13:59:30 -03:00
commit 0ce972a361
5 changed files with 283 additions and 0 deletions
@@ -0,0 +1,61 @@
+# Repository Structure
+
+The repository contains a FastAPI application for monitoring DMARC aggregate reports. The orchestration context names the repository DMARC Watch; the implemented application title and many runtime names currently use `DMARC Sentinel`.
+
+## Top-Level Files
+
+- `README.md`: current user-facing setup and operational notes.
+- `requirements.txt`: Python runtime and test dependencies.
+- `pytest.ini`: adds the repository root to `pythonpath`.
+- `Dockerfile`: Python 3.12 image that installs requirements, copies `app/` and `config/config.example.yml`, creates runtime directories, and starts Uvicorn.
+- `docker-compose.yml`: builds the app service, mounts `config/` read-only, mounts `data/` and `logs/`, publishes port `8000`, and attaches to the external `npm_proxy` Docker network.
+- `config/config.example.yml`: host-controlled runtime configuration template.
+- `.env.example`: environment variable template for IMAP, dashboard auth, homepage token, OpenAI, and SMTP settings.
+- `dmarc-sentinel-codex-implementation-spec.md`: implementation specification document present in the repository.
+
+## Application Package
+
+`app/` is the main Python package.
+
+- `main.py`: FastAPI app, startup, HTML routes, JSON routes, and admin endpoints.
+- `config.py`: settings models and configuration loading.
+- `db.py`: SQLAlchemy engine, session helpers, table initialization, and health check.
+- `models.py`: SQLAlchemy ORM models.
+- `message_processor.py`: IMAP message scanning, report import, analysis, message status updates, and processing summaries.
+- `imap_client.py`: IMAP connection, UID search/fetch, mark-seen, and move operations.
+- `attachment_extractor.py`: XML, gzip, and ZIP attachment extraction.
+- `dmarc_parser.py`: DMARC aggregate XML parser.
+- `known_senders.py`: deterministic sender classification.
+- `analyzer.py`: deterministic alert creation and update logic.
+- `alerts.py`: SMTP alert and digest delivery.
+- `llm.py`: OpenAI JSON calls and fallback summary/explanation outputs.
+- `scheduler.py`: polling, daily aggregation, and weekly summary jobs.
+- `homepage.py`: homepage widget and domain summary payload builders.
+- `schemas.py`: Pydantic request models for admin processing endpoints.
+- `auth.py`: dashboard Basic Auth and homepage bearer token dependencies.
+- `smoke_data.py`: helper for seeding smoke data.
+- `templates/`: Jinja2 templates for the server-rendered dashboard.
+- `static/app.css`: dashboard styles.
+
+## Tests and Fixtures
+
+`tests/` contains pytest coverage for current behavior:
+
+- parser behavior: `tests/test_parser.py`;
+- attachment extraction and message attachment detection: `tests/test_attachment_extractor.py`;
+- duplicate storage behavior: `tests/test_storage.py`;
+- alert analysis behavior: `tests/test_analyzer.py`;
+- homepage summary behavior: `tests/test_homepage.py`;
+- LLM fallback validation behavior: `tests/test_llm.py`;
+- test environment defaults: `tests/conftest.py`;
+- sample config and XML fixtures: `tests/fixtures/`.
+
+## Design References
+
+`design/` contains mockups and design reference files. These are reference artifacts for UI work, not runtime code.
+
+## Runtime Output Paths
+
+- `data/` is used for SQLite database files.
+- `logs/` is used for `logs/dmarc-sentinel.log`.
+- `.gitignore` excludes SQLite databases, log files, bytecode, virtual environments, and pytest cache output.