#project #storytellersuite

Storyteller Suite - Project Overview

What Is This?

Storyteller Suite is an Obsidian plugin for story planning, worldbuilding, timeline management, manuscript workflows, maps, and campaign/session play. Its core data model stays vault-native by storing entities as Markdown notes with YAML frontmatter instead of opaque database records.

Recent Update Snapshot

• 2026-03-15 - v1.7.4: startup-time patch shipped, based on the release/version bump commits.
• 2026-03-22 and 2026-03-29: follow-up maintenance commits normalized contributor identity/attribution files rather than adding new end-user features.
• Current 1.7.x codebase: includes campaign mode, redesigned timeline/Gantt tooling, compile workflows, richer note integration, and in-app onboarding/update guides.

Key Information

Current Feature Areas

Story and Worldbuilding Entities

• Core entities: characters, locations, events, items, references, chapters, scenes, and books.
• Expanded worldbuilding entities: groups, compendium entries, cultures, economies, and magic systems.
• Story organization: multi-story mode, One Story Mode, and configurable/custom folders.

Interactive Views

• Dashboard + analytics: main management view plus analytics tooling.
• Timeline + Gantt: grouped lanes, dependencies, progress overlays, forks, eras, conflict detection, exports, and watched-note support.
• Maps: dedicated MapView with image maps, real-world tile maps, hierarchy breadcrumbs, and multi-entity placement.
• Graphs: relationship network graph plus a dedicated scene graph view.
• Writing tools: dedicated writing panel/view support.

Campaign / Session Play

• Campaign view: session select + play mode in CampaignView.ts.
• DM tools: party HP and conditions, active actor selection, inventory syncing, lore surfacing, faction/group standings, encounter widgets, and branch-aware scene progression.
• Persistence: session autosave and session-log writing are built into the campaign flow.

Compile, Templates, and Import

• Compile system: reusable workflows, compile steps, scene ordering, and word-count tracking in src/compile/.
• Template system: entity-to-template and note-to-template conversion, variable substitution, validation, migration, and note-backed storage.
• Import parsers: DOCX, EPUB, Fountain, HTML, JSON, Markdown, ODT, PDF, plain text, and RTF.

Data / Note Integration

• Markdown-first storage: entities remain readable/editable outside the plugin UI.
• Entity syncing: EntitySyncService keeps cross-entity relationships in sync.
• Better note compatibility: groups are stored as real notes, and relationship properties favor note-linkable names where possible.

Architecture Highlights

1. Plugin entry: src/main.ts is the main plugin entry point and view/command registration hub.
2. Settings: src/StorytellerSuiteSettingTab.ts manages the large settings surface.
3. Views: src/views/ currently contains DashboardView, AnalyticsDashboardView, CampaignView, TimelineView, MapView, NetworkGraphView, SceneGraphView, and WritingPanelView.
4. Compile subsystem: src/compile/ contains CompileEngine, SceneOrderManager, WordCountTracker, and workflow steps.
5. Services: src/services/EntitySyncService.ts and src/services/LocationService.ts handle shared data logic.
6. Templates: src/templates/ contains storage, conversion, validation, and application logic.
7. YAML handling: src/yaml/EntitySections.ts centralizes section/frontmatter rules.
8. Tutorial + onboarding: src/tutorial/ supports built-in guide/update content.
9. Localization: src/i18n/locales/ currently ships en, de, es, fr, and zh.

Data Model

Storyteller Suite stores story data as Markdown files with YAML frontmatter.

---
name: Character Name
description: Brief description
tags:
  - protagonist
  - warrior
customFields:
  weapon: Sword
  allegiance: Kingdom
---

## Description
Full description goes here...

## Backstory
Character history...

By default, multi-story mode uses folders like:

• StorytellerSuite/Stories/[StoryName]/Characters/
• StorytellerSuite/Stories/[StoryName]/Locations/
• StorytellerSuite/Stories/[StoryName]/Events/
• StorytellerSuite/Stories/[StoryName]/Items/
• StorytellerSuite/Stories/[StoryName]/Groups/
• StorytellerSuite/Stories/[StoryName]/References/
• StorytellerSuite/Stories/[StoryName]/Chapters/
• StorytellerSuite/Stories/[StoryName]/Scenes/
• StorytellerSuite/Stories/[StoryName]/Books/
• StorytellerSuite/Stories/[StoryName]/Maps/
• StorytellerSuite/Stories/[StoryName]/Compendium/
• StorytellerSuite/Stories/[StoryName]/Cultures/
• StorytellerSuite/Stories/[StoryName]/Economies/
• StorytellerSuite/Stories/[StoryName]/MagicSystems/
• StorytellerSuite/Stories/[StoryName]/Sessions/

Technology Stack

Development Workflow

# Install dependencies
npm install

# Development build
npm run dev

# Production build
npm run build

# Unit/integration tests
npm run test

# E2E tests
npm run test:e2e

# Playwright AI-focused tests
npm run test:ai

GitHub Actions currently verifies type-check + build in CI, while the repo also includes local test commands for broader coverage.

Key Directories

src/
|- main.ts
|- StorytellerSuiteSettingTab.ts
|- commands/
|- compile/
|- components/
|- i18n/
|- import/
|- leaflet/
|- modals/
|- services/
|- templates/
|- tutorial/
|- views/
|- yaml/
`- utils/

Resources & Links

• [[01-Project-Structure]] - Detailed file organization
• [[02-Core-Plugin-Architecture]] - Main plugin class and settings
• 03-Entity-Management - Entity types and operations
• 04-Modals-System - Modal dialog patterns
• 05-Timeline-System - Timeline and Gantt features
• 06-Map-System - Leaflet map integration
• 07-Template-System - Template creation and usage
• 08-Import-Export - Document parsing and compilation
• 09-Internationalization - Translation system
• 10-Build-And-Testing - Development workflow
• GitHub Repository
• Changelog
• Release Notes