mail-cadence 0.1.1__tar.gz

mail_cadence-0.1.1/.gitignore

@@ -0,0 +1,110 @@
+# ==============================================================================
+# 1. Python Runtime & Build Artifacts
+# ==============================================================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Packaging and distribution artifacts (Hatchling / Wheel / PIP)
+build/
+dist/
+wheels/
+*.egg-info/
+.eggs/
+*.egg
+pip-wheel-metadata/
+
+# ==============================================================================
+# 2. Environment Configuration & Secrets (pydantic-settings)
+# ==============================================================================
+# Protect SMTP credentials (SMTP_USER, SMTP_PASSWORD) from leaking
+.env
+.env.*
+!.env.example
+!.env.template
+
+# ==============================================================================
+# 3. SQLite Databases (including PRAGMA journal_mode = WAL files)
+# ==============================================================================
+# Default project database (cli.py) and general SQLite files
+mail_cadence.db
+mail_cadence.db-shm
+mail_cadence.db-wal
+mail_cadence.db-journal
+
+*.db
+*.db-shm
+*.db-wal
+*.db-journal
+*.sqlite
+*.sqlite3
+*.sqlite3-shm
+*.sqlite3-wal
+
+# ==============================================================================
+# 4. Quality Gates, Testing & Static Analysis Caches
+# ==============================================================================
+# Pytest & Coverage (pytest-cov)
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Mypy & Ruff
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+
+# Other QA tools
+.tox/
+.nox/
+.cache/
+
+# ==============================================================================
+# 5. Logs & Local Working Files (XML import/export)
+# ==============================================================================
+*.log
+logs/
+tmp/
+temp/
+
+# Local XML dump files (when generated outside tests/ or examples/)
+*_export.xml
+local_*.xml
+
+# ==============================================================================
+# 6. IDEs, Editors & OS-specific Files
+# ==============================================================================
+# JetBrains (PyCharm)
+.idea/
+*.iws
+*.iml
+*.ipr
+
+# Zed / VS Code
+.zed/
+.vscode/
+
+# Editor temporary files
+*~
+*.swp
+*.swo
+
+# Operating Systems (Linux / Windows / macOS)
+.DS_Store
+.DS_Store?
+._*
+Thumbs.db
+ehthumbs.db
+Desktop.ini

mail_cadence-0.1.1/AGENTS.md

@@ -0,0 +1,36 @@
+# Architectural and Quality Guidelines (AGENTS.md)
+
+This document defines absolute engineering rules for the `mail-cadence` project. Any code changes must comply with the following principles before task completion.
+
+## 1. Mandatory Quality Gates
+Before declaring code readiness, run all of the following tools. None of them may return errors or warnings:
+1. `pytest` – all unit and integration tests must pass.
+2. `mypy src tests` – full compliance with `strict = true` mode.
+3. `ruff check src tests` and `ruff format --check src tests` – zero linter rule violations (including the `C901 <= 10` complexity limit).
+4. `vulture src` – zero dead code, unused private methods, and local variables.
+5. `radon cc src -a -nb` – no function or method may have a complexity rating worse than `B`.
+6. `pip-audit` – no known vulnerabilities in dependencies.
+
+## 2. SQLite Database Layer (`database.py`, `repository.py`, `xml_loader.py`)
+* **Ban on nested `with self.conn:` blocks:** In the `sqlite3` library, exiting a `with conn:` block immediately performs a `COMMIT` across the entire connection.
+  - Public methods in `DatabaseRepository` (e.g., `save_report_settings`, `save_work_schedules`, `save_mail_configuration`) open a `with self.conn:` block and delegate SQL queries to private methods (`_save_report_settings`, `_save_work_schedules`, `_save_mail_configuration`, `_save_task`) which **do not use** `with self.conn:`.
+  - Complex cross-module operations (e.g., `import_from_xml` in `xml_loader.py`) must open a single `with conn:` block at the highest level and call internal `_save_*` methods, guaranteeing a full `ROLLBACK` on error.
+* **Foreign Key Constraints (`ON DELETE RESTRICT`):** The `tasks` table has a foreign key `schedule_ref` with the `ON DELETE RESTRICT` clause. In `mode="replace"`, always delete rows from `task_context_variables`, `task_recipients`, and `tasks` **before** deleting rows from `schedules`.
+* **Ban on N+1 queries and execution loops:**
+  - When reading collections (e.g., `get_mail_tasks`, `get_work_schedules`), fetch related records via a bulk `SELECT` query and group them in memory using `collections.defaultdict`. Do not execute `SELECT` queries inside `for` loops.
+  - When writing collections (recipients, context variables, hour windows), always use `self.conn.executemany(...)` instead of `self.conn.execute(...)` in a loop.
+
+## 3. SMTP Engine and Concurrency (`mailer.py`, `scheduler.py`, `cli.py`)
+* **DRY Principle in `AsyncMailer`:** Management of the SMTP connection lifecycle (`_custom_smtp_client`, connection pool `self._pool`, single-use connection) must be implemented in a single place (e.g., via `@contextlib.asynccontextmanager`), without duplicating `try...except` blocks and `send_message` calls.
+* **SMTP Error Classification and Retry:**
+  - Error codes in the range `500 <= code < 600` are permanent errors and **are not subject** to retries.
+  - Upon partial delivery (when some recipients receive the message while others return an error in the `errors` dictionary), filter out recipients with a permanent `5xx` error immediately and retry sending (`pending_recipients`) exclusively for recipients with transient errors (`4xx`).
+* **Time and Clocks:**
+  - For measuring task execution duration (`duration_ms`) and in `TokenBucketRateLimiter`, use exclusively a monotonic clock (`time.monotonic()`).
+  - Execution timestamps (`last_run`, `start_time`, `end_time`) must always be stored as timezone-aware `datetime` objects (`datetime.now(UTC)` or `zoneinfo.ZoneInfo`).
+
+## 4. Security (`models.py`, `xml_loader.py`, `mailer.py`)
+* **XML Parsing:** Every XML file before being passed to `pydantic-xml` must be validated via `defusedxml.ElementTree` to protect against XXE and entity expansion attacks.
+* **SMTP Header Injection Protection:** All fields going into message headers (`sender`, `recipient`, `subject`, `to`, `cc`, `bcc`) must be validated for the absence of `\r` and `\n` characters (`_check_no_newlines`).
+* **Jinja2 Templates:** `TemplateRenderer` must validate paths using the `resolved_path.relative_to(base_dir)` method (Path Traversal protection) and keep `select_autoescape(["html", "xml"])` enabled.
+* **Secrets and Credentials:** Never store real passwords or `.env` files in the repository. In tests, use exclusively local mock/sink servers on `127.0.0.1` and dummy domains (`@example.com`, `@localhost`).

mail_cadence-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bulk Mailer Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mail_cadence-0.1.1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.5
+Name: mail-cadence
+Version: 0.1.1
+Summary: Asynchronous SQLite-backed bulk email dispatch and reporting engine with XML import/export support
+Project-URL: Homepage, https://github.com/krj29b/mail-cadence
+Project-URL: Repository, https://github.com/krj29b/mail-cadence
+Project-URL: Issues, https://github.com/krj29b/mail-cadence/issues
+Author: krj29b
+License: MIT License
+        
+        Copyright (c) 2026 Bulk Mailer Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: aiosmtplib,email,fastapi,htmx,rate-limiter,scheduler,smtp,sqlite,xml
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic :: 2
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiosmtplib>=3.0.1
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: jinja2>=3.1.4
+Requires-Dist: lxml>=5.2.2
+Requires-Dist: pydantic-settings>=2.4.0
+Requires-Dist: pydantic-xml[lxml]>=2.11.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: typer>=0.12.3
+Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pip-audit>=2.7.3; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.8; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: radon>=6.0.1; extra == 'dev'
+Requires-Dist: ruff>=0.5.5; extra == 'dev'
+Requires-Dist: vulture>=2.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MailCadence Engine
+
+Production-grade, asynchronous bulk email dispatch and reporting engine built in **Python 3.12+**.
+
+## Overview
+
+`mail-cadence` is a high-performance email dispatch engine that utilizes SQLite as its primary database backend for runtime configurations and execution history logging, while retaining full XML support for importing and exporting configuration definitions (`tasks.xml` and `schedules.xml`). It evaluates active schedule windows across timezones, dispatches scheduled email tasks concurrently with rate limiting and exponential backoff retry resilience, and sends a final Task Completion Status Report email upon completion.
+
+---
+
+## Key Features
+
+- **Python 3.12+ Standards:** Built with strict type safety, `asyncio.TaskGroup`, `StrEnum`, `pydantic v2`, and `pydantic-xml`.
+- **SQLite State Persistence:** SQLite runtime database storing tasks, schedules, report settings, and detailed execution logs with Write-Ahead Logging (`WAL`) mode and busy timeout handling (`30,000 ms`).
+- **Safe XML Import & Export:** Built-in `defusedxml` protection against XXE and entity expansion attacks, supporting bidirectional conversion between XML documents and SQLite data models.
+- **Timezone-Aware Throttling & Idempotency:** Hourly schedule windows with `zoneinfo` time zone awareness, midnight-spanning time calculation, window-level idempotency protection (`last_status == SUCCESS`), and token bucket rate limiting.
+- **Async SMTP Dispatch & Retries:** High-concurrency SMTP dispatch with `aiosmtplib`, `asyncio.Semaphore`, connection pooling, exponential backoff retries on transient errors, and `--dry-run` simulation mode.
+- **Jinja2 Templating:** Templated task emails with path traversal defense and auto-escaped context variables, alongside consolidated HTML/plain-text batch summary reports.
+
+---
+
+## Prerequisites & Installation
+
+### Requirements
+- **Python >= 3.12**
+- **pip** package manager
+
+### Installation Instructions
+
+Clone the repository and install `mail-cadence` along with its development dependencies:
+
+```bash
+# Install in editable mode with development dependencies
+python3 -m pip install -e ".[dev]"
+```
+
+Or use the provided `Makefile`:
+
+```bash
+make install
+```
+
+---
+
+## Configuration Reference
+
+`mail-cadence` is configured through environment variables (or a `.env` file) for SMTP server options and database location, alongside XML or database settings.
+
+### Environment Variables (`Settings`)
+
+Supported environment settings defined in `mail_cadence.models.Settings`:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SMTP_HOST` | `localhost` | Hostname or IP address of the SMTP server |
+| `SMTP_PORT` | `1025` | Port number for the SMTP server |
+| `SMTP_USER` | *None* | Username for SMTP authentication (optional) |
+| `SMTP_PASSWORD` | *None* | Password for SMTP authentication (optional) |
+| `SMTP_USE_TLS` | `false` | Enable direct TLS connection (`true`/`false`) |
+| `SMTP_START_TLS` | `false` | Enable STARTTLS command upgrade (`true`/`false`) |
+| `SMTP_TIMEOUT` | `30.0` | Timeout in seconds for SMTP operations |
+| `MAIL_CADENCE_DB` | `mail_cadence.db` | Path to SQLite database file |
+
+---
+
+## CLI Usage Guide (`mail-cadence`)
+
+The package provides the `mail-cadence` CLI executable (as well as `python -m mail_cadence.cli`).
+
+### 1. Main Dispatch Command
+
+Executes the main bulk mailer dispatch pipeline.
+
+```bash
+mail-cadence [OPTIONS]
+```
+
+#### Flags & Options
+| Option | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--tasks-xml` | `-t` | `PATH` | *None* | Optional path to tasks XML file to seed/upsert database |
+| `--schedule-xml` | `-s` | `PATH` | *None* | Optional path to schedule XML file to seed/upsert database |
+| `--db` | `-b` | `PATH` | `mail_cadence.db` | Path to SQLite database file (overrides `MAIL_CADENCE_DB`) |
+| `--dry-run` | `-d` | `FLAG` | `false` | Execute workflow in simulation mode without sending network SMTP requests |
+| `--verbose` | `-v` | `FLAG` | `false` | Enable verbose debug logging output |
+
+#### Exit Codes
+- **`0`**: Successful execution or no tasks were eligible for processing.
+- **`1`**: Configuration or database error encountered (e.g. invalid file format, database connection failure).
+- **`2`**: One or more tasks failed execution during the dispatch batch.
+
+#### Example Dispatch Commands
+```bash
+# Execute dispatch and seed XML configurations if database is empty or needs updates
+mail-cadence --tasks-xml config/samples/tasks.xml --schedule-xml config/samples/schedules.xml
+
+# Run dispatch in dry-run mode using an existing SQLite database
+mail-cadence --db mail_cadence.db --dry-run --verbose
+```
+
+---
+
+### 2. XML Import Command (`import-xml`)
+
+Imports task definitions and schedule rules from XML configuration files into the SQLite database.
+
+```bash
+mail-cadence import-xml [OPTIONS]
+```
+
+#### Options
+| Option | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--tasks-xml` | `-t` | `PATH` | *None* | Path to tasks configuration XML file |
+| `--schedule-xml` | `-s` | `PATH` | *None* | Path to schedule configuration XML file |
+| `--db` | `-b` | `PATH` | `mail_cadence.db` | Target SQLite database file path |
+| `--mode` | `-m` | `CHOICE` | `upsert` | Import mode: `upsert` (update/insert) or `replace` (clear and reload) |
+
+#### Example
+```bash
+mail-cadence import-xml --tasks-xml config/samples/tasks.xml --schedule-xml config/samples/schedules.xml --mode upsert
+```
+
+---
+
+### 3. XML Export Command (`export-xml`)
+
+Exports current task definitions, schedules, and report settings from the SQLite database back into XML files.
+
+```bash
+mail-cadence export-xml [OPTIONS]
+```
+
+#### Options
+| Option | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--tasks-xml` | `-t` | `PATH` | *None* | Destination path for exported tasks XML |
+| `--schedule-xml` | `-s` | `PATH` | *None* | Destination path for exported schedules XML |
+| `--db` | `-b` | `PATH` | `mail_cadence.db` | Source SQLite database file path |
+
+#### Example
+```bash
+mail-cadence export-xml --tasks-xml exported_tasks.xml --schedule-xml exported_schedules.xml
+```
+
+---
+
+## Development & Quality Gates
+
+The project maintains strict code quality standards enforced via `Makefile` commands:
+
+```bash
+# Run unit and integration test suite with coverage
+make test
+
+# Run code style and linting checks (Ruff & Mypy)
+make lint
+
+# Run dead code detection (Vulture)
+make dead-code
+
+# Run code complexity analysis (Radon)
+make complexity
+
+# Run dependency vulnerability audit (pip-audit)
+make audit
+
+# Run all quality gate checks in sequence
+make quality-gate
+```
+
+---
+
+## Architectural Deep Dive
+
+For detailed technical specifications, database entity-relationship diagrams (ERD), scheduling algorithms, Mermaid state/sequence diagrams, and security mechanics, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

mail_cadence-0.1.1/README.md

@@ -0,0 +1,176 @@
+# MailCadence Engine
+
+Production-grade, asynchronous bulk email dispatch and reporting engine built in **Python 3.12+**.
+
+## Overview
+
+`mail-cadence` is a high-performance email dispatch engine that utilizes SQLite as its primary database backend for runtime configurations and execution history logging, while retaining full XML support for importing and exporting configuration definitions (`tasks.xml` and `schedules.xml`). It evaluates active schedule windows across timezones, dispatches scheduled email tasks concurrently with rate limiting and exponential backoff retry resilience, and sends a final Task Completion Status Report email upon completion.
+
+---
+
+## Key Features
+
+- **Python 3.12+ Standards:** Built with strict type safety, `asyncio.TaskGroup`, `StrEnum`, `pydantic v2`, and `pydantic-xml`.
+- **SQLite State Persistence:** SQLite runtime database storing tasks, schedules, report settings, and detailed execution logs with Write-Ahead Logging (`WAL`) mode and busy timeout handling (`30,000 ms`).
+- **Safe XML Import & Export:** Built-in `defusedxml` protection against XXE and entity expansion attacks, supporting bidirectional conversion between XML documents and SQLite data models.
+- **Timezone-Aware Throttling & Idempotency:** Hourly schedule windows with `zoneinfo` time zone awareness, midnight-spanning time calculation, window-level idempotency protection (`last_status == SUCCESS`), and token bucket rate limiting.
+- **Async SMTP Dispatch & Retries:** High-concurrency SMTP dispatch with `aiosmtplib`, `asyncio.Semaphore`, connection pooling, exponential backoff retries on transient errors, and `--dry-run` simulation mode.
+- **Jinja2 Templating:** Templated task emails with path traversal defense and auto-escaped context variables, alongside consolidated HTML/plain-text batch summary reports.
+
+---
+
+## Prerequisites & Installation
+
+### Requirements
+- **Python >= 3.12**
+- **pip** package manager
+
+### Installation Instructions
+
+Clone the repository and install `mail-cadence` along with its development dependencies:
+
+```bash
+# Install in editable mode with development dependencies
+python3 -m pip install -e ".[dev]"
+```
+
+Or use the provided `Makefile`:
+
+```bash
+make install
+```
+
+---
+
+## Configuration Reference
+
+`mail-cadence` is configured through environment variables (or a `.env` file) for SMTP server options and database location, alongside XML or database settings.
+
+### Environment Variables (`Settings`)
+
+Supported environment settings defined in `mail_cadence.models.Settings`:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SMTP_HOST` | `localhost` | Hostname or IP address of the SMTP server |
+| `SMTP_PORT` | `1025` | Port number for the SMTP server |
+| `SMTP_USER` | *None* | Username for SMTP authentication (optional) |
+| `SMTP_PASSWORD` | *None* | Password for SMTP authentication (optional) |
+| `SMTP_USE_TLS` | `false` | Enable direct TLS connection (`true`/`false`) |
+| `SMTP_START_TLS` | `false` | Enable STARTTLS command upgrade (`true`/`false`) |
+| `SMTP_TIMEOUT` | `30.0` | Timeout in seconds for SMTP operations |
+| `MAIL_CADENCE_DB` | `mail_cadence.db` | Path to SQLite database file |
+
+---
+
+## CLI Usage Guide (`mail-cadence`)
+
+The package provides the `mail-cadence` CLI executable (as well as `python -m mail_cadence.cli`).
+
+### 1. Main Dispatch Command
+
+Executes the main bulk mailer dispatch pipeline.
+
+```bash
+mail-cadence [OPTIONS]
+```
+
+#### Flags & Options
+| Option | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--tasks-xml` | `-t` | `PATH` | *None* | Optional path to tasks XML file to seed/upsert database |
+| `--schedule-xml` | `-s` | `PATH` | *None* | Optional path to schedule XML file to seed/upsert database |
+| `--db` | `-b` | `PATH` | `mail_cadence.db` | Path to SQLite database file (overrides `MAIL_CADENCE_DB`) |
+| `--dry-run` | `-d` | `FLAG` | `false` | Execute workflow in simulation mode without sending network SMTP requests |
+| `--verbose` | `-v` | `FLAG` | `false` | Enable verbose debug logging output |
+
+#### Exit Codes
+- **`0`**: Successful execution or no tasks were eligible for processing.
+- **`1`**: Configuration or database error encountered (e.g. invalid file format, database connection failure).
+- **`2`**: One or more tasks failed execution during the dispatch batch.
+
+#### Example Dispatch Commands
+```bash
+# Execute dispatch and seed XML configurations if database is empty or needs updates
+mail-cadence --tasks-xml config/samples/tasks.xml --schedule-xml config/samples/schedules.xml
+
+# Run dispatch in dry-run mode using an existing SQLite database
+mail-cadence --db mail_cadence.db --dry-run --verbose
+```
+
+---
+
+### 2. XML Import Command (`import-xml`)
+
+Imports task definitions and schedule rules from XML configuration files into the SQLite database.
+
+```bash
+mail-cadence import-xml [OPTIONS]
+```
+
+#### Options
+| Option | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--tasks-xml` | `-t` | `PATH` | *None* | Path to tasks configuration XML file |
+| `--schedule-xml` | `-s` | `PATH` | *None* | Path to schedule configuration XML file |
+| `--db` | `-b` | `PATH` | `mail_cadence.db` | Target SQLite database file path |
+| `--mode` | `-m` | `CHOICE` | `upsert` | Import mode: `upsert` (update/insert) or `replace` (clear and reload) |
+
+#### Example
+```bash
+mail-cadence import-xml --tasks-xml config/samples/tasks.xml --schedule-xml config/samples/schedules.xml --mode upsert
+```
+
+---
+
+### 3. XML Export Command (`export-xml`)
+
+Exports current task definitions, schedules, and report settings from the SQLite database back into XML files.
+
+```bash
+mail-cadence export-xml [OPTIONS]
+```
+
+#### Options
+| Option | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--tasks-xml` | `-t` | `PATH` | *None* | Destination path for exported tasks XML |
+| `--schedule-xml` | `-s` | `PATH` | *None* | Destination path for exported schedules XML |
+| `--db` | `-b` | `PATH` | `mail_cadence.db` | Source SQLite database file path |
+
+#### Example
+```bash
+mail-cadence export-xml --tasks-xml exported_tasks.xml --schedule-xml exported_schedules.xml
+```
+
+---
+
+## Development & Quality Gates
+
+The project maintains strict code quality standards enforced via `Makefile` commands:
+
+```bash
+# Run unit and integration test suite with coverage
+make test
+
+# Run code style and linting checks (Ruff & Mypy)
+make lint
+
+# Run dead code detection (Vulture)
+make dead-code
+
+# Run code complexity analysis (Radon)
+make complexity
+
+# Run dependency vulnerability audit (pip-audit)
+make audit
+
+# Run all quality gate checks in sequence
+make quality-gate
+```
+
+---
+
+## Architectural Deep Dive
+
+For detailed technical specifications, database entity-relationship diagrams (ERD), scheduling algorithms, Mermaid state/sequence diagrams, and security mechanics, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).