travel-planner/docs/superpowers/plans/travel-planner-implementation-roadmap.md

Travel Planner AI Agent Implementation Roadmap

For agentic workers: This roadmap decomposes the approved design into independent implementation plans. Execute only one phase plan at a time. Each phase must leave the repository buildable, testable, and deployable before the next phase begins.

Goal: Deliver the approved self-hosted multi-trip travel planner with Mistral-powered agent behavior, optional web research, proactive watches, email/PWA notifications, structured planning, and TeamCity deployment.

Architecture: A modular-monolith NestJS backend exposes an API and a separate BullMQ worker from one codebase. An Angular PWA is compiled into the edge image. PostgreSQL is the source of truth; Redis is queue infrastructure. Exactly one TCP port is published by the production Compose stack, owned by the edge proxy.

Tech Stack: Node.js 24 LTS, TypeScript, Angular 22, NestJS 11, PostgreSQL 18, Redis 8, BullMQ, Docker Compose, TeamCity, Mistral.

Global Constraints

• PostgreSQL is the source of truth; the LLM is never the source of truth.
• Mistral is the only LLM provider implemented in MVP, behind an LlmProvider interface.
• The LLM never receives direct database, shell, arbitrary HTTP, or filesystem access.
• Agent tools call application services, never repositories directly.
• webResearchEnabled=false means the web-research tool is not registered for that trip/run.
• Structured APIs such as routing, places, geocoding, and weather remain independently configurable.
• Locked itinerary items and confirmed bookings are protected by deterministic backend rules.
• Background agent runs have fewer permissions than interactive/planning runs.
• AI output is schema-validated before any mutation.
• Facts retain provenance, verification state, retrieval time, and confidence where applicable.
• Critical actions require explicit confirmation.
• Notifications are delivered by application policy, not directly by the LLM.
• Background work is queued, retryable, and idempotent.
• External-provider failure must not corrupt stored trip state or prevent ordinary trip viewing/editing.
• Exactly one TCP port from production Compose is published to the host, by edge only.
• api, worker, postgres, and redis have no host-published ports.
• TeamCity deploys immutable application-image versions and runs versioned database migrations.
• Secrets are never committed, baked into images, or embedded in the Angular bundle.
• Direct purchase, cancellation, payment, Gmail ingestion, expense splitting, native apps, Kubernetes, and microservices are non-goals for MVP.

---

Plan Dependency Graph

01 Foundation & Deployment
        |
        v
02 Auth & Trip Core
        |
        v
03 Activities & Itinerary
        |
        v
04 Agent Foundation
        |
        v
05 Policies & Planning Tools
        |
        +------------------+
        v                  v
06 Research Providers   10 Budget
        |
        v
07 Watch System & Worker
        |
        v
08 Notifications
        |
        v
09 Bookings & Documents
        |
        v
11 UX Completion
        |
        v
12 Evaluation & Hardening

Budget can begin after Phase 5 but must be complete before Phase 11. All other phases should be executed in numeric order unless a reviewed dependency change is made.

Phase Plans

01 — Foundation & Deployment

Plan file: docs/superpowers/plans/2026-08-17-phase-01-foundation-deployment.md

Outcome: A repository with Angular PWA, NestJS API and worker, PostgreSQL/Redis development infrastructure, health/readiness endpoints, production images, single-port edge topology, and repo-owned TeamCity build/deploy scripts.

Exit gate:

• pnpm test, pnpm lint, and pnpm build pass.
• API /health/live and /health/ready pass with PostgreSQL/Redis available.
• Production Compose publishes exactly one host port from edge.
• A smoke deployment can be performed using immutable IMAGE_TAG images.

02 — Authentication & Trip Core

Outcome: OIDC SSO, local users, preferences, trips, trip settings, members, invitations, and account-less travelers.

Primary domain: User, UserPreference, Trip, TripSettings, TripMember, TripInvitation, Traveler, TripPreferenceOverride.

Exit gate: A user can sign in via the existing OIDC IdP, create multiple trips, invite a member, add an infant traveler without an account, and toggle web research per trip.

03 — Activities & Itinerary

Outcome: Activity ideas, voting, day-by-day itinerary, drag/drop mutations, locking, optimistic concurrency, and initial trip UI.

Exit gate: Two users cannot silently overwrite the same itinerary version; locked items cannot be moved through normal mutation APIs; the frontend can drag/drop unlocked items.

04 — Agent Foundation

Outcome: LlmProvider, Mistral implementation, structured-output/tool-call contract, AgentRun, AgentAction, context builder, tool registry, and basic interactive agent endpoint with streaming status events.

Exit gate: A mocked provider can drive a deterministic tool-call loop; a live Mistral smoke test is opt-in; ordinary app functions continue when Mistral is unavailable.

05 — Policies & Planning Tools

Outcome: Deterministic action policy, protected actions, pending confirmations, audit trail, undo model, activity/itinerary planning tools, interactive and planning run modes.

Exit gate: A request to optimize a trip may move unlocked items but creates a pending confirmation instead of mutating a locked/confirmed resource.

06 — Research & Structured Providers

Outcome: ResearchFact, ResearchSource, web-research abstraction, places/geocoding/routing/weather abstractions, provenance UI, and provider capability handling.

Exit gate: With web research disabled, no web tool exists in the tool registry. Structured routing can still run. Current facts are labeled verified/unverified based on provenance.

07 — Watch System & Background Worker

Outcome: Watch items, dynamic nextCheckAt, scheduler, BullMQ processors, periodic trip review, web-condition checks, background permission restrictions, retry/idempotency behavior.

Exit gate: A due watch is queued and processed exactly once semantically; background runs cannot perform protected itinerary/bookings mutations.

08 — Notifications

Outcome: In-app notifications, SMTP mail, Web Push subscriptions/delivery, severity routing, per-user preferences, trip overrides, deduplication.

Exit gate: A HIGH watch transition results in one deduplicated in-app notification and, when enabled, one email and one PWA push.

09 — Bookings & Documents

Outcome: Manual bookings, local storage abstraction, PDF/JPEG/PNG uploads, extraction draft, user confirmation, confirmed-booking planning constraints.

Exit gate: Uploaded booking evidence cannot become authoritative without explicit confirmation; confirmed bookings are protected from autonomous agent mutation.

10 — Budget

Outcome: Trip budget, categories, estimates/actuals, budget UI, budget-impact agent tool and planning validation.

Exit gate: The agent can compare the cost impact of a plan and must not represent estimates as actual costs.

11 — UX Completion

Outcome: Trip dashboard, watches, ideas/details, bookings, budget, group page, global agent side panel, planning/travel mode emphasis, responsive PWA polish.

Exit gate: Core workflows are usable on desktop and mobile without requiring chat prompts for ordinary CRUD/planning actions.

12 — Evaluation & Hardening

Outcome: Slovenia 2027 golden scenario suite, resilience/concurrency/security tests, live-provider smoke profiles, deployment rollback rehearsal, backup/restore rehearsal, documentation completion.

Exit gate: All MVP acceptance criteria from the approved specification pass, including the single-port production invariant and TeamCity rollback without rebuild.

---

Implementation Rules for Coding Agents

1. Load the approved design spec plus only the current phase plan and directly relevant source files.
2. Do not pre-implement later phases “for convenience”. Introduce interfaces only when the current phase needs their boundary.
3. Use TDD for deterministic domain/application behavior: failing test, minimal implementation, passing test, commit.
4. Prefer focused files and narrow interfaces. Split a file when it develops multiple independent reasons to change.
5. Every task ends in a repository state that can be reviewed independently.
6. Do not weaken architecture invariants to make a test pass.
7. Never add a generic agent executeSql, shell, arbitrary HTTP, or arbitrary filesystem tool.
8. Live/paid external-provider tests are opt-in and must not run on every TeamCity commit build.
9. Production Compose invariant tests are mandatory and must fail if any service other than edge adds ports:.
10. TeamCity should call repository scripts rather than duplicating deployment logic in opaque UI steps.

Version Baseline (2026-08-17)

• Node.js: 24 LTS line.
• Angular: 22.x.
• NestJS: 11.x.
• PostgreSQL production image baseline: postgres:18.4-alpine.
• Redis production image baseline: redis:8.8.1-alpine.

Image tags are reviewed upgrade inputs, not floating latest tags. JavaScript dependencies are locked by pnpm-lock.yaml.

Roadmap Completion Definition

The roadmap is complete only when the end-to-end Slovenia 2027 scenario passes: OIDC sign-in, multi-person trip planning including a child, optional web research, provenance-aware suggestions, votes, realistic itinerary generation, protected locks/bookings, background marathon watch, deduplicated email and PWA push, booking-document confirmation, budget-aware planning, graceful LLM outage, single published production port, and TeamCity immutable deployment/rollback.