TableQuest - World Building & Narrative Structure Visualizer

A comprehensive tool for fiction writers, TTRPG gamemasters, and world builders to visualize story arcs, character relationships, dependencies, and timelines.

Features

• Character Management: Create and manage complex characters with flexible attributes
• Story Arc Visualization: Interactive timeline view of narrative structure
• Relationship Networks: Force-directed graphs showing character connections
• Dependency Mapping: Visualize story dependencies and avoid plot holes
• Real-time Collaboration: Multi-user editing with Supabase backend
• Export Integration: Compatible with popular writing software

Tech Stack

• Frontend: React 18 + TypeScript + Vite
• Styling: Tailwind CSS 3.x
• Backend: Supabase (PostgreSQL + Auth + Real-time)
• Visualization: D3.js v7
• State Management: Zustand
• Routing: React Router 6
• Forms: React Hook Form + Zod validation

Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• Supabase account

Installation

1. Clone the repository:

git clone <repository-url>
cd tablequest

1. Install dependencies:

npm install

1. Set up environment variables:

cp .env.example .env.local

1. Update .env.local with your Supabase credentials:

VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_PUBLISHABLE_KEY=your_supabase_publishable_key

1. Start the development server:

npm run dev

1. Open http://localhost:5173 in your browser

Database Setup

The application uses Supabase for data storage. The database schema is automatically applied when you first run the application.

For manual setup, run the SQL schema found in database_schema.sql in your Supabase SQL editor.

Project Structure

src/
├── components/           # Reusable UI components
│   ├── ui/              # Basic UI primitives
│   ├── forms/           # Form components
│   ├── visualizations/  # D3.js visualization components
│   └── layout/          # Layout components
├── pages/               # Route-level page components
├── hooks/               # Custom React hooks
├── stores/              # Zustand stores
├── services/            # API services and utilities
├── types/               # TypeScript type definitions
├── utils/               # Utility functions
└── constants/           # App constants and configurations

Development

Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build
• npm run lint - Run ESLint
• npm run type-check - Run TypeScript type checking

Code Quality

This project uses:

• ESLint for code linting
• Prettier for code formatting
• TypeScript strict mode
• Conventional commits

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

Database Schema

The application uses these main tables:

• projects - Main project containers
• characters - Character entities with attributes
• story_arcs - Hierarchical story structure
• events - Atomic story units (scenes, plot points)
• character_relationships - Character connections
• story_dependencies - Dependencies between story elements
• locations - World/location hierarchy

All tables include Row Level Security (RLS) policies to ensure data privacy.

Deployment

Vercel (Recommended)

1. Connect your repository to Vercel
2. Set environment variables in Vercel dashboard
3. Deploy automatically on push to main branch

Manual Deployment

1. Build the project:

npm run build

1. Deploy the dist folder to your hosting provider

Environment Variables

• VITE_SUPABASE_URL - Your Supabase project URL
• VITE_SUPABASE_PUBLISHABLE_KEY - Your Supabase publishable key
• VITE_APP_TITLE - Application title (optional)
• VITE_APP_VERSION - Application version (optional)
• VITE_ENVIRONMENT - Environment (development/production)

Troubleshooting

Common Issues

Authentication errors: Verify your Supabase URL and key are correct in .env.local

Database connection issues: Ensure your Supabase project is active and the database schema is applied

Build errors: Clear node_modules and reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

TypeScript errors: Ensure you're using TypeScript 5.0+ and all dependencies are up to date

Performance

For optimal performance with large datasets:

• Use pagination for character lists (50+ items)
• Enable virtualization for large visualizations
• Consider using React.memo for expensive components

License

[Add your license here]

Support

For questions and support:

• Create an issue on GitHub
• Check the documentation in /docs
• Review the troubleshooting guide above