LogicArena

A competitive platform for practicing formal logic and natural deduction proofs.

Features

• Natural deduction proof system with Fitch-style notation
• Interactive proof editor with syntax highlighting
• Real-time proof validation
• Practice mode with puzzles of varying difficulty
• Timed duel matches between players
• Elo-based rating system
• User profiles and statistics tracking
• Progressive tutorial system
• Secure authentication with Supabase
• Responsive design for mobile and desktop

Tech Stack

Frontend

• Next.js 14 (App Router)
• TypeScript
• Tailwind CSS
• Framer Motion
• Monaco Editor
• Supabase Auth (SSR)

Backend

• FastAPI
• PostgreSQL with SQLAlchemy
• Redis for caching and real-time features
• Supabase for authentication

Proof Checking

• Custom natural deduction proof validator
• Support for propositional logic
• Fitch-style proof notation

Getting Started

Prerequisites

• Node.js 18+
• Python 3.11+
• PostgreSQL 15+
• Redis
• Supabase account (for authentication)

Installation

1. Clone the repository:

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

2. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configuration
   # Add Supabase URL and keys

3. Install frontend dependencies:

   cd front
   npm install

4. Install backend dependencies:

   cd gateway
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt

5. Run database migrations:

   cd gateway
   python -m alembic upgrade head
   # Run Supabase auth migration
   python migrations/20250724_000003_add_supabase_id.py

6. Start the development servers:

   Backend:

   cd gateway
   uvicorn main:app --reload

   Frontend:

   cd front
   npm run dev

7. Access the application at http://localhost:3000

Authentication Setup

Supabase Configuration

1. Create a project at supabase.com
2. Copy your project URL and anon key
3. Add to .env:

   NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

4. Enable email/password authentication in Supabase dashboard
5. Configure redirect URLs for your domain

See docs/SUPABASE_AUTH_GUIDE.md for detailed setup instructions.

Project Structure

LogicArena/
├── front/                 # Next.js frontend
│   ├── src/
│   │   ├── app/          # App router pages
│   │   ├── components/   # React components
│   │   ├── contexts/     # React contexts (Auth, Toast)
│   │   ├── hooks/        # Custom hooks
│   │   ├── lib/          # Utilities and API
│   │   └── utils/        # Supabase clients
│   └── public/           # Static assets
├── gateway/              # FastAPI backend
│   ├── app/
│   │   ├── models.py     # SQLAlchemy models
│   │   ├── puzzles/      # Puzzle endpoints
│   │   ├── users/        # User endpoints
│   │   └── games/        # Game logic
│   └── migrations/       # Database migrations
├── puzzle/               # Proof validation service
└── docs/                 # Documentation

Key Features Documentation

Practice Mode

• Solve puzzles at your own pace
• Multiple difficulty levels
• Category-based puzzle selection
• Hint system for learning
• Progress tracking

Tutorial System

• 6 chapter lessons covering formal logic
• 3 interactive practice tutorials
• Step-by-step guidance
• Progress tracking

User Profiles

• Experience points and leveling
• Achievement system
• Puzzle solving statistics
• Activity history

Responsive Design

• Mobile-optimized UI
• Touch-friendly interactions
• Adaptive layouts
• Progressive web app ready

Development

Running Tests

Frontend:

cd front
npm test

Backend:

cd gateway
pytest

Code Quality

Frontend:

npm run lint
npm run typecheck

Backend:

ruff check .
mypy .

Deployment

See docs/DEPLOYMENT.md for production deployment instructions.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT License

Acknowledgments

• Inspired by formal logic education needs
• Built with modern web technologies
• Powered by Supabase authentication