Xmas List

A real-time collaborative Christmas wish list application built with Flask (Python) backend and React (TypeScript) frontend, communicating via WebSockets.

Purpose

Enable users to create, share, and manage Christmas gift wish lists with real-time synchronization across all connected clients.

Users can:

• Manage their Christmas wish list
• See realtime feeds of what other people are wishing for

Tech Stack

• Backend: Python 3.14+ with Flask 3.0, Flask-SocketIO, Pydantic validation
• Frontend: Node 22 with React 18, TypeScript 5, Zod validation
• Communication: WebSocket-based message-oriented handler pattern
• Package Managers: uv (Python), pnpm (Node.js)
• Platform: macOS development environment

Project Structure

xmas-list/
├── backend/               # Python Flask backend API
│   ├── src/
│   │   ├── app.py        # Flask application entry point
│   │   ├── handlers/     # Message handlers
│   │   ├── models/       # Pydantic data models
│   │   └── services/     # Business logic services
│   ├── tests/
│   ├── pyproject.toml
│   └── README.md         # Backend-specific documentation
│
├── ui/                    # React TypeScript frontend
│   ├── src/
│   │   ├── App.tsx       # Main React component
│   │   ├── components/   # React components
│   │   ├── handlers/     # Message handlers
│   │   ├── models/       # Zod validation schemas
│   │   └── services/     # WebSocket client service
│   ├── package.json
│   └── README.md         # Frontend-specific documentation
│
├── specs/                 # Feature specifications
│   └── 001-app-setup/    # Current feature documentation
│       ├── spec.md       # Feature specification
│       ├── plan.md       # Technical plan
│       ├── tasks.md      # Implementation tasks
│       └── quickstart.md # 15-minute setup guide
│
├── .githooks/            # Git hooks for commit conventions
├── CONTRIBUTING.md       # Contribution guidelines
└── README.md             # This file

Quick Start

See specs/001-app-setup/quickstart.md for a complete 15-minute setup guide.

Prerequisites

• Python 3.14 or higher
• uv package manager
• Node 22 LTS or higher
• pnpm package manager

Backend Setup

cd backend
uv sync                    # Install dependencies
uv run python src/app.py   # Start Flask server on http://127.0.0.1:5000

See backend/README.md for detailed backend documentation.

Frontend Setup

cd ui
pnpm install              # Install dependencies
pnpm dev                  # Start Vite dev server on http://localhost:5173

See ui/README.md for detailed frontend documentation.

Development

Git Hooks (Optional)

Enable git hooks for commit message and branch name validation:

git config core.hooksPath .githooks

See CONTRIBUTING.md for development conventions.

Running Tests

Backend:

cd backend
uv run pytest

Frontend:

cd ui
pnpm test

Code Quality

Backend:

cd backend
uv run black src/         # Format code
uv run mypy src/          # Type checking

Frontend:

cd ui
pnpm lint                 # ESLint
pnpm type-check           # TypeScript checking

Architecture

Message-Oriented Handler Pattern

Both backend and frontend use a consistent message handler pattern:

1. Messages follow a standard schema: {type, payload, id, timestamp}
2. Handlers are registered by message type
3. Validation uses Pydantic (backend) and Zod (frontend)
4. Routing happens automatically based on message type

WebSocket Communication

• Backend: Flask-SocketIO on port 5000
• Frontend: Native WebSocket client connecting to backend
• Protocol: JSON-encoded messages over WebSocket
• Reconnection: Automatic with exponential backoff

Environment Configuration

Both backend and frontend include .env.example files with required environment variables:

# Backend
cp backend/.env.example backend/.env

# Frontend
cp ui/.env.example ui/.env

Edit these files as needed for your environment.

Documentation

• Feature Specification - What we're building and why
• Technical Plan - Architecture and tech decisions
• Implementation Tasks - Detailed task breakdown
• Quick Start Guide - 15-minute setup walkthrough
• Contributing Guide - Development conventions and workflow

Project Status

Current Phase: Initial application structure setup (Feature 001)

✅ Completed:

• Project structure and build configuration
• Message-oriented handler pattern (both backend and frontend)
• WebSocket communication infrastructure
• Development tooling and git hooks
• Comprehensive documentation

🚧 Next Steps:

• User authentication
• Wish list CRUD operations
• Real-time synchronization
• User interface components

Troubleshooting

Port Conflicts

If ports 5000 (backend) or 5173 (frontend) are in use:

# Find process using port
lsof -i :5000
lsof -i :5173

# Kill process
kill -9 <PID>

Import/Module Errors

Ensure you're using the correct Python/Node versions:

python --version    # Should be 3.14+
node --version      # Should be 22+

WebSocket Connection Issues

1. Verify backend is running on port 5000
2. Check frontend is connecting to correct URL in .env
3. Inspect browser console for connection errors
4. Check backend logs for WebSocket errors

For more troubleshooting, see component-specific READMEs:

• backend/README.md
• ui/README.md

License

MIT

Contributing

See CONTRIBUTING.md for guidelines on:

• Branch naming conventions
• Commit message format
• Pull request process
• Code style guidelines