🧚♀️ Fairytales with Spice ✨
Generate spicy, adult-oriented fairy tales with AI-powered storytelling, multi-voice audio narration, and professional export options
🌟 Features
📚 Enhanced Story Generation v2.0 🆕
- Multi-Creature Stories: Choose from vampires, werewolves, and fairies
- 5 Distinct Themes: Romance, Adventure, Mystery, Comedy, and Dark narratives
- 🎭 10 Unconventional Beat Structures: Temptation Cascade, Power Exchange, Seduction Trap, Ritual Binding, Vulnerability Spiral, Hunt and Claim, Bargain's Price, Memory Fracture, Transformation Hunger, Mirror Souls
- 👥 Dynamic Author Style Blending: 2+1 selection system combines voices from 15 renowned authors (Anne Rice, Patricia Briggs, Holly Black, etc.)
- 🎯 Invisible Randomization: Each story gets unexpected combinations completely hidden from users
- 📚 Chekhov Element Tracking: Automatically plants story elements for future chapter payoffs
- 🌶️ Spice-Aware Adaptation: Beat structures intelligently adapt to content intensity (1-5 levels)
- Real-time Progress: Watch your story unfold with live generation updates
- Chapter Continuation: Extend stories with seamless chapter additions
- Customizable Length: 700, 900, or 1200 word options
🎭 Multi-Voice Audio Narration (Preview)
- Speaker Tag Recognition: Reads the
[Character]: / [Character, voice: …]: / [Narrator]: tags the story generator already writes into every chapter
- Character-Specific Voices: Configure a shared
ELEVENLABS_VOICE_POOL once and every AI-generated character name spreads across it, or pin a known recurring character with an ELEVENLABS_VOICE_<CHARACTER_NAME> override — see Custom Voices below
- Seamless Audio Merging: Concatenates every speaker's line into one continuous narration, in the order the excerpt reads
- ElevenLabs Integration, With a Dev/Test Mock Fallback: Real text-to-speech behind
ELEVENLABS_API_KEY; without one, a deterministic silent narration of the same length in development and tests, so the feature is fully testable offline. A production deployment with no key answers AI_UNAVAILABLE instead — it never narrates silence and calls it a success.
- Narrates an opening excerpt, not the whole chapter: the response is one inline audio file, capped at ~3 minutes of narration so it fits safely in a single API response — this app's shortest chapter (600 words) is already longer than that. Narrating a full chapter needs stored, URL-delivered audio instead, which is real follow-up work.
📤 Professional Export Options
- Multiple Formats: PDF, EPUB, DOCX, HTML, and TXT
- Metadata Inclusion: Author, title, themes, and generation details
- Chapter Organization: Properly formatted multi-chapter exports
- Download Management: Secure links with expiration handling
🛠️ Developer-Friendly Architecture
- Seam-Driven Development: Explicit contracts prevent integration failures
- Mock Services: Full functionality without external API dependencies
- Comprehensive Testing: 95%+ test coverage with integration suites
- Debug Panel: Built-in tools for API testing and error monitoring
- Enterprise CI/CD: 5-workflow pipeline with security scanning
🚀 Quick Start
Prerequisites
- Node.js 20.x or higher
- npm or yarn package manager
- (Optional) ElevenLabs API key for audio features
- (Optional) Grok/XAI API key for AI story generation
1. Clone the Repository
git clone https://github.com/Phazzie/FairytaleswithSpice.git
cd FairytaleswithSpice
2. Install Dependencies
# Install root dependencies
npm install
# Install frontend dependencies
cd story-generator && npm install && cd ..
3. Environment Setup
Create a .env file in the root directory:
# Optional: AI Story Generation (uses mocks if not provided)
XAI_API_KEY=your_grok_api_key_here
# Optional: Audio Generation (uses mocks if not provided)
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
# Optional: post `logCritical(...)` alerts (system failures, security issues)
# to a webhook instead of console-only logging, when NODE_ENV=production —
# `logCritical` never dispatches beyond the console otherwise, so this has no
# effect in the development setup below. Accepts any endpoint that takes a
# Slack-incoming-webhook-shaped `{ text }` POST body, Slack included. A
# malformed URL is reported (and degrades `/api/health`) rather than silently
# failing every delivery — see the Health Check section.
CRITICAL_ALERT_WEBHOOK_URL=https://hooks.slack.com/services/your/webhook/url
# Development settings
NODE_ENV=development
# Optional: Story Lab cloud storage (signed-in profile + project library).
# Defaults to `postgres` (requires DATABASE_URL) since that has always been
# this store's only implementation; an unset DATABASE_URL degrades
# `/api/health` (503) rather than silently erroring on every profile/project
# request. `non_durable_memory` is a local/test convenience only, not a
# supported production fallback: it keeps the backend from hard-erroring
# without a database, but the Angular client already treats that mode as
# unavailable (a signed-in library that can't actually save or sync), so
# `/api/health` also reports it as degraded rather than healthy — see the
# Health Check section.
STORY_LAB_CLOUD_STORAGE=postgres
4. Run in Development Mode
# Start frontend (Angular dev server)
cd story-generator && npm run dev
# API functions are automatically deployed to Vercel
# No local backend server needed - uses Vercel serverless functions
5. Access the Application
🏗️ Architecture Overview
Seam-Driven Development
This project follows a unique methodology where every data boundary is explicitly defined:
// Example: Story Generation Seam
interface StoryGenerationSeam {
input: {
creature: CreatureType;
themes: ThemeType[];
userInput: string;
spicyLevel: SpicyLevel;
wordCount: WordCount;
};
output: {
storyId: string;
title: string;
content: string;
// ... complete contract definition
};
}
Project Structure
FairytaleswithSpice/
├── 📁 story-generator/ # Angular 20.3 Frontend
│ ├── src/app/
│ │ ├── contracts.ts # Frontend seam contracts
│ │ ├── app.ts # Main application component
│ │ ├── story.service.ts # API communication
│ │ └── debug-panel/ # Development tools
│ └── ...
├── 📁 api/ # Vercel Serverless Functions
│ ├── health.ts # Health check endpoint
│ ├── story/
│ │ ├── generate.ts # Story generation endpoint
│ │ └── continue.ts # Chapter continuation
│ ├── audio/
│ │ └── convert.ts # Audio conversion endpoint
│ └── lib/
│ ├── services/ # Core business logic
│ └── types/ # Shared type definitions
├── 📁 .github/workflows/ # Enterprise CI/CD Pipeline
└── 📁 tests/ # Integration test suites
🎯 Usage Guide
Creating Your First Story
- Select a Creature: Choose vampire, werewolf, or fairy
- Pick Themes: Select up to 5 themes from the available options
- Set Spicy Level: Choose intensity from 1 (mild) to 5 (hot) 🌶️
- Add Custom Input (optional): Provide specific story elements
- Choose Word Count: Select 700, 900, or 1200 words
- Generate: Click "Generate Story" and watch the real-time progress
Multi-Voice Audio Features
The system automatically detects speaker patterns in generated stories:
[Vampire Lord]: "Come closer, my dear..."
[Fairy Princess]: "I'll never succumb to your darkness!"
[Narrator]: The tension in the moonlit chamber was palpable.
Each speaker gets a unique voice:
- Vampire Lord: Deep, seductive male voice
- Fairy Princess: Light, magical female voice
- Narrator: Neutral storytelling voice
Export Options
After generating a story, you can export in multiple formats:
- PDF: Professional layout with metadata
- EPUB: E-book format for readers
- DOCX: Microsoft Word document
- HTML: Web-ready format
- TXT: Plain text for universal compatibility
🔧 Development
Available Scripts
Frontend (story-generator/)
npm run dev # Development server with hot reload
npm run build # Production build
npm run test # Run unit tests
npm run lint # Code quality checks
API Development (now integrated with frontend)
# Build and run locally (all-in-one Express server)
cd story-generator
npm run build
PORT=3000 node dist/story-generator/server/server.mjs
# Or use Docker for local development
docker compose up --build
# Test API endpoints
curl http://localhost:3000/api/health
curl -X POST http://localhost:3000/api/story/generate \
-H "Content-Type: application/json" \
-d '{"creature":"vampire","themes":["romance"],"spicyLevel":2,"wordCount":700}'
Integration Tests (tests/)
npm run test:integration # Full end-to-end tests
Mock vs Real Services
The application works fully without external APIs:
Mock Mode (default):
- Realistic story generation with predefined templates
- Audio conversion returns mock URLs with proper metadata
- Export functions generate downloadable mock files
Production Mode (with API keys):
- Real AI story generation via Grok/XAI
- Professional audio via ElevenLabs text-to-speech
- All features maintain identical interfaces
Debug Panel
Access with Ctrl+Shift+D or click the debug button:
- API Health Checks: Test endpoint connectivity
- Error Log Viewer: Real-time error monitoring
- Service Status: Current API key configuration
- Test Suite Runner: Execute integration tests
🔐 Security & Privacy
- No Data Persistence: Stories are generated fresh each time
- Environment Variable Security: API keys never exposed to frontend
- CORS Protection: Proper origin validation
- Input Sanitization: All user inputs are validated and cleaned
- Rate Limiting: API calls are throttled to prevent abuse
🚀 Deployment
Digital Ocean Deployment (Recommended)
Deploy to Digital Ocean App Platform for scalable, cost-effective hosting:
- Fork this repository
- Connect to Digital Ocean:
- Login to Digital Ocean dashboard
- Go to Apps → Create App
- Connect your GitHub repository
- Deploy with one-click:
- Use the provided
.do/app.yaml configuration
- Or manually configure Docker deployment
- Set Environment Variables:
XAI_API_KEY=your_grok_key
ELEVENLABS_API_KEY=your_elevenlabs_key
- Deploy: Digital Ocean builds and deploys automatically
Cost: Starting at $5/month (Basic plan) - much cheaper than Vercel for production!
📋 Complete Digital Ocean Deployment Guide
Alternative: Vercel Deployment (Legacy)
⚠️ Note: This app has been migrated to work better with Digital Ocean, but Vercel still works:
- Fork this repository
- Connect to Vercel: Import your fork in Vercel dashboard
- Set Environment Variables:
XAI_API_KEY=your_grok_key
ELEVENLABS_API_KEY=your_elevenlabs_key
- Deploy: Vercel automatically builds and deploys
Docker Deployment
# Local Docker development
docker compose up --build
# Production Docker deployment
docker build -t fairytales-with-spice .
docker run -p 8080:8080 \
-e XAI_API_KEY=your_key \
-e ELEVENLABS_API_KEY=your_key \
fairytales-with-spice
📊 Testing
Test Coverage
- Frontend: 85%+ component and service coverage
- API: 98%+ endpoint coverage with 154 test cases
- Integration: Complete workflow validation
- CI/CD: Automated testing on every commit
Running Tests
# Run all tests
npm test
# Frontend tests only
cd story-generator && npm test
# API tests only
cd api && npm test
# Integration tests
cd tests && npm run test:integration
🤝 Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Follow the seam-driven approach: Define contracts first
- Add comprehensive tests: Maintain 95%+ coverage
- Update documentation: Comment your code thoroughly
- Submit a pull request: Include detailed description
Development Guidelines
- Follow TypeScript strict mode
- Use seam contracts for all API boundaries
- Add JSDoc comments to all public methods
- Include error handling for all external calls
- Write tests for both success and failure scenarios
📝 API Documentation
Health Check
GET /api/health
Returns 200 with status: "healthy" normally, or 503 with status: "degraded"
when the rate-limit store, Story Lab job store, or Story Lab cloud storage
(signed-in profile/project library) is misconfigured. Falling back to the
in-memory/non-durable default is not itself degraded for the rate-limit store
or job store — those keep doing their actual job (per-instance rate limiting,
in-process job progress) either way, so only an unsupported mode value or an
unreachable postgres mode degrades them. Story Lab cloud storage is the one
exception: its default mode is postgres, not a non-durable fallback (see
Environment Setup above), and its non_durable_memory mode is also
degraded rather than healthy — unlike the other two stores' non-durable
defaults, this one means the signed-in profile/project library itself
doesn't work for its purpose (the Angular client's own CloudLibraryService
already treats that storage mode as unavailable). So this field is healthy
only in a reachable postgres mode.
services.criticalAlerting reports where logCritical(...) calls are actually
delivered right now: { mode: "console" } by default, or { mode: "webhook", configured: true } once CRITICAL_ALERT_WEBHOOK_URL is set and
NODE_ENV=production (see Environment Setup below) — logCritical never
dispatches beyond the console outside production, so this field reports
console there even with a valid URL configured, rather than claiming a
destination nothing will call yet. A syntactically invalid URL reports
{ mode: "webhook", configured: false } and does flip the overall
status to degraded (503) — unlike the two durable stores above, this is
the one case where an unset/console-only default is fine but a broken
explicit configuration is not.
Story Generation
POST /api/story/generate
Content-Type: application/json
{
"creature": "vampire",
"themes": ["romance", "mystery"],
"userInput": "Victorian London setting",
"spicyLevel": 3,
"wordCount": 900
}
Audio Conversion
POST /api/audio/convert
Content-Type: application/json
{
"storyId": "story_123",
"chapterId": "chapter_1",
"content": "<p>[Narrator]: The candles guttered.</p><p>[Lord Damien, voice: velvet-smoke]: \"Come closer.\"</p>",
"speed": 1.0,
"format": "wav"
}
voice is optional and, when sent, overrides every segment's resolved voice — see Custom Voices below for the per-character default. With no ELEVENLABS_API_KEY configured, the route answers a deterministic silent narration of the same length instead of calling ElevenLabs, so the feature works fully offline in development and tests. A production deployment (NODE_ENV/VERCEL_ENV = production) with no key instead answers every request with AI_UNAVAILABLE — the same fail-closed rule this repo applies to story and image generation — rather than silently narrating minutes of silence and reporting success.
content must estimate to 3 minutes of narration or less (about 450 words at the default speed) — the response is one inline data: URI, not a stream or a stored file, and a longer request is refused with INVALID_INPUT before any synthesis runs. The frontend's "Preview Narration" control sends the chapter's opening rather than the whole thing for this reason.
Image Generation Status
/api/image/generate is live and counted against the Story Lab's tracked Vercel function budget (see scripts/recovery/check-vercel-function-count.sh), alongside /api/audio/convert added for narration.
View complete API documentation
🎨 Customization
Adding New Creatures
- Update
CreatureType in contracts.ts
- Add creature to themes array in app.ts
- Update story generation prompts
Custom Voices
Character names are written by the AI fresh for every story, so pre-registering an env var per name isn't realistic — the setup most deployments actually want is ELEVENLABS_VOICE_POOL, a fixed set of real voice ids configured once:
ELEVENLABS_VOICE_POOL=your_voice_id_1,your_voice_id_2,your_voice_id_3
ELEVENLABS_VOICE_NARRATOR=your_voice_id
Each speaker's name is hashed to a stable slot in the pool, so the same character gets the same voice across every chapter and continuation of a story, and distinct characters spread across the pool rather than collapsing onto one voice.
For a known, recurring character you want pinned to a specific voice regardless of the pool, set a per-character override named after them:
ELEVENLABS_VOICE_LORD_DAMIEN=your_voice_id
AudioService resolves each speaker tag to a voice in this order: the caller's voice override, the per-character override, ELEVENLABS_VOICE_NARRATOR for the narrator specifically, ELEVENLABS_VOICE_POOL, then a flat ELEVENLABS_VOICE_DEFAULT fallback for anyone still unresolved. The deterministic id after that is a mock-mode-only fallback — it is never a real ElevenLabs voice, so with ELEVENLABS_API_KEY set, a speaker that reaches it instead fails the request with a configuration error naming the speaker. A production deployment needs at least one of ELEVENLABS_VOICE_DEFAULT or ELEVENLABS_VOICE_POOL set.
New Export Formats
Extend the export service with additional format handlers following the existing seam contract pattern.
📈 Performance
- Story Generation: 2-8 seconds (depending on complexity)
- Audio Conversion: 10-30 seconds (varies by length)
- Export Generation: 1-3 seconds per format
- Bundle Size: <2MB compressed frontend
- Lighthouse Score: 95+ performance rating
🐛 Troubleshooting
Common Issues
Story Generation Fails
- Check if running in mock mode (expected behavior)
- Verify XAI_API_KEY if using real AI
- Check API health endpoint
Audio Not Working
- Confirm ELEVENLABS_API_KEY is set
- Check browser audio permissions
- Verify audio format compatibility
Build Errors
- Run
npm ci to clean install dependencies
- Check Node.js version (requires 20.x+)
- Clear npm cache:
npm cache clean --force
Debug Mode
Enable verbose logging:
NODE_ENV=development
DEBUG=fairytales:*
📜 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- ElevenLabs for premium text-to-speech technology
- Grok/XAI for advanced AI story generation and image generation
- Digital Ocean for scalable, cost-effective cloud deployment
- Angular Team for the robust frontend framework
- Docker for containerized deployment simplicity
📞 Support
🚀 Digital Ocean Deployment Guide | 📖 Documentation | 🐳 Docker Setup
Made with ❤️ and a touch of spice
