# 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

```text
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.
