Cross-Platform Gaming App: Project Plan & Status

This document serves as a living record of our project plan, current status, and progress towards completing the cross-platform gaming application with Expo and Rust.

Current Status

Phase: Development Environment Setup
Current Task: Configuring WSL2 + Expo development environment
Last Updated: May 28, 2025

Project Vision

To create a cross-platform (iOS/Android/Web) gaming application that allows friends to connect, chat in real-time, and play games together, starting with tic-tac-toe and expanding to other games.

Architecture Overview

Technical Stack

  • Frontend: Expo + React Native with TypeScript (single codebase for all platforms)
  • Backend: Rust with Axum framework for WebSocket handling
  • Database & Auth: Supabase for user authentication and data persistence
  • Development: WSL2 + Ubuntu on Windows with VS Code
  • Deployment: EAS for mobile apps, containerized backend on Railway/Fly.io

Key Design Decisions

  • Single WebSocket connection per friendship (handles both chat and game data)
  • Message routing by type (chat, game_invite, game_move, game_end, presence)
  • Friend-based persistent connections (not ephemeral game rooms)
  • Cross-platform deployment from one React Native codebase

Development Approach

This project follows an iterative development approach with a focus on:

  • Cross-platform compatibility from day one
  • Real-time functionality as a core feature
  • Scalable architecture that can grow from chat to multiple game types
  • User experience across all platforms

User Flow

  1. Authentication: Users sign up/log in via Supabase
  2. Connection: Player 1 generates a connection link → creates pending connection
  3. Acceptance: Player 2 visits link → accepts connection → friendship established
  4. Interaction: Both players can chat and initiate games from their friend list
  5. Gaming: Real-time game data sharing over existing WebSocket connection

Development Roadmap

Phase 1: Development Environment Setup (3-4 days)

1.1 WSL2 Setup ⬜

  • Install WSL2 with Ubuntu 22.04 LTS
  • Install Windows Terminal for better WSL experience
  • Configure VS Code with WSL extension
  • Set up file system in WSL (~/projects/game-platform/)

1.2 WSL2 Development Tools ⬜

  • Install Node.js via nvm for version management
  • Install Expo CLI: npm install -g @expo/cli
  • Install Git and configure credentials
  • Install VS Code extensions: React Native Tools, Expo Tools

1.3 Rust Backend Setup ⬜

  • Install Rust toolchain (WSL2 or Windows)
  • Install Rust Analyzer extension
  • Test cross-compilation if mixing environments

1.4 Project Structure ⬜ 

~/projects/game-platform/
├── mobile-app/        # Expo + React Native
├── backend/          # Rust Axum WebSocket server  
├── shared-types/     # TypeScript definitions
└── docs/            # Documentation

1.5 Supabase Setup ⬜

  • Create Supabase project
  • Configure authentication
  • Design database schema (users, friendships, games, chat_messages)
  • Test connection from both WSL2 and Windows

Phase 2: Backend Foundation (1-2 weeks)

2.1 Basic Axum Server ⬜

  • Initialize Cargo project with dependencies
  • Create basic HTTP server with CORS
  • Health check and API versioning endpoints
  • Environment configuration

2.2 Supabase Integration ⬜

  • JWT verification middleware
  • User authentication endpoints
  • Database connection pooling

2.3 Connection Management System ⬜

  • Connection link generation endpoint
  • Link validation and expiration logic
  • Database schema for pending connections
  • Connection acceptance endpoint

2.4 WebSocket Infrastructure ⬜

  • WebSocket upgrade endpoint
  • Connection state management
  • Message routing by type
  • Graceful connection cleanup

Phase 3: Mobile App Foundation (1 week)

3.1 Expo Project Initialization ⬜

  • Create Expo app with TypeScript template
  • Configure app.json for all platforms
  • Set up Expo Router for navigation
  • Install core dependencies

3.2 Authentication System ⬜

  • Supabase Auth configuration
  • Login/Register screens
  • Secure token storage
  • Authentication context and protected routes

3.3 Core Navigation Structure ⬜

  • Auth screens (login/register)
  • Main tabs (friends, chat, game)
  • Connection flow screens

3.4 WebSocket Service ⬜

  • WebSocket connection manager class
  • Message type handling and routing
  • Automatic reconnection
  • Connection state management

Phase 4: Core Features Implementation (2-3 weeks)

4.1 Friend Connection System ⬜

  • Friends list screen
  • Connection link generation and sharing
  • QR code generation
  • Real-time connection status updates

4.2 Chat Functionality ⬜

  • Chat screen with message history
  • Real-time messaging via WebSocket
  • Message persistence in Supabase
  • Typing indicators and read receipts
  • Push notifications

4.3 Game System (Tic-Tac-Toe) ⬜

  • Game board component
  • Game state synchronization
  • Turn management and validation
  • Win/draw detection
  • Game history storage

Phase 5: Mobile-Specific Features (1 week)

5.1 Push Notifications ⬜

  • Expo Notifications setup
  • Backend notification triggers
  • Notification permissions
  • Deep linking from notifications

5.2 Native Features ⬜

  • Haptic feedback for game moves
  • Share API for connection links
  • Background app state handling
  • Network connectivity detection

5.3 UI/UX Polish ⬜

  • React Native styling and themes
  • Loading states and skeleton screens
  • Error boundaries and user feedback
  • Accessibility features

Phase 6: Testing and Optimization (1 week)

6.1 Development Testing ⬜

  • Expo Go testing on physical devices
  • iOS Simulator and Android Emulator testing
  • WebSocket connection reliability testing
  • Cross-platform UI consistency

6.2 Performance Optimization ⬜

  • Message batching for high-frequency updates
  • Efficient re-rendering with React.memo
  • Image optimization and caching
  • Bundle size optimization

Phase 7: Production Deployment (1 week)

7.1 Backend Deployment ⬜

  • Containerize Rust app with Docker
  • Deploy to Railway/Fly.io
  • Environment variables and secrets
  • SSL/TLS configuration

7.2 Mobile App Deployment ⬜

  • EAS Build configuration
  • App Store Connect and Google Play setup
  • TestFlight and Internal Testing
  • Production release

7.3 Web Deployment ⬜

  • Expo web build optimization
  • Deploy to Vercel/Netlify
  • PWA configuration

Key Decisions & Notes

Date Decision Rationale
May 28, 2025 Pivoted to Expo + React Native architecture Enables true cross-platform development from a single codebase, better mobile performance, and access to native features
May 28, 2025 Selected Rust + Axum for backend High-performance WebSocket handling, type safety, and excellent async support for real-time features
May 28, 2025 Chose WSL2 for development environment Solves Windows networking issues with Expo Go, provides Linux environment for better tooling
May 28, 2025 Adopted friend-based persistent connections Simplifies architecture compared to ephemeral game rooms, enables better chat integration
May 28, 2025 Selected Supabase for auth and database Provides ready-made authentication, real-time subscriptions, and PostgreSQL database

Core Features

Minimum Viable Product (MVP)

  • User registration and authentication
  • Friend connections via shareable links
  • Real-time chat between friends
  • Tic-tac-toe game with real-time moves
  • Push notifications for messages and game invites
  • Cross-platform support (iOS, Android, Web)

Future Enhancements

  • Additional games beyond tic-tac-toe
  • Group chats and multi-player games
  • Game statistics and leaderboards
  • Custom avatars and profiles
  • Game replays and sharing

Technology Migration Notes

From Web Components to React Native

  • Transitioning from Lit Web Components to React Native components
  • Moving from Shadow DOM to React Native’s component model
  • Replacing localStorage with expo-secure-store and Supabase

From WebSocket Testing to Real Implementation

  • Previous WebSocket testing patterns inform new implementation
  • Result pattern concepts can be adapted to TypeScript error handling
  • TDD principles apply but with React Native testing tools

Preserved Concepts

  • Type-safe error handling patterns
  • Component-based architecture
  • Real-time communication focus
  • User-centric design approach

Current Focus

Setting up the WSL2 development environment with Expo tooling. This foundation is critical for ensuring smooth cross-platform development throughout the project.

Immediate Next Steps

  1. Complete WSL2 and Ubuntu installation
  2. Configure VS Code for WSL development
  3. Install Expo CLI and create initial project
  4. Set up Rust development environment
  5. Create Supabase project and configure authentication

Estimated Timeline

Total Duration: 6-9 weeks

  • Environment Setup: 3-4 days
  • Backend Development: 1-2 weeks
  • Mobile App Foundation: 1 week
  • Core Features: 2-3 weeks
  • Polish & Native Features: 1 week
  • Testing: 1 week
  • Deployment: 1 week

Success Metrics

  • Cross-platform app working on iOS, Android, and Web
  • Real-time chat and game functionality
  • <100ms latency for game moves
  • 99.9% WebSocket connection reliability
  • App store approval for both iOS and Android
  • Positive user feedback on connection flow

Open Questions

  • How to handle offline gameplay and sync when reconnected?
  • Should we implement voice/video chat in future versions?
  • What analytics should we collect (with user consent)?
  • How to monetize (ads, premium features, or stay free)?
  • Should we add tournament/competition features?
  • How to handle user reporting and moderation?

Risk Mitigation

  • WSL2 Complexity: Document all setup steps, create setup scripts
  • Cross-platform Issues: Test early and often on all platforms
  • WebSocket Reliability: Implement robust reconnection logic
  • App Store Approval: Research guidelines early, implement required features
  • Scalability: Design for horizontal scaling from the start

Back to top

Copyright © 2025 Your Name. Distributed under an MIT license.