A personal hobby project focused on automating boring everyday tasks. Built as an exploration of Azure Functions, pragmatic clean architecture, and GitHub Copilot agent-assisted development.
- Primary: Automate repetitive tasks (package tracking, invoice management, manga updates, etc.)
- Secondary: Experiment with modern technologies (Azure hosting, GitHub Copilot agents)
The project follows clean architecture principles with a clear separation between infrastructure and application logic.
├── cloud/ # Infrastructure layer (Azure)
│ ├── functions/ # Azure Functions (one per file)
│ ├── dependencies/ # Service and client resolvers
│ └── helper/ # Azure-specific utilities
│
├── sebastian/ # Application layer (core logic)
│ ├── clients/ # External service clients
│ ├── usecases/ # Business logic services
│ ├── infrastructure/ # Event-triggered infrastructure (Telegram, Google Tasks)
│ └── shared/ # Shared utilities
│
└── function_app.py # Azure Functions entry point
Cloud Layer (cloud/):
- Timer-triggered Azure Functions that run on schedules
- Dependency injection via resolvers in
dependencies/ - Output bindings for Telegram notifications and Google Tasks
Application Layer (sebastian/):
- Clients: Interact with external services (Gmail, Telegram, Google Drive/Tasks)
- Usecases: Orchestrate clients with business logic (e.g., checking for DHL pickups, tracking manga updates)
- The application layer has no dependency on the cloud layer
- Azure Functions (cloud/functions/) are triggered by timers (see
TriggerTimes.py) - Functions resolve services via
cloud/dependencies/services.py - Services are injected with clients resolved from
cloud/dependencies/clients.py - Services execute business logic and return results
- Functions map results to output bindings (Telegram messages, Google Tasks)
| Function | Description | Schedule |
|---|---|---|
| DeliveryReady | Checks Gmail for DHL pickup notifications | Hourly at :28 |
| ReturnTracker | Tracks return shipments | Hourly at :35 |
| MangaUpdate | Monitors manga update sources | Daily at 3:05 AM |
| WinSim | Archives WinSim invoices to Google Drive | Daily at 9:00 PM |
| Mietplan | Manages rental payment schedules | Daily at 9:01 PM |
The project extensively uses GitHub Copilot agents for assisted development. Instructions are organized under .github/:
copilot-instructions.md: General coding guidelines, architecture principles, and style conventionsinstructions/: Task-specific instructions for:- Creating new Azure Functions
- Creating new clients
- Creating new services
prompts/: Reusable prompts for common operations
These instruction files ensure consistent code generation that follows the project's clean architecture patterns.
- Docker
- VS Code with Dev Containers extension
- Required credentials in Azure Key Vault (Telegram, Google, MangaUpdate, etc.)
Development is done via Dev Containers, which automatically sets up the complete environment:
- Open the project in VS Code
- When prompted, click "Reopen in Container" (or run
Dev Containers: Reopen in Containerfrom command palette) Start Azure Blob Service(bottom right in vscode)- In Azure extension, start debugging locally
The devcontainer includes:
- Python 3.12
- Azure Functions Core Tools
- Azure CLI
- GitHub CLI (
gh) - Poetry for dependency management
- All Python dependencies pre-installed
If you want to manage repository settings (for example, branch protection and auto-merge rules) from inside the devcontainer, use gh with a token stored only in your local .env file.
- Copy
.env.sampleto.env. - Create a fine-grained personal access token in GitHub.
- Add it to
.envasGH_TOKEN=.... - Rebuild or restart the devcontainer so the variable is injected.
- Verify with
gh auth status.
Security notes:
.envis gitignored in this repository, so your token is not committed.- Do not store tokens in tracked files like
README.md,pyproject.toml, or workflow files. - Prefer a fine-grained token scoped to this repository only, with minimum required permissions.
seamail is a read-only Gmail recall CLI for agents: search with Gmail's own query syntax, read one mail in full, list labels, pull attachments. It runs as a plain short-lived host process — no container, no Azure login, no Key Vault — on WSL today and a Raspberry Pi later.
scripts/setup_seamail.sh # idempotent: installs uv if missing, builds the venv, writes the PATH shim
export SEAMAIL_GOOGLE_CREDENTIALS="$(cat /path/to/credentials.json)"
seamail search 'from:installer subject:KfW after:2026/01/01'
seamail show <message-id> [--format text|html] [--max-chars 20000]
seamail labels
seamail attachments <message-id> --out ~/Downloads [--force]- Every successful call prints one JSON object on stdout. Failures print JSON on stderr with a machine-readable
kind(auth,api,usage,io); exit codes are0success,1runtime error,2usage error. - API errors carry
statusand, when Gmail names one,reasonalongside a single-sentencemessage(no Python repr or request URL):{"kind": "api", "status": 404, "reason": "notFound", "message": "Requested entity was not found."}. A401(expired/revoked token) or a permission403is reported askind: auth; quota/rate-limit403s stayapi. attachments --out DIRcreatesDIR(including parents) when missing; existing files are only replaced with--force.- The CLI never writes to Gmail. Labels are resolved to names on every call; search returns metadata only and a
nextPageTokeninstead of paginating for you. SEAMAIL_GOOGLE_CREDENTIALSholds the credentials JSON content (not a path); token refresh happens in-process and nothing is written back.- Its dependencies are the direct ones listed in
cli-requirements.txt;pyproject.tomlstays the source of truth andtests/unit_tests/test_cli_requirements.pyguards the two from drifting. The Azure deployment andrequirements.txtare untouched.
The project uses pytest for testing with a focus on the application layer (sebastian/).
Test organization:
tests/unit_tests/- Unit tests (no external dependencies, run in CI)tests/integration_tests/- Integration tests (require credentials, run locally)
Integration tests (dev machine only, pytest-xdist in the dev group) run in parallel per file via tests/integration_tests/pytest.ini (-n auto --dist loadfile) when invoked as poetry run pytest tests/integration_tests. Use -n0 to run serially. CI and unit tests are unaffected.
Run all tests:
poetry run pytestRun only unit tests:
poetry run pytest tests/unit_testsRun with coverage:
poetry run pytest tests/unit_tests --cov=sebastian --cov-report=htmlCI/CD:
-
Only unit tests run automatically in CI (fast, no credentials needed)
-
Integration tests should be run locally before merging
-
See
.github/instructions/testing.instructions.mdfor detailed testing guidelines
This project uses Poetry for dependency management while maintaining compatibility with Azure Functions deployment via requirements.txt.
Production dependencies:
poetry add <package-name>Development dependencies:
poetry add --group dev <package-name>Test dependencies:
poetry add --group test <package-name>Both pyproject.toml and poetry.lock will be updated automatically.
poetry remove <package-name>Azure Functions requires a requirements.txt file. A pre-commit hook automatically exports this file whenever pyproject.toml or poetry.lock changes, ensuring it stays in sync.
CI Validation:
The pull request pipeline automatically checks that requirements.txt is up-to-date. If the check fails, either:
- Commit your changes (the pre-commit hook will update it automatically), or
- Run the export command manually:
Committing your changes will only work if there are changes to
poetry.lockorpyproject.toml
poetry export -f requirements.txt --output requirements.txt --without-hashesOnly production dependencies are included in deployments—dev and test dependencies (pytest, ipykernel, etc.) are excluded.
For more details, see notes/dev_setup/dependencies.md.