Skip to content

README.md

Latest commit

 

History

History
216 lines (167 loc) · 9.12 KB

README.md

File metadata and controls

216 lines (167 loc) · 9.12 KB
Raw

Aetheria World Data System

A comprehensive system for managing and sharing fantasy world data, featuring both AI-optimized RAG documentation and beautiful public websites.

🌟 What You Get

🤖 AI-Optimized Documentation

Generate consolidated markdown files specifically designed for RAG (Retrieval Augmented Generation) systems and vector databases. Perfect for loading into pgvector or other vector storage systems.

🌐 Public Documentation

Beautiful, responsive SolidJS website automatically deployed to GitHub Pages with hash routing and mobile-friendly design.

📊 Structured Data

JSON-based data with automatic TypeScript types, combined with rich markdown documentation.

🚀 Quick Start

View the Live Site

Your world data is automatically published at: https://rjordan.github.io/Aetheria

Make Changes

  1. Edit data files in /site/src/data/ or page content in /site/src/pages/
  2. Commit and push to GitHub
  3. GitHub Actions automatically rebuilds and deploys your site!

Development

# Preview site locally (Node.js)
./dev.sh site

# Preview site locally (Bun - faster)
./dev.sh site-bun

# Generate AI-optimized docs for RAG systems
./dev.sh package

# Deploy changes to GitHub Pages
git add . && git commit -m "Update content" && git push

🔨 Build Commands

The project uses dotenv for clean environment management:

# Development server (uses .env)
npm run dev

# Production build (uses .env)
npm run build

# GitHub Pages build (uses .env.github)
npm run build:github

# Preview production build
npm run preview

Environment Files

  • .env - Development defaults (not committed)
  • .env.example - Template with all options
  • .env.github - GitHub Pages configuration

🤖 AI-Optimized Documentation

The system generates comprehensive markdown documentation specifically optimized for AI consumption and RAG systems:

Quick Start for AI Integration

# Generate AI-optimized documentation
./dev.sh package

# This creates a timestamped ZIP file with:
# - Consolidated reference documents
# - Individual entity files
# - Cross-reference mappings
# - Master index and navigation

What You Get

  • Consolidated Files: complete-world-overview.md, all-magic.md, all-characters.md
  • Individual References: Detailed files for each entity (regions, characters, magic schools)
  • Cross-References: Explicit relationship mapping between entities
  • Vector-Ready: Perfect for chunking and loading into pgvector or similar systems
  • GitHub Releases: Automated ZIP generation and publishing via GitHub Actions

Perfect for RAG Systems

The generated documentation is specifically designed for vector databases:

  • Semantic Completeness: Each document contains full context
  • Chunk-Friendly: Natural breaks for vector database chunking
  • Relationship Mapping: Explicit entity connections for better retrieval
  • Comprehensive Coverage: Both individual and consolidated views

Generic Data Loading Interface

The site uses a configurable data loading system that works with static files or APIs:

// Runtime loading via HTTP fetch (cached automatically)
const magicData = await fetchMagicData()  // GET ${DATA_ENDPOINT}/magic.json
const classData = await fetchClassesData()  // GET ${DATA_ENDPOINT}/classes.json

Environment Configuration

# Copy .env.example to .env and customize
cp .env.example .env

# Default configuration (.env)
VITE_DATA_ENDPOINT=/data      # Data source endpoint
AETHERIA_BASE_PATH=/          # Site base path

# Example configurations:
VITE_DATA_ENDPOINT=https://api.example.com/aetheria/data  # Remote API
VITE_DATA_ENDPOINT=http://localhost:3000/api/v1/data     # Local API server
AETHERIA_BASE_PATH=/Aetheria/                            # GitHub Pages path

Data Architecture

  • Dotenv Integration: Clean environment variable management with .env files
  • Multiple Environments: Separate configs for development, GitHub Pages, etc.
  • Static Files: JSON files in /public/data/ served at /data/ URLs
  • Dynamic APIs: Any HTTP endpoint returning JSON with the same structure
  • Runtime Loading: Uses standard fetch() calls, no compile-time dependencies
  • Automatic Caching: In-memory cache prevents repeated requests

Data Structure Examples

  • magic.json: Contains magic.schools and magic.spells data
  • classes.json: Contains classes.primary and classes.specialized data
  • Other files: Equipment, organizations, creatures, site configuration

Benefits

  • Environment Configurable: Switch between static files and APIs via ENV vars

  • Zero Bundle Impact: JSON files not included in JavaScript bundle

  • Offline Support: Service Worker provides offline functionality with cached data

  • Intelligent Caching: Network-first for fresh data, cache fallback for offline

  • API-Ready: Drop-in replacement with real web services

  • Development Friendly: Works with local files during development

  • Production Flexible: Can serve from CDN, API, or static files## 📁 Project Structure

  • /content/ - 📝 Narrative content (Markdown) - Prose, lore, and instructional text

  • /site/public/data/ - 🔢 Structured data (JSON) - Lists, stats, and attributes

  • /site/ - SolidJS application with data and pages

    • /src/pages/ - SolidJS page components

  • /docs/ - Generated static site (GitHub Pages output)

  • /ai-docs/ - Generated AI-optimized documentation (excluded from git)

  • /generate-ai-docs.js - AI documentation generator script

  • /dev.sh - Development workflow script

  • .github/workflows/ - Automated deployment and AI docs generation

Content Management Philosophy

This project uses a hybrid approach to maintain a single source of truth:

Markdown in /content/ (for prose):

  • ✅ Religion lore and deity explanations
  • ✅ Character creation guidelines
  • ✅ Political system descriptions
  • ✅ Any narrative or instructional text
  • ✅ Easy to edit, version control friendly

JSON in /site/public/data/ (for structured data):

  • ✅ Deity lists with domains and alignments
  • ✅ Character stats and attributes
  • ✅ Creature abilities and threat levels
  • ✅ Region hierarchies and demographics
  • ✅ Schema validation and iteration support

Why This Matters: You edit content ONCE in the appropriate format, then generate-ai-docs.js combines both sources to create comprehensive AI documentation. The website reads from JSON for dynamic content, while AI docs include both structured data AND narrative context.

✨ Features

For AI Systems (RAG Integration)

  • Vector-Ready Content: Consolidated documents perfect for chunking and vector storage
  • Comprehensive Context: Each document contains complete information without requiring navigation
  • Relationship Mapping: Explicit cross-references between entities for better retrieval
  • Multiple Access Patterns: Both consolidated overviews and individual entity files
  • Automated Generation: GitHub Actions automatically creates and releases updated documentation

For Humans (GitHub Pages)

  • SolidJS SPA: Fast, reactive single-page application
  • Hash Routing: Works perfectly with GitHub Pages subpaths
  • Offline Support: Service Worker enables offline browsing with cached data
  • Smart Caching: Network-first strategy keeps content fresh when online
  • Mobile-Friendly: Responsive design that works on all devices
  • Fast Navigation: Instant page transitions after initial load

For Developers

  • TypeScript: Type-safe development with full IntelliSense
  • Hot Reload: Fast development with Vite
  • Multiple Runtimes: Choose between Node.js or Bun for development
  • Automated Deployment: Zero-maintenance publishing to GitHub Pages
  • AI Documentation Pipeline: Automated generation and packaging for RAG systems

🎯 Use Cases

  • 📖 Story Writing: AI generates consistent, lore-accurate content using comprehensive world knowledge from RAG systems
  • 🎮 Game Mastering: Rich reference material with AI assistance powered by vector search
  • 👥 Player Resources: Share world information via public website
  • 📚 World Building: Organize complex information with rich cross-references
  • 🌍 Community Sharing: Professional presentation of your fantasy world
  • 🤖 AI Training: Perfect dataset for fine-tuning language models on your world
  • 📊 Vector Databases: Ready-to-use documentation for pgvector and other RAG systems

🔧 Technical Architecture

  • Frontend: SolidJS + TypeScript + Vite
  • Routing: Hash-based routing for GitHub Pages compatibility
  • Styling: SCSS with responsive design
  • AI Documentation: Node.js generator for RAG-optimized markdown
  • Vector Database Ready: Perfect for pgvector, Chroma, or other vector stores
  • Deployment: GitHub Actions → GitHub Pages + AI docs releases
  • Development: Multiple runtime support (Node.js/Bun)

Perfect for creating rich, interactive fantasy worlds that serve both AI systems via RAG and human readers via beautiful web interfaces! 🎉