62 lines
3.3 KiB
Markdown
62 lines
3.3 KiB
Markdown
# 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.
|