🎮 Pictagories - AI-Powered Word Game

A daily word guessing game where AI validates your creativity!

Play Now | Report Bug | Request Feature

📖 About

Pictagories is an engaging daily word game that challenges players to think creatively within categories. Each day brings a new category, and players submit words that fit the theme. Our AI-powered validation system (using OpenAI GPT-4o) ensures fair and intelligent word acceptance, making each game dynamic and fun.

✨ Key Features

• 🎯 Daily Categories - New challenge every day
• 🤖 AI Validation - Smart word validation using GPT-4o
• 🏆 Leaderboards - Compete with friends and global players
• 📱 Mobile Optimized - Play anywhere, anytime
• 🎨 Dynamic Visuals - AI-generated category images with DALL-E 3
• 🎉 Composite Images - Celebrate your words with custom generated art
• ⚡ Real-time Updates - Instant feedback on your submissions
• 🎮 Simple Multiplayer - Name-based authentication for quick games

🚀 Quick Start

Prerequisites

• Node.js 18+ installed
• OpenAI API key (Get one here)

Installation

1. Clone the repository

git clone https://github.com/yourusername/pictagories.git
cd pictagories

2. Install dependencies

npm install

3. Set up environment variables

cp .env.example .env
# Edit .env and add your OpenAI API key

4. Start the development server

npm run dev

5. Open your browser Navigate to http://localhost:5000

🎮 How to Play

1. Enter your name - No registration required!
2. See today's category - Example: "Things you'd take on a camping trip"
3. Submit words - Type words that fit the category
4. Get instant feedback - AI validates if your word fits
5. Score points - Valid words earn you points
6. Click "I'm Done" - Generate a celebratory image with your words
7. Check the leaderboard - See how you rank against others

🛠️ Technology Stack

Frontend

• React 18 - UI framework
• TypeScript - Type safety
• Tailwind CSS - Styling
• Vite - Build tool
• TanStack Query - Data fetching
• Wouter - Routing
• shadcn/ui - Component library

Backend

• Express.js - Web server
• TypeScript - Type safety
• OpenAI API - Word validation & image generation
• In-memory storage - Fast development (easily replaceable with database)

AI Integration

• GPT-4o - Intelligent word validation
• DALL-E 3 - Dynamic image generation

📁 Project Structure

pictagories/
├── client/                 # Frontend React application
│   ├── src/
│   │   ├── components/    # Reusable UI components
│   │   ├── pages/        # Page components
│   │   ├── hooks/        # Custom React hooks
│   │   └── lib/          # Utilities and types
├── server/                # Backend Express server
│   ├── services/         # External service integrations
│   │   └── openai.ts    # OpenAI API integration
│   ├── routes.ts        # API endpoints
│   └── storage.ts       # Data persistence layer
├── shared/              # Shared types and schemas
│   └── schema.ts       # Data models
└── public/             # Static assets

🔧 Configuration

Environment Variables

# Required
OPENAI_API_KEY=sk-...       # Your OpenAI API key

# Optional
PORT=5000                    # Server port (default: 5000)
NODE_ENV=development         # Environment (development/production)

Category Configuration

Categories are rotated daily. To add or modify categories, edit the category list in server/storage.ts:

const categories = [
  "Things you'd take on a camping trip",
  "Items found in a kitchen",
  "Types of transportation",
  // Add more categories here
];

📚 API Documentation

See API.md for complete API documentation.

Quick API Examples

# Create/get player
curl -X POST http://localhost:5000/api/players \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

# Submit a word
curl -X POST http://localhost:5000/api/words/submit \
  -H "Content-Type: application/json" \
  -d '{
    "word": "tent",
    "category": "Things you'd take on a camping trip",
    "playerId": "uuid"
  }'

# Get leaderboard
curl http://localhost:5000/api/game/leaderboard

🚢 Deployment

See DEPLOYMENT.md for detailed deployment instructions.

Quick Deploy to Replit

1. Fork this repl or import from GitHub
2. Add OPENAI_API_KEY in Secrets
3. Click the Deploy button
4. Your app is live!

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Ways to Contribute

• 🐛 Report bugs
• 💡 Suggest new features
• 📝 Improve documentation
• 🎨 Submit UI/UX improvements
• 🌍 Add translations
• ⚡ Optimize performance

📈 Roadmap

• User accounts with persistent stats
• Custom game rooms
• Timer-based challenges
• Achievement system
• Social sharing features
• Category suggestions by users
• Multi-language support
• WebSocket for real-time updates
• Mobile app (React Native)

🐛 Known Issues

• Composite image generation may take a few seconds
• Category images are cached for 24 hours
• In-memory storage resets on server restart (use database for production)

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OpenAI for GPT-4o and DALL-E 3 APIs
• shadcn for the beautiful UI components
• Tailwind CSS for the styling system
• The React and TypeScript communities

💬 Support

• 📧 Email: support@pictagories.com
• 💬 Discord: Join our server
• 🐦 Twitter: @pictagories

🌟 Star History

---

Made with ❤️ by the Pictagories Team

If you enjoy Pictagories, please ⭐ this repository!