Content Timeline System

Overview

The Content Timeline System is the core organizational feature of the Progressive World-Building Platform. It provides a structured way for creators to plan, track, and reveal world-building content over time. Each timeline update represents a themed content release -- such as "Session 1: The Blood Moon" or "Chapter 3: The Siege of Ironhold" -- that bundles related items into a cohesive unit with sections, items, and sub-items.

For creators (Owners, Storytellers, Co-Creators), the timeline is a planning and tracking tool. It answers: what content exists, what is being worked on, what is still just an idea, and what has been retired. For consumers (Players, Viewers), the timeline is a roadmap showing what has been published and what is available to explore.

The system supports a full content lifecycle through its development status model. Content moves from early concepts through active development into published availability, and eventually into a legacy archive. Combined with drag-and-drop reordering, color-coded themes, and pending item placeholders, the timeline provides a flexible but structured framework for managing creative projects of any scale.

Goals

• Provide a hierarchical content organization system (Timeline Update > Section > Item > Sub-Item)
• Support a clear development lifecycle for content (Concept > In Development > Published > Legacy)
• Enable drag-and-drop reordering at every level of the hierarchy
• Allow creators to signal upcoming content via pending item placeholders
• Enforce role-based visibility so Players and Viewers only see published content
• Support color-coded timeline updates for visual theme categorization
• Enable linking published items to external content (URLs to blog posts, wiki pages, sessions)
• Provide bulk status operations for efficient content management

User Stories

Game Master / Storyteller

• As a GM, I want to create a timeline update for each game session so I can track what content was introduced when
• As a GM, I want to organize items into sections (e.g., "NPCs Introduced", "Locations Revealed") so content is easy to find
• As a GM, I want to mark items as "pending" so my players see that something is coming without knowing what it is
• As a GM, I want to change an item's status from In Development to Published when I reveal it in a session
• As a GM, I want to bulk-publish all items in a section after a session concludes

Writer

• As a writer, I want to create timeline updates for each chapter or arc so I can track my world-building across the narrative
• As a writer, I want to add sub-items beneath main items to capture related details (e.g., a character's key relationships listed under the character item)
• As a writer, I want to reorder timeline updates to reflect changes in my narrative structure
• As a writer, I want to color-code timeline updates by storyline so I can visually distinguish parallel arcs

Player / Reader

• As a player, I want to browse published timeline updates to see what content is available to me
• As a player, I want to click through from a timeline item to the actual content (via external URL)
• As a player, I want to see pending placeholders so I know more content is on the way

Functional Description

Timeline Updates

A timeline update is the top-level organizational unit. It represents a themed content release -- a game session, a book chapter, a story arc, or any other logical grouping chosen by the creator.

Properties:

• Title -- descriptive name (e.g., "Session 5: The Blood Moon")
• Color -- one of five theme colors (red, blue, green, purple, amber) for visual categorization
• Status -- development status that controls visibility (see Status Lifecycle below)
• Order -- integer controlling display position among sibling timeline updates
• Sequence Number -- project-scoped public identifier (e.g., the "3" in VNO-3)

Timeline updates are aggregate roots. All modifications to their child sections, items, and sub-items are performed through the aggregate boundary to maintain consistency.

Sections

Sections subdivide a timeline update into labeled groups. A timeline update might contain sections like "New Characters", "Revealed Locations", and "Plot Developments".

Properties:

• Label -- section heading text
• Order -- integer controlling display position within the parent timeline update

Sections have no independent status; they inherit visibility from their parent timeline update.

Items

Items are the individual pieces of content tracked by the timeline. Each item lives within a section and represents a single deliverable -- a character, a location, a plot point, a rule change, or any other discrete content element.

Properties:

• Name -- item title (displayed even for pending items if the creator chooses, or left as a placeholder)
• Description -- optional rich text providing additional detail about the item
• URL -- optional external link pointing to the full content (blog post, wiki page, etc.)
• IsPending -- boolean flag indicating this item is planned but not yet finalized
• Order -- integer controlling display position within the parent section
• ParentItemId -- optional self-referencing foreign key enabling one level of sub-items

Sub-Items

Sub-items are items with a ParentItemId set. They appear nested beneath their parent item in the UI. Sub-items follow the same data model as items but are displayed in a subordinate position. Only one level of nesting is supported -- a sub-item cannot have its own sub-items.

Pending Items

A pending item is any item where IsPending = true. Pending items serve as placeholders indicating that content is planned for this timeline update but has not yet been finalized. The creator may choose to give the pending item a descriptive name (e.g., "Mystery NPC") or leave it vague (e.g., "Coming Soon").

Pending items are visible to all roles that can see the parent timeline update, but they communicate to consumers that the content is not yet complete.

External Links

Items may include an optional URL field for linking to external content. This is most useful for published items where the timeline serves as an index pointing to detailed content hosted elsewhere -- a blog post, a wiki page, a Google Doc, or a session recording. The URL is validated for basic format correctness but no URL probing is performed.

Color Coding

Each timeline update is assigned one of five colors: red, blue, green, purple, or amber. Colors have no system-enforced semantic meaning; creators use them freely for visual organization. Common patterns include color-coding by storyline, by content type, or by urgency.

Status Lifecycle

Every timeline update carries a development status that controls its visibility and indicates its maturity. The four statuses form a lifecycle:

Status definitions:

Status	Meaning	Visible to Players/Viewers
Concept	Early idea, not yet being actively developed	No
In Development	Actively being worked on by creators	No
Published	Released and available to all project members	Yes
Legacy	Archived; still viewable but no longer active	Yes

Allowed transitions:

• Concept -> In Development (begin active work)
• In Development -> Published (release to audience)
• Published -> Legacy (archive)
• In Development -> Concept (revert to ideation)
• Published -> In Development (pull back for revision)
• Legacy -> Published (reactivate)

The status applies at the timeline update level. All sections and items within a timeline update inherit its visibility. There is no per-item status override -- if a timeline update is In Development, all of its items are hidden from Players and Viewers.

Bulk Status Changes

Creators with appropriate permissions can change the status of multiple timeline updates at once. The bulk status endpoint accepts a list of timeline update sequence numbers and a target status. The system validates that each requested transition is allowed (per the state machine above) and applies the changes atomically. If any transition is invalid, the entire batch is rejected.

Reordering

All three levels of the hierarchy (timeline updates, sections, items) support drag-and-drop reordering. Reordering is implemented via integer Order fields and dedicated reorder endpoints.

Reorder operation:

When a reorder request arrives, the client sends the complete ordered list of IDs for the siblings being reordered. The backend:

1. Validates that all IDs belong to the same parent (same project for timeline updates, same timeline update for sections, same section for items)
2. Validates that the list contains exactly the current set of siblings (no additions or removals)
3. Assigns new sequential Order values (0, 1, 2, ...) based on the submitted order
4. Persists the changes in a single transaction

This approach avoids floating-point gaps, fractional ordering, or complex gap-filling algorithms. The client always sends the complete sibling list, so the backend can safely reassign contiguous integers.

Role-Based Visibility

The timeline system enforces visibility rules through IPermissionService:

Role	What they see
Owner	All timeline updates regardless of status
Storyteller	All timeline updates regardless of status
Co-Creator	All timeline updates regardless of status
Player	Only Published and Legacy timeline updates
Viewer	Only Published and Legacy timeline updates

When a Player or Viewer requests the timeline list, the API response omits Concept and In Development timeline updates entirely. There is no indication that hidden content exists -- the response simply contains fewer items. This follows the platform-wide "full omission" visibility policy (see Permission & Visibility).

Data Flow

Entity Relationship Diagram

Content Creation Flow

Reorder Operation Flow

Timeline View Flow (Role-Based Visibility)

Key Components

TimelineController

Handles all HTTP endpoints for timeline updates, sections, and items. Routes requests to the appropriate service methods. Performs initial request validation (model binding, format checks).

TimelineService

Core business logic for timeline operations. Coordinates between the permission system and the data layer. Responsible for:

• Creating, updating, and deleting timeline updates, sections, and items
• Enforcing the status state machine (validating transitions)
• Applying bulk status changes atomically
• Performing reorder operations
• Filtering results by role-based visibility

IPermissionService

Consulted on every operation to verify the requesting user has the appropriate role. The timeline system requires CanEditTimeline for all write operations and applies visibility filtering on all read operations.

TimelineUpdate (Aggregate Root)

The domain entity that owns sections and items. State changes to child entities are coordinated through the aggregate root to maintain invariants (e.g., sub-items cannot exceed one level of nesting, order values remain contiguous after operations).

Domain Events

The TimelineUpdate aggregate root raises domain events on significant state changes:

• TimelineUpdateCreatedEvent -- triggers activity feed entry
• TimelineStatusChangedEvent -- triggers notifications to relevant project members (especially when publishing)
• TimelineReorderedEvent -- triggers real-time UI updates via SignalR

Feature Interactions

Feature	Interaction
Project Management	Timeline updates belong to a project. Project deletion cascades to all timeline data. Project key is used in all timeline API routes. Sequence numbers are allocated from the project's counter.
Permission & Visibility	Every timeline read and write operation checks permissions. Visibility filtering determines which timeline updates appear in responses for Players/Viewers.
Version History & Changelog	Timeline updates are a primary target for version history. Changelog entries are attached to individual timeline updates.
Real-time & Collaboration	Reorder operations, status changes, and new content trigger SignalR notifications to connected clients.
Search & Navigation	Timeline updates, sections, and items are indexed for project-wide search.
Authentication	All timeline endpoints require authentication. The current user identity is used for audit fields and permission checks.

Edge Cases & Error Handling

Reorder Conflicts

If two users attempt to reorder sections in the same timeline simultaneously, the second request may submit stale IDs. The backend validates that the submitted ID set matches the current siblings. If a section was added or removed between the client loading the UI and submitting the reorder, the request is rejected with a conflict error. The client must reload and retry.

Deleting a Timeline Update with Children

Deleting a timeline update cascades to all child sections, items, and sub-items. The operation is performed in a single transaction. Changelog entries associated with the timeline update are also deleted. A confirmation step on the client side is recommended but not enforced by the API.

Deleting a Section with Items

Deleting a section cascades to all child items and sub-items. Order values for remaining sections within the timeline update are not automatically recompacted -- gaps in ordering are tolerable and will be corrected on the next explicit reorder operation.

Deleting an Item with Sub-Items

Deleting a parent item cascades to all sub-items. This is consistent with the aggregate root pattern -- the parent owns its children.

Sub-Item Nesting Depth

Only one level of sub-items is allowed. If a request attempts to create a sub-item beneath another sub-item (i.e., the specified ParentItemId refers to an item that already has a ParentItemId), the request is rejected with a validation error.

Invalid Status Transitions

Attempting a disallowed status transition (e.g., Concept directly to Published) returns a validation error indicating the allowed transitions from the current status.

Bulk Status - Partial Validity

When a bulk status change request includes timeline updates with different current statuses, some transitions may be valid and others invalid. The system rejects the entire batch if any single transition is invalid, returning details about which transitions failed. This prevents partial updates that could leave the project in a confusing state.

Pending Items with URLs

A pending item should not have a URL set since it represents content that is not yet finalized. The system allows it but the client should present a warning. This is not enforced as a hard constraint because creators may want to link to draft content.

Empty Sections

Sections with no items are allowed. A creator may set up the section structure before populating it with items.

Maximum Limits

To prevent abuse, the system enforces reasonable limits:

• Maximum 100 timeline updates per project
• Maximum 20 sections per timeline update
• Maximum 200 items per section
• Maximum 20 sub-items per parent item

These limits are configurable and may be adjusted based on usage patterns.

Phase & Priority

Phase: Phase 1 (Core Timeline & Projects)

The Content Timeline System is a foundational feature and one of the first to be implemented. It depends only on the Authentication and Project Management features being in place. Many other features -- Version History, Changelog, Search, and Collaboration -- build on top of the timeline system.