MolinoPro

README

Master Codebase Guidebook
Markdown + HTML Dev-Docs Renderer - Frontend Client Module

Default Index
Open README.md
Root: README.mdexperiences
Milestones
H1Experiences

version: 2026.04 status: supporting commercial unit owner: Molino scope: app/experiences, app/trips featured-experiences lane last_updated: 2026-04-26

H2Focus Strip
NowLockDo Not BreakNext Closure
Support Trips inventorycity-linked experiencesTrips stays execution rootclean data only where it improves Trips lanes
StateMeaning
built/lockedExperience schema, CRUD, starter save, Trips projection
built/partialcapture/test surfaces and FareHarbor data quality
docs-aheadricher TripCityExperience authoring path
H10. Implementation Snapshot
H2Current state
H3`/experiences` now reads as a public landing surface

Keep it focused on independent travellers, city tours, and single sessions.

H3`/experiences/test` remains the fuller intake and mapping surface

Keep the capture flow regular and explicit.

H3Trips already renders featured experiences as a visible commercial lane

Preserve Trips as the main discovery surface.

H3Project-scoped CRUD exists in `app/experiences/actions/projectExperiences.ts`

Keep the CRUD surface narrow.

H3Experiences are reusable, city-linked commercial units

Use them as supporting inventory.

H3The entity is structurally correct but remains lighter than Trips in execution authority

Do not promote it to a separate commercial root.

H2Next build steps
H3Keep the landing surface conventional and editorial

Use hero-led sections, city cards, and direct entry cues.

H3Keep the intake surface regular and readable

Let the full editor feel like a normal product page rather than a test harness.

H3Preserve Trips as the main consumer of experience inventory

Keep the supporting inventory aligned with Trips.

H3Extend pricing and mapping only where it feeds `Trip -> LineItem -> Offer -> Order`

Keep the bridge explicit.

H3Do not turn Experiences into a separate commercial root

Leave commercial authority in Trips.

H2Prompt starter summary
H3Keep Experiences as a reusable city-linked commercial unit

Use a conventional landing page, a fuller intake page, a Trips featured-experiences lane, and a narrow bridge into trip execution.

H2Prompt starter
Update the Experiences PRD slice using _PRD/experiences/README.md as the source of truth. Keep Experiences as a supporting commercial ingredient layer, not a canonical business root. Preserve the starter capture route at /experiences, the featured-experiences lane inside /trips, and the existing project-scoped CRUD. Keep the next steps tied to Trip composition, LineItems, and Offers. Do not expand scope into a separate booking system or replace Trip execution authority.

Functional note:

  • /experiences is currently a starter capture and mapping surface, not a full commerce engine.
  • app/experiences/actions/projectExperiences.ts covers the direct project-scoped CRUD, while Trips remains the main commercial consumer of experience inventory.
  • The mapping and test surfaces should stay thin so they do not become a parallel execution root.

Prompt starter companion:

Audit Experiences as a support unit. Keep /experiences as a starter capture and mapping route, keep project-scoped CRUD, and preserve the Trips featured-experiences lane as the main discovery surface. Do not promote Experiences to canonical business truth or separate booking authority. If you touch pricing or mapping, keep the bridge explicit to TripCityExperience, LineItems, and Offers.
H21. Product Identity
H3Name

Experiences

H3One-line Definition

Experiences are reusable city-linked commercial units that support Trips, LineItems, and future booking flows.

H3User-facing Purpose

This feature exists so users can:

  • capture a reusable experience record
  • associate the experience with a city and product type
  • surface the experience inside Trips
  • keep a lightweight editor separate from full trip execution
H3Internal Platform Purpose

Inside Molino App, this feature exists to:

  • preserve reusable experience data
  • keep capture and mapping thin
  • feed the Trips featured-experiences lane
  • provide a support layer for LineItems, Offers, and Orders
H22. Current Status
H3Core Complete
  • schema entity exists
  • /experiences starter capture route exists
  • project-scoped CRUD actions exist
  • Trips already surfaces featured experiences
  • city-linking is part of the domain model
H3Code Audit - 2026-04-26

Built / locked

  • Prisma Experience has slug, basePrice, currency, externalId, active, featured, cityId, productTypeId, and relation support for line items and trip-city composition.
  • saveExperienceDraft() persists starter/mapped experience bundles and revalidates /experiences plus /experiences/test.
  • getProjectExperiences(), createExperience(), updateExperience(), and deleteExperience() provide project-scoped CRUD.
  • Trips consumes active experiences through getTripsPublicData() and maps externalId into FareHarbor booking hrefs.

Built / partial

  • The starter capture and test/editor surfaces exist, but are still lighter than Trips.
  • Experience pricing can feed line-item calculations through support code, but Experiences does not own the canonical booking path.

Docs-ahead / pending

  • Richer experience-to-trip composition through TripCityExperience is schema-supported but not yet the main production authoring path.
  • Duplicate/variant handling for city tours and FareHarbor-linked experiences remains a pending data hygiene concern.

Critical next step

Keep Experiences as supporting inventory: improve city/FareHarbor data quality only where it improves Trips lane projection or the eventual LineItem/Offer path.

H3Partial
  • pricing authority is still lighter than Trips
  • richer LineItem generation is not the primary home of this feature
  • booking authority is not centered here
  • action maturity is adequate for capture, not for a full commerce engine
H3Not Built
  • Experiences is not a canonical commercial pipeline root
  • it does not replace Trip execution
  • it does not own order authority
  • it should not become a parallel booking system
H23. Architectural Position

Experiences are a supporting commercial ingredient layer.

  • They are not Trip
  • They are not Offer
  • They are not Order
  • They are not LineItem

They sit before or alongside intent and feed the execution pipeline through Trips and downstream commerce layers.

H24. Relationship to Trips
  • Trips is the primary execution surface
  • Experiences are supporting discovery and ingredient units
  • the featured-experiences lane in Trips is already the correct integration point
  • TripCityExperience remains the composition bridge
H24.1 Naming Alignment

Treat these as the same commercial family in the docs and UI:

  • city tours
  • city highlight tours
  • featured experiences
  • experience records

They all describe the reusable city-linked ingredient layer that Trips surfaces.

Treat these as the same planning family:

  • trip plan
  • flexible trip planning
  • trip planner
  • plans

They describe the intent / planning surface that consumes or orchestrates experiences, not the experience entity itself.

H25. Scope
H3In Scope
  • routes: /experiences, /experiences/[id]
  • app folder: app/experiences/
  • actions: create, update, list, delete, capture, mapping
  • integration points: Trips featured-experiences lane, Trip composition, LineItems, Offers
  • models: Experience, TripCityExperience, supporting product-type mapping
H3Out of Scope
  • a separate commercial booking engine
  • replacing Trips as the primary execution surface
  • duplicating pricing authority outside the established pipeline
H26. Next Steps
H3Priority 1
  • keep /experiences as a thin capture and mapping route
  • keep Trips as the main consumer of experience inventory
  • preserve the featured-experiences lane as the primary surface for discovery
H3Priority 2
  • extend pricing only where it feeds Trip -> LineItem -> Offer -> Order
  • keep the execution bridge explicit and deterministic
  • avoid introducing a second commerce model
H3Priority 3
  • add filtering or list views only if they help Trips or Offers
  • keep the editor and capture flow simple
  • defer richer automation until the core pipeline needs it
H27. Hard Rules
  • experiences never mutate Trips directly
  • experiences never replace the canonical trip pipeline
  • experiences never become the commercial truth source
  • experiences remain derived or user-edited support data
H28. Final Positioning

Experiences are a lightweight reusable commercial ingredient layer that supports Molino’s trip execution pipeline, but they are not the canonical commercial domain root.