# 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/`, 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.