Hero/Landing Page
Spirit Gallery
Interpretation Comparison
Spectral Timeline
File Upload Demo

The Haunted Reader - Project Story

🎃 Inspiration

The idea for The Haunted Reader came from a simple question: "What if you could get feedback on your writing from Edgar Allan Poe?"

As a writer, I often struggled to see my work from different perspectives. I'd get stuck in my own voice, my own style, my own biases. Traditional writing tools offer grammar checks and spell corrections, but they don't help explore how a story might sound through different lenses—Gothic horror, Victorian social commentary, innocent wonder, or academic analysis.

The Kiroween Hackathon's Frankenstein category was the perfect fit. Like Dr. Frankenstein stitching together different parts to create something new, The Haunted Reader stitches together:

Literary analysis engines
AI text generation (Amazon Bedrock)
Perspective modeling systems
File parsing (PDF/EPUB/TXT)
Emotional flow visualization
AWS cloud infrastructure

The result? A chimera that brings literary spirits to life, allowing anyone to see their text through the eyes of classic authors, fictional characters, or abstract perspectives.

📖 What It Does

The Haunted Reader is a multi-perspective text interpretation engine that transforms how you read and analyze text.

Core Features

Text Upload & Parsing
- Upload TXT, PDF, or EPUB files (up to 10MB)
- Direct text paste for quick analysis
- Automatic structure detection (chapters, sections, paragraphs)
- Real-time metadata calculation (word count, read time)
- File info display - Shows filename and size (KB/MB) after upload
- Home button - Quick reset to start over with new text
Literary Spirit Gallery
- 10+ unique spirits with distinct personalities:
  - Edgar Allan Poe - Gothic horror and psychological darkness
  - Charles Dickens - Victorian social commentary
  - Jane Austen - Romantic wit and social observation
  - H.P. Lovecraft - Cosmic horror and existential dread
  - Ernest Hemingway - Minimalist, direct prose
  - The Villain - Malicious perspective
  - A 5-year-old - Innocent, wonder-filled lens
  - An Old Scholar - Academic, analytical view
  - The Monster - Creature's perspective
  - Prophet of Doom - Apocalyptic interpretation
- Multi-select up to 5 spirits simultaneously
- Category filtering (Authors, Characters, Perspectives, Abstract)
- Responsive grid layout - Optimized for all screen sizes (max 3 columns)
- No horizontal overflow - Spirits fit perfectly on any device
AI-Powered Interpretation
- Powered by Amazon Bedrock (Claude 3 Sonnet & Haiku)
- Generate summaries from each spirit's perspective
- Rewrite text in different author styles
- Create alternative endings
- Analyze emotional tone and themes
- Parallel generation for multiple spirits
Spectral Timeline Visualization
- Emotional flow analysis across text sections
- Color-coded emotions: fear, joy, tension, sadness, mystery, neutral
- Interactive timeline with clickable sections
- Mathematical emotion scoring: $\sum_{i=1}^{6} e_i = 1.0$ per section
- Neutral sentiment detection for receipts, technical docs, and non-emotional content
Export & Save
- Export as TXT, PDF, Markdown, or ZIP
- Include all interpretations with metadata
- Spirit attribution and generation timestamps

🛠 How I Built It

Architecture Overview

The Haunted Reader follows a modular, spec-driven architecture:

┌─────────────────────────────────────────────────────────┐
│                     React UI Layer                      │
│  (TextUploader, SpiritGallery, InterpretationViewer)    │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                  Service Layer                          │
│  (AIService, FileParser, InterpretationEngine)          │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                  Spirit Engine                          │
│  (Spirit Definitions, Prompt Templates, Voice Profiles) │
└─────────────────────────────────────────────────────────┘

Technology Stack

Frontend:

React 18 - Component-based UI
Vite - Lightning-fast build tool
Tailwind CSS + DaisyUI - Utility-first styling with pre-built components
Custom Dracula Theme - Spooky dark theme with purple/green accents
React Dropzone - File upload with drag-and-drop

AI & Cloud:

Amazon Bedrock - Claude 3 Sonnet (quality) & Haiku (speed)
Amazon Cognito - Identity pool for temporary AWS credentials
AWS S3 - Static website hosting
AWS CloudFront - Global CDN with HTTPS

File Processing:

PDF.js - PDF text extraction
EPUB.js - EPUB parsing
Custom parsers - Structure detection and metadata

Development Tools:

Kiro IDE - Spec-driven development
Vitest - Unit testing (69 tests passing)
ESLint - Code quality

Development Process with Kiro

The entire project was built using Kiro's spec-driven development approach:

1. Specification Phase

Created comprehensive specs in .kiro/specs/haunted-reader/:

requirements.md - 7 acceptance criteria with user stories
design.md - 9 modules with 30+ correctness properties
tasks.md - 21 implementation tasks across 6 phases

Example correctness property: $$CP\text{-}4.1: T_{interpretation} < 30s \text{ for } |W| \leq 5000$$

Where $T_{interpretation}$ is generation time and $|W|$ is word count.

2. Implementation Phase

Followed task-by-task implementation:

Phase 1: Project setup (3 tasks)
Phase 2: Core services (6 tasks)
Phase 3: UI components (4 tasks)
Phase 4: Integration & polish (4 tasks)
Phase 5: Deployment (1 task)

3. Agent Hooks

Automated workflows with custom hooks:

on-file-save - Auto-validate syntax on save
spirit-consistency-check - Verify spirit voice consistency

4. Steering Documents

Project-wide guidelines in .kiro/steering/:

project-context.md - Architecture and code style
spirit-personalities.md - Voice consistency rules
ai-prompts.md - Bedrock prompt engineering

Key Implementation Details

Spirit Prompt Engineering: Each spirit has a carefully crafted prompt template:

{
  id: 'poe',
  name: 'Edgar Allan Poe',
  voice: {
    tone: 'Ornate, melancholic, obsessed with death and beauty',
    vocabulary: ['melancholy', 'sepulchral', 'phantasm', 'pallid'],
    structure: 'Long, flowing sentences with dramatic pauses',
    focus: 'Psychological horror, death, beauty in decay'
  },
  prompts: {
    summary: 'Rewrite this text as Edgar Allan Poe would...',
    // ... more templates
  }
}

Emotion Analysis Algorithm: The Spectral Timeline uses a weighted scoring system with 6 emotions:

$$E_{section} = {e_{fear}, e_{joy}, e_{tension}, e_{sadness}, e_{mystery}, e_{neutral}}$$

Where each emotion score $e_i \in [0, 1]$ and $\sum e_i = 1.0$

Neutral Detection: When no emotional keywords are found, the system assigns: $$e_{neutral} = 0.5, \quad e_{other} = 0.1 \text{ each}$$

This prevents misclassification of receipts, technical documents, and factual content as "joyful".

Caching Strategy: Interpretations are cached using: $$cache_key = hash(text + spirit_id + prompt_type)$$

This prevents duplicate Bedrock API calls and reduces costs.

🚧 Challenges I Ran Into

1. Amazon Bedrock Integration

Challenge: Bedrock requires proper IAM roles and Cognito configuration for browser-based access.

Solution:

Created Cognito Identity Pool for unauthenticated access
Configured IAM role with bedrock:InvokeModel permissions
Implemented retry logic with exponential backoff for throttling
Used separate models: Haiku for speed, Sonnet for quality

Code:

const credentials = fromCognitoIdentityPool({
  identityPoolId: process.env.VITE_COGNITO_IDENTITY_POOL_ID,
  clientConfig: { region: 'us-east-1' }
});

2. File Upload in Production

Challenge: File upload worked locally but failed in production deployment.

Root Cause: Missing CORS configuration on S3 bucket.

Solution:

aws s3api put-bucket-cors --bucket haunted-reader \
  --cors-configuration '{
    "CORSRules": [{
      "AllowedOrigins": ["*"],
      "AllowedMethods": ["GET", "HEAD", "POST"],
      "AllowedHeaders": ["*"]
    }]
  }'

3. Click-to-Browse Not Working

Challenge: Drag-and-drop worked, but clicking the upload area didn't open file picker.

Solution: Explicitly enabled click events in react-dropzone:

const { getRootProps, getInputProps } = useDropzone({
  noClick: false,  // Explicitly enable
  noKeyboard: false
});

4. PDF.js Worker Loading

Challenge: PDF parsing failed in production due to worker file not loading.

Solution: Used CDN for worker file:

pdfjsLib.GlobalWorkerOptions.workerSrc = 
  `//cdnjs.cloudflare.com/ajax/libs/pdf.js/${pdfjsLib.version}/pdf.worker.min.js`;

5. SPA Routing on S3

Challenge: Direct URL access or page refresh resulted in 404 errors.

Solution: Configured CloudFront custom error responses:

403 → /index.html (200)
404 → /index.html (200)

6. Accessibility Compliance

Challenge: Meeting WCAG 2.1 AA standards while maintaining spooky theme.

Solution:

Added ARIA labels to all interactive elements
Implemented keyboard navigation with skip links
Ensured color contrast ratios ≥ 4.5:1
Added prefers-reduced-motion support
Created screen reader announcements for dynamic updates

Contrast Calculation: $$C = \frac{L_1 + 0.05}{L_2 + 0.05} \geq 4.5$$

Where $L_1$ and $L_2$ are relative luminance values.

7. Bundle Size Optimization

Challenge: Initial bundle was 1.8 MB (too large).

Solution:

Code splitting by module (spirit-engine, parsers, vendor)
Lazy loading for PDF/EPUB parsers
Tree shaking unused code
Gzip compression via CloudFront

Result: 1.34 MB → 412 KB (gzipped) - 69% reduction

8. Neutral Content Misclassification

Challenge: Receipts and technical documents were incorrectly classified as "Joy" in the emotional timeline due to tie-breaking logic.

Root Cause: When no emotional keywords were found, all 5 emotions received equal scores (20% each). The tie-breaker preferred "joy" first, causing neutral content to appear joyful.

Solution:

Added 6th emotion category: neutral
Created neutral keyword dictionary: total, amount, price, receipt, transaction, payment, tax, invoice, order, purchase, etc.
Updated default emotion distribution when no keywords found: javascript { fear: 0.1, joy: 0.1, tension: 0.1, sadness: 0.1, mystery: 0.1, neutral: 0.5 // Dominant for non-emotional content }
Changed tie-breaker preference order to prioritize neutral first

Result: Receipts, invoices, and technical documents now correctly display as neutral (gray) instead of joy (pink).

9. Responsive Layout Issues

Challenge: Spirit gallery cards overflowed horizontally on smaller screens, causing horizontal scrollbar and poor mobile experience.

Root Cause: Grid was set to 4 columns (xl:grid-cols-4) which was too wide for most screens.

Solution:

Reduced grid from 4 columns to max 3 columns
Changed breakpoints: grid-cols-1 sm:grid-cols-2 lg:grid-cols-3
Added max-width container: max-w-7xl mx-auto
Responsive padding: p-4 md:p-8
Reduced gap spacing: gap-4 md:gap-6

Result: Spirits now fit perfectly on all screen sizes without horizontal overflow. Mobile experience significantly improved.

🏆 Accomplishments I'm Proud Of

1. Complete Spec-Driven Development

Built the entire project using Kiro's spec-driven approach:

21 tasks completed across 6 phases
30+ correctness properties verified
69 unit tests passing
Zero critical bugs at deployment

2. Production-Ready AWS Deployment

✅ Custom domain: hauntedreader.com
✅ HTTPS with CloudFront + AWS Certificate Manager
✅ Global CDN for fast worldwide access
✅ CORS configured for file operations
✅ SPA routing working perfectly
✅ DNS configured with Route 53
✅ Cost: ~$12/year (domain only, AWS within free tier)

3. WCAG 2.1 AA Accessibility

Full keyboard navigation
Screen reader support
Focus indicators on all elements
Reduced motion support
Color contrast compliance

4. 10+ Unique Literary Spirits

Each with:

Distinct personality and voice
Custom prompt templates
Consistent tone across all operations
Accurate style mimicry

5. Emotional Flow Visualization

The Spectral Timeline provides unique insights:

Divides text into 10-20 sections
Analyzes 6 emotions per section (including neutral)
Interactive, clickable timeline
Color-coded for accessibility
Accurately classifies non-emotional content

6. Multi-Format Support

Input: TXT, PDF, EPUB
Output: TXT, PDF, Markdown, ZIP
Preserves structure and metadata
Handles files up to 10MB

7. Performance Optimization

First Contentful Paint: < 1.5s
Time to Interactive: < 3s
Interpretation generation: < 30s for 5000 words
Parallel spirit generation
Intelligent caching

📚 What I Learned

Technical Learnings

Amazon Bedrock Best Practices
- Model selection: Haiku for speed, Sonnet for quality
- Prompt engineering for consistent voice
- Token estimation and cost optimization
- Handling throttling and rate limits
AWS Deployment Architecture
- S3 static website hosting configuration
- CloudFront distribution setup
- CORS and security policies
- Cache invalidation strategies
Accessibility is Non-Negotiable
- ARIA labels make a huge difference
- Keyboard navigation requires careful planning
- Color contrast affects readability significantly
- Screen readers need explicit announcements
Spec-Driven Development Works
- Clear requirements prevent scope creep
- Correctness properties catch bugs early
- Task dependencies ensure logical flow
- Checkpoints validate progress

Development Process Learnings

Kiro's Power
- Specs provide clear roadmap
- Agent hooks automate repetitive tasks
- Steering documents maintain consistency
- Vibe coding accelerates UI polish
Testing Matters
- Unit tests caught 12+ bugs before deployment
- Integration tests verified end-to-end flows
- Manual testing found UX issues
Documentation is Essential
- Comprehensive guides saved debugging time
- Troubleshooting docs helped solve issues quickly
- README clarity improves user experience

Design Learnings

User Experience
- Loading states reduce perceived wait time
- Error messages should be helpful AND thematic
- Multi-step flows need clear progress indicators
Performance vs. Quality Trade-offs
- Claude Haiku: 2x faster, 90% quality
- Claude Sonnet: Slower, 100% quality
- Let users choose based on needs
Spooky Theme Challenges
- Dark themes can reduce readability
- Animations must respect user preferences
- Accessibility and aesthetics can coexist
DaisyUI Component Library
- Pre-built components accelerated development
- Consistent design system across all views
- Easy theme customization (Dracula theme)
- Reduced custom CSS by ~60%

Iterative Development Learnings

Small UX Improvements Matter
- Home button significantly improved user flow
- File info display increased transparency
- Responsive layout fixes enhanced mobile experience
Sentiment Analysis Needs Nuance
- Not all text is emotional
- Neutral category essential for factual content
- Context-aware classification improves accuracy
Testing on Real Content
- Uploading receipts revealed emotion classification bug
- Mobile testing caught layout overflow issues
- User feedback drives meaningful improvements

🚀 What's Next for The Haunted Reader

Short-Term Enhancements

Domain & Branding
- ✅ Custom domain purchased: hauntedreader.com
- ✅ DNS configured to point to CloudFront distribution
- ✅ AWS Certificate Manager SSL certificate issued
- ✅ Professional thumbnail created (1280x720px with animations)
- Social media preview cards (Open Graph, Twitter Cards)
Custom Spirit Creation
- Allow users to define their own spirits
- Upload voice samples for style matching
- Share spirits with community
User Experience Enhancements
- Comparison mode for side-by-side spirit interpretations
- Bookmarking favorite interpretations
- Text highlighting and annotations
- Dark/light theme toggle
- Customizable emotion colors
Real-Time Collaboration
- Multiple users analyzing same text
- Shared spirit selections
- Collaborative annotations
Advanced Analysis
- Sentiment analysis over time
- Character relationship mapping
- Plot structure visualization
- Writing style metrics
More File Formats
- DOCX (Microsoft Word)
- RTF (Rich Text Format)
- HTML (web pages)
- Markdown (technical docs)

Long-Term Vision

Integration with Writing Tools
- Google Docs add-on
- Scrivener plugin
- VS Code extension
- Notion integration
Voice Narration
- Text-to-speech for interpretations
- Different voices for different spirits
- Audio export options
Machine Learning Enhancements
- Fine-tune models on specific authors
- Improve emotion detection accuracy
- Personalized spirit recommendations
Educational Features
- Lesson plans for teachers
- Literary analysis tutorials
- Writing improvement suggestions
- Style comparison tools
Community Features
- User accounts and saved interpretations
- Public spirit gallery
- Interpretation sharing
- Rating and feedback system
Mobile Apps
- Native iOS app
- Native Android app
- Offline mode support
- Camera text capture (OCR)

Scalability Plans

Current Architecture: $$Cost_{monthly} = S3_{storage} + CloudFront_{transfer} + Bedrock_{tokens}$$ $$Cost_{monthly} \approx \$0.13 + \$0.01 \times tokens_{millions}$$

Future Architecture:

Lambda functions for backend processing
DynamoDB for user data and caching
API Gateway for rate limiting
ElastiCache for interpretation caching

Expected Scaling:

Support 10,000+ concurrent users
Process 1M+ interpretations/month
Maintain < 3s response time
Keep costs < $500/month

🎃 Conclusion

The Haunted Reader is more than just a hackathon project—it's a glimpse into the future of reading and writing. By combining AI, cloud infrastructure, and thoughtful UX design, I've created a tool that makes literary analysis accessible, engaging, and fun.

Built entirely with Kiro's spec-driven development, deployed on AWS with Bedrock, and designed with accessibility in mind, The Haunted Reader demonstrates what's possible when you stitch together the right technologies with clear vision and careful execution.

Like Dr. Frankenstein's creation, it's a chimera—but unlike his monster, it's here to help, not haunt (well, maybe a little haunting 👻).

Try it now: https://www.hauntedreader.com

The spirits are waiting to interpret your text! 📖👻

📊 Project Statistics

Lines of Code: ~9,200
Components: 22+ (all using DaisyUI)
Services: 9
Spirits: 10+
Emotions Tracked: 6 (fear, joy, tension, sadness, mystery, neutral)
UI Framework: Tailwind CSS + DaisyUI
Tests: 69 passing
Build Time: ~5 seconds
Bundle Size: 413 KB (gzipped)
Development Time: ~45 hours
Tasks Completed: 21/21 (100%)
Accessibility Score: WCAG 2.1 AA compliant
Performance Score: Lighthouse 90+
Git Commits: 50+
Deployments: 10+

Built with 💜 for the Kiroween Hackathon 2025
Category: Frankenstein - Stitching Together the Impossible

Built With

amazon-bedrock
amazon-cognito
amazon-web-services
aws-cloudfront
daisyui
epub.js
eslint
kiro
pdf.js
react
tailwind
vite
vitest

The Haunted Reader - Project Story

🎃 Inspiration

📖 What It Does

Core Features

🛠 How I Built It

Architecture Overview

Technology Stack

Development Process with Kiro

1. Specification Phase

2. Implementation Phase

3. Agent Hooks

4. Steering Documents

Key Implementation Details

🚧 Challenges I Ran Into

1. Amazon Bedrock Integration

2. File Upload in Production

3. Click-to-Browse Not Working

4. PDF.js Worker Loading

5. SPA Routing on S3

6. Accessibility Compliance

7. Bundle Size Optimization

8. Neutral Content Misclassification

9. Responsive Layout Issues

🏆 Accomplishments I'm Proud Of

1. Complete Spec-Driven Development

2. Production-Ready AWS Deployment

3. WCAG 2.1 AA Accessibility

4. 10+ Unique Literary Spirits

5. Emotional Flow Visualization

6. Multi-Format Support

7. Performance Optimization

📚 What I Learned

Technical Learnings

Development Process Learnings

Design Learnings

Iterative Development Learnings

🚀 What's Next for The Haunted Reader

Short-Term Enhancements

Long-Term Vision

Scalability Plans

🎃 Conclusion

📊 Project Statistics

Built With

Updates