Pakobbix/rpg-companion-sillytavern
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
242eb6ed5718b65e7a689ffc72c59cf834154e2c
rpg-companion-sillytavern/docs
T
History

README.md

RPG Companion Documentation

This directory contains all design and implementation documentation for RPG Companion v2.0.

Documentation Index

Implementation

  • IMPLEMENTATION_PLAN.md - Complete implementation roadmap
    • 8 epics with detailed tasks and subtasks
    • Checkboxes for progress tracking
    • Dependencies and timeline estimates
    • Each task builds on the previous one

Feature Design

  • Widget Dashboard System - Dashboard architecture

    • Dynamic tabs with create/rename/delete
    • Widget grid system with drag-and-drop
    • Edit mode and layout persistence
    • Mobile responsive design
    • Widget development guide

  • Schema System Architecture - Schema system design

    • Entity-Component-System (ECS) pattern
    • YAML-based system definitions
    • Formula engine with @ references
    • Character instance validation
    • Storage layer (IndexedDB + File System API)
    • AI prompt generation and parsing

Quick Start

For Developers

  1. Start here: Read IMPLEMENTATION_PLAN.md
  2. Understand the dashboard: Read Widget Dashboard System
  3. Understand schemas: Read Schema System Architecture
  4. Pick a task: Find unchecked tasks in implementation plan
  5. Build incrementally: Each task builds on previous ones

For Contributors

  • All major features documented in /docs/features/
  • Implementation plan tracks progress with checkboxes
  • Each epic is a major deliverable
  • Commit messages should reference task numbers
  • Example: feat: implement grid engine core (Task 1.1)

Architecture Overview

RPG Companion v2.0 Architecture

┌─────────────────────────────────────────────────────────┐
│                   User Interface Layer                   │
│  ┌───────────────┐  ┌───────────────┐  ┌──────────────┐│
│  │ Tab Navigator │  │ Widget Grid   │  │ Edit Mode UI ││
│  └───────────────┘  └───────────────┘  └──────────────┘│
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                  Widget System Layer                     │
│  ┌───────────────┐  ┌───────────────┐  ┌──────────────┐│
│  │ Widget        │  │ Grid Engine   │  │ Drag & Drop  ││
│  │ Registry      │  │               │  │ Handler      ││
│  └───────────────┘  └───────────────┘  └──────────────┘│
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                   Schema System Layer                    │
│  ┌───────────────┐  ┌───────────────┐  ┌──────────────┐│
│  │ Schema        │  │ Formula       │  │ Character    ││
│  │ Validator     │  │ Engine        │  │ Manager      ││
│  └───────────────┘  └───────────────┘  └──────────────┘│
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                   Storage Layer                          │
│  ┌───────────────┐  ┌───────────────┐  ┌──────────────┐│
│  │ IndexedDB     │  │ File System   │  │ Extension    ││
│  │               │  │ Access API    │  │ Settings     ││
│  └───────────────┘  └───────────────┘  └──────────────┘│
└─────────────────────────────────────────────────────────┘

Key Concepts

Widget Dashboard

  • Dynamic Tabs: Users create unlimited tabs with custom names
  • Widget Grid: 12-column responsive grid with drag-and-drop
  • Edit Mode: Visual editor for arranging widgets
  • Persistence: Layouts save automatically

Schema System

  • System Definition: YAML files define RPG system rules
  • Character Instance: JSON data validated against schema
  • Formula Engine: Calculate derived stats with @ references
  • AI Integration: Dynamic prompts and parsing based on schema

Progressive Enhancement

  • No Modes: Single flexible system with toggles
  • Backward Compatible: Existing features work without schemas
  • Opt-In Complexity: Users enable advanced features when ready

Epics Overview

# Epic Status Duration Description
1 Dashboard Infrastructure Not Started 2 weeks Core grid engine, tabs, drag-and-drop
2 Widget Conversion Not Started 2-3 weeks Convert existing sections to widgets
3 Schema Infrastructure Not Started 3-4 weeks YAML parser, formula engine, validation
4 Schema-Driven Widgets Not Started 3-4 weeks Widgets that render from schemas
5 Schema Editor UI Not Started 2-3 weeks YAML editor and visual builder
6 AI Integration Not Started 2-3 weeks Schema-based prompts and parsing
7 Polish & Mobile Not Started 2-3 weeks Responsive, animations, accessibility
8 Documentation Not Started 1-2 weeks User docs, migration, templates

Total Estimated Time: 12-14 weeks (3-3.5 months)

Design Principles

KISS (Keep It Simple, Stupid)

  • Vanilla JavaScript, no frameworks
  • Progressive enhancement over feature flags
  • Clear APIs over clever abstractions

User Freedom

"This is SillyTavern - users should be able to do whatever the fuck they want"

  • No arbitrary limitations
  • Everything customizable
  • Full GUI editing
  • Import/export everything

Backward Compatibility

  • Existing features must keep working
  • Graceful fallbacks everywhere
  • Migration wizard for v1.x users
  • No data loss scenarios

Performance First

  • Widgets lazy-load
  • Formulas memoized
  • Drag-and-drop throttled
  • Mobile optimized

Contributing

Before Starting a Task

  1. Read the task description in IMPLEMENTATION_PLAN.md
  2. Check dependencies are complete
  3. Review relevant design docs
  4. Understand acceptance criteria

While Working

  1. Mark task in progress (comment or [~])
  2. Follow code style in CLAUDE.md
  3. Test incrementally
  4. Check console for errors
  5. Add debug logging

After Completing

  1. Test acceptance criteria
  2. Mark task complete ([x])
  3. Commit with conventional commit message
  4. Update epic progress
  5. Document any blockers or deviations

Commit Message Format

type(scope): description

Examples:
feat(dashboard): implement grid engine core (Task 1.1)
fix(widgets): resolve user stats rendering bug
docs(schema): add formula engine examples
refactor(storage): optimize IndexedDB queries

Testing Strategy

Manual Testing

  • Test in SillyTavern with extension enabled
  • Check console for errors
  • Test on different screen sizes
  • Verify data persistence
  • Test edge cases

Browser Compatibility

  • Chrome/Chromium (primary)
  • Firefox
  • Safari (if possible)
  • Mobile browsers

Accessibility

  • Keyboard navigation
  • Screen reader support
  • Focus indicators
  • Color contrast

Support

Getting Help

  • Check CLAUDE.md for development guidelines
  • Review relevant design docs in /docs/features/
  • Check implementation plan for dependencies
  • Ask questions in Discord

Reporting Issues

When stuck or blocked:

  • Document the blocker in implementation plan
  • Include error messages and logs
  • Describe what you tried
  • Note which task is blocked

Future Enhancements

Ideas for post-v2.0:

  • Widget marketplace for community widgets
  • Layout templates for different RPG systems
  • Widget linking (skills affect stats, etc.)
  • Conditional widget visibility
  • Real-time collaboration
  • Cloud sync
  • Advanced formula functions
  • Visual node-based formula editor
  • Drag-and-drop formula builder

License

See LICENSE for details (AGPL-3.0).

Last Updated: 2025-10-23 Version: 2.0.0-dev

Reference in New Issue View Git Blame Copy Permalink