Tov+ Tov+

Documentation

Timeline Module Guide

Timeline is the operational run-of-show module for Tov+.

3 min read

Purpose

Timeline is the operational run-of-show module for Tov+.

It provides:

  • occasion-level installation through the module platform
  • event-level timeline enablement
  • planner-managed timeline items with assignments and dependency links
  • vendor-scoped schedule visibility for assigned work
  • guest-safe summary items when an event explicitly enables them

Timeline is not a generic note list. It is the module that captures the ordered operational plan for an event.

Scope model

Timeline is installed once per occasion and enabled per event.

That means:

  • the occasion installation defines the default timeline posture
  • each event enablement decides whether guest-safe summary items may be exposed
  • every timeline item belongs to exactly one event
  • cross-event dependency links are not allowed

The current install config uses default_view_mode.

The current event enablement config uses guest_summary_visible.

Timeline item model

Each timeline item stores:

  • occasion scope and event scope
  • module installation and enablement ids
  • title and optional description
  • starts_at
  • either ends_at, duration_minutes, or both
  • sort_order
  • operational status
  • visibility classification
  • optional owner actor
  • optional location and notes

Statuses are:

  • scheduled
  • in_progress
  • completed
  • blocked
  • cancelled

Visibility values are:

  • internal
  • assigned_vendor
  • guest_summary

internal is planner-only operational detail. assigned_vendor is visible to authorized vendor contexts that are actually assigned to the item. guest_summary is the guest-safe public summary posture.

Assignment model

Timeline assignments attach actors to timeline items.

The baseline assignment roles are:

  • owner
  • support

Assignments can target planner actors, vendor actors, and teams as long as the actor belongs to the same occasion. The server validates actor existence and occasion membership before writes are accepted.

The item-level owner_actor_id remains a convenience field for the primary owner. Assignment rows are the fuller multi-actor model.

Dependency model

Timeline supports explicit dependency edges between items within the same event.

The baseline dependency types are:

  • finish_to_start
  • start_to_start

Each dependency also stores offset_minutes.

Current behavior:

  • predecessor items must already exist
  • predecessor and successor must stay inside the same event
  • self-dependencies are rejected
  • cyclic graphs are rejected

Automatic rescheduling is not implemented in this task. The current implementation captures and validates the dependency graph so later tasks can build rescheduling or critical-path behavior on top of it.

Planner flow

Planner routes are:

  • GET /v1/occasions/:occasion_id/timeline
  • POST /v1/occasions/:occasion_id/timeline/items
  • PATCH /v1/occasions/:occasion_id/timeline/items/:timeline_item_id
  • DELETE /v1/occasions/:occasion_id/timeline/items/:timeline_item_id

The planner dashboard route is:

  • /occasions/:occasionId/timeline

The planner view supports:

  • loading event-aware timeline items
  • creating and editing timeline items
  • setting timing, ordering, status, visibility, location, and notes
  • assigning actors
  • defining dependency links
  • deleting timeline items

The page is intentionally form-first rather than a full gantt-style visualization. It is built to be operationally usable now while leaving room for richer timeline views later.

Vendor flow

Vendor route:

  • GET /v1/vendors/occasions/:occasion_id/timeline

Vendor app route:

  • /occasions/:occasionId/schedule

Vendor visibility rules:

  • an active vendor actor context is required
  • the vendor actor scope includes the active actor plus linked parent/child memberships
  • internal items are always excluded
  • the vendor only sees items that have at least one assignment within that actor scope
  • centralized authorization must still allow resource:timeline_item:view

This gives vendors a practical working schedule without exposing the full planner operations surface.

Guest flow

Guest route:

  • GET /v1/guest/occasions/:occasion_slug/timeline

Guest app route:

  • /schedule

Guest visibility rules:

  • the guest token must resolve to the same occasion
  • the event must be accessible to that guest token
  • Timeline must be enabled for that event
  • the enablement must set guest_summary_visible = true
  • the item visibility must be guest_summary

Guests never receive internal or assigned_vendor items from this API.

Permissions and visibility

Planner management remains centralized. The baseline planner actions are:

  • timeline:list
  • timeline:create
  • timeline:update
  • timeline:delete

Vendor item reads use:

  • resource:timeline_item:view

Timeline therefore follows the existing permission model instead of embedding access rules in frontend code.

Module-platform integration

Timeline is a real module definition in the shared registry.

It currently declares:

  • occasion installation scope
  • event enablement scope
  • actor-domain dependency
  • planner, vendor, and guest surfaces
  • install and enablement config schemas

The server-side timeline queries require the installation to exist and, where relevant, require an event enablement record for the target event.