# 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.