@echoes-io/models

@echoes-io/models

TypeScript models and validation schemas for Echoes - a multi-POV digital storytelling platform.

Table of Contents

• Overview
• Architecture Context
• Content Structure
  • Hierarchy
  • File Structure Convention
• Models
  • Core Content Models
  • Metadata Models
• Compatibility with @echoes-io/utils
• Installation
• Models Reference
  • Timeline
  • Arc
  • Episode
  • Part
  • Chapter
  • ChapterMetadata
  • TextStats
• Usage
• Development
  • Tech Stack
  • Scripts
• Integration
  • With @echoes-io/utils
  • With @echoes-io/tracker
  • With @echoes-io/rag
• License

Overview

This package provides shared TypeScript interfaces, types, and validation schemas used across the Echoes ecosystem:

• Timeline repositories (content storage)
• Tracker service (content management and API)
• RAG service (semantic search and AI context)
• Web application (frontend)
• CLI tools and utilities

Architecture Context

Echoes is organized as a multi-repository system:

@echoes-io/utils     # Shared utilities (markdown parsing, text stats)
@echoes-io/models    # This package - shared types and schemas
@echoes-io/tracker   # Content management API and database
@echoes-io/rag       # Semantic search and AI context
echoes-timeline-*    # Individual timeline content repositories
echoes-web-app       # Frontend application

Content Structure

Echoes organizes storytelling content in a hierarchical structure:

erDiagram
    Timeline ||--o{ Arc : contains
    Arc ||--o{ Episode : contains
    Episode ||--o{ Part : contains
    Episode ||--o{ Chapter : contains
    Part ||--o{ Chapter : "belongs to"
    
    Timeline {
        string name PK
        string description
    }
    
    Arc {
        string timelineName FK
        string name PK
        int number
        string description
    }
    
    Episode {
        string timelineName FK
        string arcName FK
        int number PK
        string slug
        string title
        string description
    }
    
    Part {
        string timelineName FK
        string arcName FK
        int episodeNumber FK
        int number PK
        string slug
        string title
        string description
    }
    
    Chapter {
        string timelineName FK
        string arcName FK
        int episodeNumber FK
        int partNumber FK
        int number PK
        string pov
        string title
        string date
        string summary
        string location
        string outfit "optional"
        string kink "optional"
        int words
        int characters
        int charactersNoSpaces
        int paragraphs
        int sentences
        int readingTimeMinutes
    }

Hierarchy

Timeline
  └─ Arc (ordered)
      └─ Episode (numbered)
          ├─ Part (numbered, optional subdivision)
          └─ Chapter (numbered, continuous within episode)

Note: Chapter numbering is continuous within an episode and does NOT reset per part.

File Structure Convention

timeline-repo/
├── content/
│   ├── <arc-name>/
│   │   └── <ep01-episode-title>/
│   │       └── <ep01-ch001-pov-title>.md

Naming Conventions:

• Episode numbers: 2-digit padding (ep01, ep02, ep12)
• Chapter numbers: 3-digit padding (ch001, ch005, ch123)
• Slugification: lowercase, hyphens, no special characters
• Example: content/introduction-arc/ep01-first-meeting/ep01-ch005-alice-first-meeting.md

Models

This package defines TypeScript interfaces for:

Core Content Models

• Timeline - Root story container with name and description
• Arc - Story arc within timeline with ordering
• Episode - Episode within arc with numbering, slug, title, description
• Part - Part within episode with numbering, slug, title, description
• Chapter - Individual content file with metadata and stats (content stored in .md files)

Metadata Models

• ChapterMetadata - Frontmatter structure for .md files:
  • Required fields: pov, title, date, timeline, arc, episode (number), part (number), chapter (number), summary, location
  • Optional fields: outfit, kink
• TextStats - Text statistics from content analysis:
  • words, characters, charactersNoSpaces, paragraphs, sentences, readingTimeMinutes

Compatibility with @echoes-io/utils

This package provides the same interfaces as @echoes-io/utils but adds:

• Database-ready models with IDs and relationships
• Zod validation schemas for runtime type checking
• API request/response types for the tracker service
• Extended metadata for content management

// These interfaces match @echoes-io/utils exactly
import type { ChapterMetadata, TextStats } from '@echoes-io/models';

// These are new database models
import type { Timeline, Arc, Episode, Chapter } from '@echoes-io/models';

// These are new validation schemas
import { validateChapterMetadata, validateTimeline } from '@echoes-io/models';

Installation

npm install @echoes-io/models

Models Reference

Timeline

Root container for a story universe.

Field	Type	Key	Description
name	string	PK	Timeline name (unique identifier)
description	string		Timeline description

Example:

const timeline: Timeline = {
  name: 'main-story',
  description: 'The primary storyline',
};

Arc

Story arc within a timeline. Represents major story phases (e.g., "Introduction", "Rising Action").

Field	Type	Key	Description
timelineName	string	FK, PK	Timeline name (foreign key)
name	string	PK	Arc name
number	number		Arc order/number within timeline
description	string		Arc description

Primary Key: (timelineName, name)

Example:

const arc: Arc = {
  timelineName: 'main-story',
  name: 'introduction',
  number: 1,
  description: 'The beginning of the story',
};

Episode

Episode within an arc. Represents story events or time periods.

Field	Type	Key	Description
timelineName	string	FK, PK	Timeline name (foreign key)
arcName	string	FK, PK	Arc name (foreign key)
number	number	PK	Episode number (e.g., 1, 2, 3)
slug	string		Episode slug (URL-friendly)
title	string		Episode title
description	string		Episode description

Primary Key: (timelineName, arcName, number)

Example:

const episode: Episode = {
  timelineName: 'main-story',
  arcName: 'introduction',
  number: 1,
  slug: 'first-meeting',
  title: 'First Meeting',
  description: 'Alice and Bob meet for the first time',
};

Part

Part within an episode. Used for organizing longer episodes into subdivisions.

Field	Type	Key	Description
timelineName	string	FK, PK	Timeline name (foreign key)
arcName	string	FK, PK	Arc name (foreign key)
episodeNumber	number	FK, PK	Episode number (foreign key)
number	number	PK	Part number within episode
slug	string		Part slug (URL-friendly)
title	string		Part title
description	string		Part description

Primary Key: (timelineName, arcName, episodeNumber, number)

Example:

const part: Part = {
  timelineName: 'main-story',
  arcName: 'introduction',
  episodeNumber: 1,
  number: 1,
  slug: 'morning',
  title: 'Morning',
  description: 'The morning scene',
};

Chapter

Individual content file (.md with frontmatter). Extends ChapterMetadata and TextStats from @echoes-io/utils.

Note: Chapter numbering is continuous within an episode and does NOT reset per part.

Structure:

interface Chapter extends ChapterMetadata, TextStats {
  timelineName: string;
  arcName: string;
  episodeNumber: number;
  partNumber: number;
  number: number;
}

Field	Type	Key	Required	Description
Database Keys
timelineName	string	FK, PK	✓	Timeline name (foreign key)
arcName	string	FK, PK	✓	Arc name (foreign key)
episodeNumber	number	FK, PK	✓	Episode number (foreign key)
partNumber	number	FK	✓	Part number (indicates which part the chapter belongs to)
number	number	PK	✓	Chapter number (unique within episode)
From ChapterMetadata
pov	string		✓	Point of view character
title	string		✓	Chapter title
date	string		✓	Chapter date (free text, e.g., "2025-01-01 Monday")
timeline	string		✓	Timeline name (from frontmatter)
arc	string		✓	Arc name (from frontmatter)
episode	number		✓	Episode number (from frontmatter)
part	number		✓	Part number (from frontmatter)
chapter	number		✓	Chapter number (from frontmatter)
summary	string		✓	Brief chapter description
location	string		✓	Chapter location/setting
outfit	string			Character outfit description (optional)
kink	string			Content tags/kinks (optional)
From TextStats
words	number		✓	Total word count
characters	number		✓	Total character count (including spaces)
charactersNoSpaces	number		✓	Character count excluding spaces
paragraphs	number		✓	Number of paragraphs
sentences	number		✓	Number of sentences
readingTimeMinutes	number		✓	Estimated reading time in minutes (200 words/min)

Primary Key: (timelineName, arcName, episodeNumber, number)

Example:

const chapter: Chapter = {
  // Database keys
  timelineName: 'main-story',
  arcName: 'introduction',
  episodeNumber: 1,
  partNumber: 1,
  number: 1,
  // Metadata (from ChapterMetadata)
  pov: 'Alice',
  title: 'First Meeting',
  date: '2025-01-01 Monday',
  timeline: 'main-story',
  arc: 'introduction',
  episode: 1,
  part: 1,
  chapter: 1,
  summary: 'Alice meets Bob at the coffee shop',
  location: 'Coffee Shop',
  outfit: 'Blue dress', // optional
  kink: 'romance', // optional
  // Text statistics (from TextStats)
  words: 1000,
  characters: 5000,
  charactersNoSpaces: 4000,
  paragraphs: 10,
  sentences: 50,
  readingTimeMinutes: 5,
};

ChapterMetadata

Frontmatter structure for .md files. This is the source of truth that gets replicated into the database.

Field	Type	Required	Description
pov	string	✓	Point of view character
title	string	✓	Chapter title
date	string	✓	Chapter date (free text, e.g., "2025-01-01 Monday")
timeline	string	✓	Timeline name
arc	string	✓	Arc name
episode	number	✓	Episode number
part	number	✓	Part number
chapter	number	✓	Chapter number
summary	string	✓	Brief chapter description
location	string	✓	Chapter location/setting
outfit	string		Character outfit description (optional)
kink	string		Content tags/kinks (optional)

Example:

const metadata: ChapterMetadata = {
  pov: 'Alice',
  title: 'First Meeting',
  date: '2025-01-01 Monday',
  timeline: 'main-story',
  arc: 'introduction',
  episode: 1,
  part: 1,
  chapter: 1,
  summary: 'Alice meets Bob at the coffee shop',
  location: 'Coffee Shop',
};

TextStats

Text statistics calculated from content analysis (via @echoes-io/utils).

Field	Type	Description
words	number	Total word count
characters	number	Total character count (including spaces)
charactersNoSpaces	number	Character count excluding spaces
paragraphs	number	Number of paragraphs
sentences	number	Number of sentences
readingTimeMinutes	number	Estimated reading time in minutes (200 words/min)

Example:

const stats: TextStats = {
  words: 1000,
  characters: 5000,
  charactersNoSpaces: 4000,
  paragraphs: 10,
  sentences: 50,
  readingTimeMinutes: 5,
};

Usage

import { 
  Timeline, 
  Arc, 
  Episode, 
  Part, 
  Chapter, 
  ChapterMetadata,
  validateTimeline,
  validateChapter,
} from '@echoes-io/models';

// Type-safe content structures
const timeline: Timeline = {
  name: 'main-story',
  description: 'The primary storyline',
};

const arc: Arc = {
  timelineName: 'main-story',
  name: 'introduction',
  number: 1,
  description: 'The beginning of the story',
};

const episode: Episode = {
  timelineName: 'main-story',
  arcName: 'introduction',
  number: 1,
  slug: 'first-meeting',
  title: 'First Meeting',
  description: 'Alice and Bob meet for the first time',
};

const part: Part = {
  timelineName: 'main-story',
  arcName: 'introduction',
  episodeNumber: 1,
  number: 1,
  slug: 'morning',
  title: 'Morning',
  description: 'The morning scene',
};

const chapter: Chapter = {
  timelineName: 'main-story',
  arcName: 'introduction',
  episodeNumber: 1,
  partNumber: 1,
  number: 1,
  pov: 'Alice',
  title: 'First Meeting',
  date: '2025-01-01 Monday',
  timeline: 'main-story',
  arc: 'introduction',
  episode: 1,
  part: 1,
  chapter: 1,
  summary: 'Alice meets Bob at the coffee shop',
  location: 'Coffee Shop',
  words: 1000,
  characters: 5000,
  charactersNoSpaces: 4000,
  paragraphs: 10,
  sentences: 50,
  readingTimeMinutes: 5,
};

// Validation with Zod
try {
  validateTimeline(timeline);
  validateChapter(chapter);
  console.log('Valid!');
} catch (error) {
  console.error('Validation error:', error);
}

Development

Tech Stack

• Language: TypeScript (strict mode)
• Validation: Zod (planned)
• Testing: Vitest
• Linting: Biome

Scripts

# Run tests
npm test

# Type checking
npm run type-check

# Lint code
npm run lint

Integration

With @echoes-io/utils

• Uses ChapterMetadata interface from this package
• Provides validation for parsed frontmatter

With @echoes-io/tracker

• Implements these models in database schema
• Uses types for API endpoints and operations

With @echoes-io/rag

• Uses models for content indexing
• Provides types for semantic search results

License

MIT