PhantomForge 👻

A spooky hybrid application that generates retro-themed haunted microsites through AI-powered content generation. Built for the Kiroween Hackathon (Frankenstein Category).

🎃 Features

• One-Click Site Generation: Choose from Geocities, BBS ANSI, or 90s Neon themes
• AI Ghostwriter: Automatically generates HTML, CSS, JavaScript, and spooky content
• Live Preview: Real-time preview with responsive viewport testing
• Agent Hooks: Automated asset processing and thumbnail generation
• Spec-Driven CI: Quality enforcement with accessibility and SEO validation
• MCP Connectors: Integration with external tools (ANSI converter, TTS, fonts)
• Deployment: One-click deployment to Vercel or Netlify
• Dashboard: Manage all your haunted microsites in one place

🛠️ Tech Stack

• Frontend: Angular 15+ with TypeScript
• Backend: Node.js + Express + TypeScript
• Database: MySQL 8.0+
• WebSocket: Real-time generation progress updates
• Storage: Local filesystem (development) / Cloud storage (production)
• Testing: Jest for unit tests

📋 Prerequisites

• Node.js 18+ and npm
• MySQL 8.0+
• Angular CLI (npm install -g @angular/cli)

🚀 Quick Start

1. Clone and Install

# Install backend dependencies
npm install

# Install frontend dependencies
cd webapp
npm install
cd ..

2. Configure Environment

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
# - Set database credentials
# - Configure JWT secret
# - Add API tokens for deployment services

3. Setup Database

# Create database
mysql -u root -p -e "CREATE DATABASE phantom_forge;"

# Run migrations
npm run db:setup

# Optional: Seed with test data
npm run db:setup -- --seed

4. Start Development Servers

# Terminal 1: Start backend
npm run dev

# Terminal 2: Start frontend
cd webapp
ng serve

Visit http://localhost:4200 to access the application!

📁 Project Structure

phantom-forge/
├── .kiro/                      # Kiro configuration
│   ├── hooks/                  # Agent hooks
│   ├── steering/               # Steering documents
│   ├── specs/                  # Spec files
│   └── mcp.json               # MCP connectors config
├── src/                        # Backend source
│   ├── config/                 # Configuration
│   ├── models/                 # Data models
│   ├── repositories/           # Database layer
│   ├── services/               # Business logic
│   ├── routes/                 # API endpoints
│   ├── middleware/             # Express middleware
│   ├── utils/                  # Utilities
│   ├── websocket/              # WebSocket server
│   └── server.ts               # Entry point
├── webapp/                     # Angular frontend
│   ├── src/app/
│   │   ├── components/         # UI components
│   │   ├── services/           # Angular services
│   │   ├── models/             # TypeScript interfaces
│   │   ├── guards/             # Route guards
│   │   └── interceptors/       # HTTP interceptors
│   └── src/environments/       # Environment configs
├── database/                   # Database scripts
│   ├── migrations/             # SQL migrations
│   ├── migrate.ts              # Migration runner
│   ├── seed.ts                 # Seed data
│   └── setup.ts                # Setup script
├── storage/                    # Generated site bundles
└── tests/                      # Test files

🎨 Themes

Geocities Theme

• Animated GIFs and sparkles
• Marquee scrolling text
• Table-based layouts
• Visitor counters
• Under construction signs

BBS ANSI Theme

• Monospace terminal fonts
• ANSI color codes
• ASCII art borders
• Retro BBS aesthetics
• Text-based navigation

90s Neon Theme

• Neon glow effects
• Gradient backgrounds
• Retro typography
• Animated elements
• Cyberpunk vibes

🔌 API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user

Microsites

• POST /api/microsites - Create new microsite
• GET /api/microsites - List user's microsites
• GET /api/microsites/:id - Get microsite details
• PUT /api/microsites/:id - Update microsite
• DELETE /api/microsites/:id - Delete microsite
• GET /api/microsites/search - Search microsites

Deployment

• POST /api/microsites/:id/deploy - Deploy to hosting
• GET /api/microsites/:id/deployments - Get deployment history
• POST /api/microsites/:id/rollback - Rollback deployment

Preview & Export

• GET /api/microsites/:id/preview - Get preview URL
• POST /api/microsites/:id/export - Export as ZIP

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm test -- --coverage

🎯 Kiro Features Used

1. Vibe Coding

Used Kiro to generate initial component structures and iterate on designs through natural language prompts.

2. Agent Hooks

Automated workflows in .kiro/hooks/:

• on_save_generate_thumbnail.yaml - Auto-generate thumbnails on asset save
• on_deploy_verify_spec.yaml - Verify spec compliance before deployment

3. Steering Documents

Consistency enforcement in .kiro/steering/:

• voice.md - Spooky tone and language guidelines
• structure.md - Code organization and style rules

4. Spec-Driven Development

Complete specification in .kiro/specs/phantom-forge/:

• requirements.md - User stories and acceptance criteria
• design.md - Architecture and correctness properties
• tasks.md - Implementation task list

5. MCP Connectors

External tool integrations in .kiro/mcp.json:

• ANSI art converter
• Text-to-speech service
• Vintage font generator

🚢 Deployment

Backend (Node.js)

# Build
npm run build

# Start production server
npm start

Frontend (Angular)

cd webapp
ng build --configuration production

Deploy the webapp/dist folder to your hosting provider.

📝 Environment Variables

# Server
PORT=3000
NODE_ENV=development

# Database
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=phantom_forge

# JWT
JWT_SECRET=your_secret_key
JWT_EXPIRES_IN=7d

# Storage
STORAGE_PATH=./storage
MAX_FILE_SIZE=10485760

# MCP Connectors
MCP_ANSI_CONVERTER_URL=http://localhost:4001/convert
MCP_TTS_SERVICE_URL=http://localhost:4002/tts
MCP_FONT_SERVICE_URL=http://localhost:4003/fonts

# Deployment
VERCEL_API_TOKEN=your_vercel_token
NETLIFY_API_TOKEN=your_netlify_token

🤝 Contributing

This project was built for the Kiroween Hackathon. Contributions are welcome!

📄 License

MIT License - see LICENSE file for details

👻 Demo

• Live Demo: [Coming Soon]
• Video Demo: [Coming Soon]
• Test Credentials:
  • Email: test@phantomforge.com
  • Password: password123

📞 Support

For issues or questions, please open an issue on GitHub.

---

Built with 💀 for Kiroween Hackathon