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.

3.3 KiB Raw Blame History