Gabriel Radureau
99989fc9e9
Adds the Mailpit HTTP API client used by BDD scenarios to assert on
emails sent during a test. Implements the per-recipient query/await/
purge pattern from ADR-0030.
Build-tag-gated integration tests run against the live Mailpit at
localhost:8025 (started via docker compose up -d mailpit).
Three operations on the client:
- MessagesTo(ctx, to) — list message IDs for a recipient
- Get(ctx, id) — fetch full message content (text, html,
headers, subject, etc.)
- AwaitMessageTo(ctx, to, — poll until a message arrives or timeout
timeout) (50ms polls, fail-fast on ctx cancel)
- PurgeMessagesTo(ctx, to) — delete all messages for a recipient
Tests in client_integration_test.go (build tag `integration`):
- RoundTrip: SMTP submit → list → get → assert subject/text — proves
the BDD-helper contract end-to-end via real SMTP
- AwaitTimeoutWhenNoMessage: bounded wait when no email arrives
- PurgeIsolation: per-recipient delete does NOT affect other recipients
Mailpit API quirk discovered + documented (Q-NNN candidate):
- /api/v1/messages?query=... is for PAGINATION, not filtering — the
`query` param there is silently ignored for filtering
- /api/v1/search?query=to:<addr> is the correct endpoint for filtering
AND the matching DELETE
- ADR-0030 + EMAIL.md updated with the correct endpoint
Run integration tests:
docker compose up -d mailpit
go test -tags integration -race ./pkg/bdd/mailpit/...
Out of scope for this PR (Phase A.3+):
- pkg/bdd/steps/email_steps.go BDD step definitions
- magic_link_tokens table + repository
- magic-link/request and magic-link/consume HTTP handlers
- BDD scenarios for the magic-link flow
Architecture Decision Records (ADRs)
This directory contains the Architecture Decision Records (ADRs) for the dance-lessons-coach project. Each ADR captures a structurally important decision, its context, and its consequences.
Index
| ADR | Title | Status |
|---|---|---|
| 0001 | Use Go 1.26.1 as the standard Go version | Accepted |
| 0002 | Use Chi router for HTTP routing | Accepted |
| 0003 | Use Zerolog for structured logging | Accepted |
| 0004 | Adopt interface-based design pattern | Accepted |
| 0005 | Implement graceful shutdown with readiness endpoints | Accepted |
| 0006 | Use Viper for configuration management | Accepted |
| 0007 | Integrate OpenTelemetry for distributed tracing | Accepted |
| 0008 | Adopt BDD with Godog for behavioral testing | Accepted |
| 0009 | Combine BDD and Swagger-based testing | Implemented |
| 0010 | API v2 Feature Flag Implementation | Accepted |
| 0012 | Git Hooks: Staged-Only Formatting | Accepted |
| 0013 | OpenAPI/Swagger Toolchain Selection | Implemented |
| 0015 | CLI Subcommands and Flag Management with Cobra | Implemented |
| 0016 | CI/CD Pipeline Design for Multi-Platform Compatibility | Accepted |
| 0017 | Trunk-Based Development Workflow for CI/CD Safety | Approved |
| 0018 | User Management and Authentication System | Implemented |
| 0019 | PostgreSQL Database Integration | Implemented |
| 0020 | Docker Build Strategy: Traditional vs Buildx | Accepted |
| 0021 | JWT Secret Retention Policy | Implemented |
| 0022 | Rate Limiting and Cache Strategy | Implemented (Phase 1) |
| 0023 | Config Hot Reloading Strategy | Implemented |
| 0024 | BDD Test Organization and Isolation Strategy | Implemented |
| 0025 | BDD Scenario Isolation Strategies | Implemented |
| 0026 | Composite Info Endpoint vs Separate Calls | Implemented |
| 0027 | Ollama Tier 1 onboarding via meta-trainer-bootstrap | Proposed |
| 0028 | Passwordless authentication: magic link → OpenID Connect | Proposed |
| 0029 | Email infrastructure: Mailpit local + production deferred | Proposed |
| 0030 | BDD email assertions with parallel test execution | Proposed |
Note
: numbers
0011and0014are not currently in use. Reserved for future ADRs or representing previously deleted entries.
What is an ADR?
An ADR is a document capturing one significant architectural decision: the context that motivated it, the decision itself, and its consequences. ADRs are append-only — once published, an ADR is not edited (except for typo / status updates). New decisions that supersede previous ones are recorded as new ADRs that explicitly link back.
Canonical Format
All ADRs follow the canonical format below (homogenized 2026-05-03):
# NN. Short title summarising the decision
**Status:** <Proposed | Accepted | Implemented | Partially Implemented | Approved | Rejected | Deferred | Deprecated | Superseded by ADR-NNNN>
**Date:** YYYY-MM-DD
**Authors:** Name(s)
[Optional fields, all in `**Field:** value` format:]
**Decision Drivers:** ...
**Implementation Status:** ...
**Implementation Date:** ...
**Last Updated:** ...
## Context and Problem Statement
[Describe the context and problem statement.]
## Decision Drivers
* Driver 1
* Driver 2
## Considered Options
* Option 1
* Option 2
## Decision Outcome
Chosen option: "Option 1" because [justification].
## Pros and Cons of the Options
### Option 1
* Good, because [argument].
* Bad, because [argument].
### Option 2
* Good, because [argument].
* Bad, because [argument].
## Links
* Related ADR: [ADR-NNNN](NNNN-slug.md)
* Issue: [#NN](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues/NN)
Status Legend
| Status | Meaning |
|---|---|
| Proposed | Decision is being discussed; no implementation yet. |
| Accepted | Decision has been made; implementation may be pending or in progress. |
| Approved | Same as Accepted; alternative term used in some legacy ADRs. |
| Implemented | Decision is fully implemented and in production. |
| Partially Implemented | Decision is partly implemented; remainder is deferred or pending. |
| Rejected | Decision considered and explicitly rejected. The ADR documents why. |
| Deferred | Decision postponed; revisit later. |
| Deprecated | Decision is no longer relevant; system has moved on. |
| Superseded by ADR-NNNN | Decision has been replaced by another ADR. Always include the link. |
How to Add a New ADR
- Pick the next available number (currently next would be
0026). - Copy an existing ADR (e.g.,
0001-go-1.26.1-standard.md) as a starting template. - Edit the title, status, date, authors, and content.
- Update this
README.mdindex with the new ADR. - Commit using gitmoji convention (e.g.,
📝 docs(adr): add ADR-0026 about ...). - Open a PR for review.