Add 8 proposed changes and old trails analysis
Proposed changes (all with proposal, design, specs, tasks): - app-navigation (9 tasks) — nav bars for both apps - planner-landing-page (7 tasks) — standalone landing page - planner-multiplayer-awareness (13 tasks) — participants, cursors, names - changelog (13 tasks) — public changelog with "what's new" - transactional-emails (15 tasks) — magic link + welcome emails - planner-features (18 tasks) — no-go areas, notes, recovery, rate limits - komoot-import (23 tasks) — Komoot tour import - route-features (37 tasks) — sharing, multi-day, spatial, photos Also adds docs/old-trails-analysis.md with feature analysis from the older trails project. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ullrich Schäfer
parent
57141cdfab
commit
c7c1c275df
55 changed files with 1704 additions and 0 deletions
2
openspec/changes/transactional-emails/.openspec.yaml
Normal file
2
openspec/changes/transactional-emails/.openspec.yaml
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
schema: spec-driven
|
||||
created: 2026-03-25
|
||||
62
openspec/changes/transactional-emails/design.md
Normal file
62
openspec/changes/transactional-emails/design.md
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
## Context
|
||||
|
||||
The Journal has passkey auth (primary) and magic link login (fallback). Magic
|
||||
links work in dev (auto-redirect) but in production the link is only logged
|
||||
to console — users never receive it. No email infrastructure exists.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Actually deliver magic link emails in production
|
||||
- Send a welcome email after registration
|
||||
- Provider-agnostic email interface (easy to swap providers)
|
||||
- HTML templates with plain-text fallback
|
||||
- Easy to add new email types in the future (just add a template + call)
|
||||
- Dev mode: still log to console / return devLink (no real emails)
|
||||
|
||||
**Non-Goals:**
|
||||
- Marketing emails or newsletters
|
||||
- Email preferences / unsubscribe (only transactional)
|
||||
- Inline CSS / complex email layouts (keep it simple text-focused)
|
||||
- Queuing or retry logic (provider handles delivery)
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1: Resend as email provider
|
||||
|
||||
Use [Resend](https://resend.com) — simple API, generous free tier (3k
|
||||
emails/month), good developer experience. Single dependency: `resend` npm
|
||||
package.
|
||||
|
||||
**Alternative considered**: Nodemailer + SMTP. More complex setup, requires
|
||||
SMTP server. Resend is simpler for a small project.
|
||||
|
||||
**Alternative considered**: Postmark. Similar to Resend but less ergonomic API.
|
||||
|
||||
### D2: Email module in apps/journal/app/lib/email.server.ts
|
||||
|
||||
Not a shared package — only the Journal sends emails. Keep it simple:
|
||||
- `sendEmail(to, subject, html, text)` — low-level sender
|
||||
- `sendMagicLink(email, link)` — template wrapper
|
||||
- `sendWelcome(email, username)` — template wrapper
|
||||
|
||||
In dev mode, `sendEmail` logs to console instead of calling Resend.
|
||||
|
||||
### D3: Inline HTML templates
|
||||
|
||||
Simple functions returning HTML strings. No template engine. Each email type
|
||||
is a function: `magicLinkTemplate(link)`, `welcomeTemplate(username)`. Plain
|
||||
text generated by stripping tags.
|
||||
|
||||
### D4: Sender domain: noreply@trails.cool
|
||||
|
||||
Requires DNS verification (DKIM/SPF records) with Resend. Add TXT records via
|
||||
Terraform or manually in Hetzner DNS.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **Resend vendor lock-in** → Low risk. The `sendEmail` wrapper abstracts it.
|
||||
Swapping to nodemailer later is a one-file change.
|
||||
- **DNS verification required** → Must add DKIM/SPF records before emails work.
|
||||
Can use Resend's test domain initially.
|
||||
- **Free tier limits** → 3k/month is plenty for <100 users.
|
||||
32
openspec/changes/transactional-emails/proposal.md
Normal file
32
openspec/changes/transactional-emails/proposal.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
## Why
|
||||
|
||||
Magic link login doesn't work in production — the link is logged to console
|
||||
but never emailed to the user. Registration works (passkey-based) but the
|
||||
fallback auth flow is broken. We need actual email delivery.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add a reusable email sending layer (`@trails-cool/email` or in-app module)
|
||||
with a provider-agnostic interface so future emails are trivial to add
|
||||
- Send magic link emails in production
|
||||
- Send a welcome email after registration
|
||||
- Use a transactional email provider (Resend, Postmark, or SMTP)
|
||||
- HTML email templates with plain-text fallback
|
||||
- Document email sending in the privacy manifest
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `transactional-emails`: Send templated emails via a provider-agnostic interface. Current emails: magic link login, welcome on registration. Designed for easy addition of future email types.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `journal-auth`: Magic link flow now actually sends the email instead of logging to console
|
||||
|
||||
## Impact
|
||||
|
||||
- **Files**: New email module (lib or package), modified `api.auth.login.ts`, modified registration flow, email templates
|
||||
- **Dependencies**: One email provider SDK (e.g., `resend` or `nodemailer`)
|
||||
- **Infrastructure**: Email provider API key as env var, DNS records for sender domain verification
|
||||
- **Privacy**: Email addresses sent to third-party email provider — must document
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Magic link login
|
||||
The magic link login flow SHALL deliver the link via email in production instead of logging to console.
|
||||
|
||||
#### Scenario: Production email delivery
|
||||
- **WHEN** a user requests a magic link in production
|
||||
- **THEN** the link is emailed to the user (not just logged to console)
|
||||
|
||||
#### Scenario: Dev mode unchanged
|
||||
- **WHEN** a user requests a magic link in development
|
||||
- **THEN** the link is returned directly for auto-redirect (existing behavior preserved)
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Email sending interface
|
||||
The system SHALL provide a provider-agnostic email sending function that supports HTML and plain-text content.
|
||||
|
||||
#### Scenario: Send email in production
|
||||
- **WHEN** the system sends a transactional email in production
|
||||
- **THEN** the email is delivered via the configured provider (Resend) to the recipient
|
||||
|
||||
#### Scenario: Dev mode skips sending
|
||||
- **WHEN** the system sends a transactional email in development
|
||||
- **THEN** the email content is logged to console and no external API is called
|
||||
|
||||
### Requirement: Magic link email
|
||||
The system SHALL send an email containing the magic link when a user requests passwordless login.
|
||||
|
||||
#### Scenario: Magic link delivered
|
||||
- **WHEN** a user requests a magic link login
|
||||
- **THEN** an email is sent with a clickable link that logs them in
|
||||
|
||||
#### Scenario: Email content
|
||||
- **WHEN** a magic link email is sent
|
||||
- **THEN** it includes: the link, expiry time (15 minutes), and plain-text fallback
|
||||
|
||||
### Requirement: Welcome email
|
||||
The system SHALL send a welcome email after successful registration.
|
||||
|
||||
#### Scenario: Welcome on registration
|
||||
- **WHEN** a user completes passkey registration
|
||||
- **THEN** a welcome email is sent to their registered email address
|
||||
|
||||
### Requirement: Email templates
|
||||
Each email type SHALL have an HTML template with a plain-text fallback.
|
||||
|
||||
#### Scenario: Extensible template pattern
|
||||
- **WHEN** a new email type is needed in the future
|
||||
- **THEN** it can be added by creating a template function and calling sendEmail
|
||||
|
||||
### Requirement: Privacy disclosure
|
||||
Email sending SHALL be documented in the privacy manifest.
|
||||
|
||||
#### Scenario: Privacy manifest updated
|
||||
- **WHEN** transactional emails are enabled
|
||||
- **THEN** the /privacy page documents: what emails are sent, that email addresses are shared with the email provider, and which provider is used
|
||||
30
openspec/changes/transactional-emails/tasks.md
Normal file
30
openspec/changes/transactional-emails/tasks.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
## 1. Email Infrastructure
|
||||
|
||||
- [ ] 1.1 Add `resend` package to Journal dependencies
|
||||
- [ ] 1.2 Create `apps/journal/app/lib/email.server.ts` with sendEmail(to, subject, html, text) — uses Resend in production, logs to console in dev
|
||||
- [ ] 1.3 Add `RESEND_API_KEY` env var to docker-compose.yml
|
||||
- [ ] 1.4 Write unit test for sendEmail (mock Resend, verify dev-mode logging)
|
||||
|
||||
## 2. Email Templates
|
||||
|
||||
- [ ] 2.1 Create magicLinkTemplate(link: string) returning { html, text } — includes link, 15-min expiry note, trails.cool branding
|
||||
- [ ] 2.2 Create welcomeTemplate(username: string) returning { html, text } — greeting, what they can do, link to routes
|
||||
- [ ] 2.3 Wire sendMagicLink(email, link) and sendWelcome(email, username) helper functions
|
||||
|
||||
## 3. Integration
|
||||
|
||||
- [ ] 3.1 Update api.auth.login.ts: call sendMagicLink in production instead of just logging
|
||||
- [ ] 3.2 Update registration flow: call sendWelcome after successful passkey registration
|
||||
- [ ] 3.3 Verify dev mode still works (devLink returned, no email sent)
|
||||
|
||||
## 4. Privacy & Config
|
||||
|
||||
- [ ] 4.1 Update /privacy page: document email sending, provider (Resend), what data is shared
|
||||
- [ ] 4.2 Add `RESEND_API_KEY` to CD secrets and deploy documentation
|
||||
- [ ] 4.3 Document sender domain DNS setup (DKIM/SPF for noreply@trails.cool)
|
||||
|
||||
## 5. Verify
|
||||
|
||||
- [ ] 5.1 Test magic link email delivery locally with Resend test API key
|
||||
- [ ] 5.2 Test welcome email on registration
|
||||
- [ ] 5.3 Verify existing E2E tests still pass (dev mode unchanged)
|
||||
Loading…
Add table
Add a link
Reference in a new issue