Instruction file imported from anyistudio/SmashMate (.cursor/rules/001-backend-core.mdc). Copyright stays with the author.

This rule should ALWAYS be applied when the AI is working inside the Smash Mate backend.

Stack: Python 3.11 · uv · FastAPI · SQLAlchemy 2.0 (Async) · Supabase Local Development · PostGIS · PyTest · pydantic-settings. Architectural constraints: async DB access only, domain logic isolated in services/, rating logic uses trueskill synchronously inside a DB transaction. Security: Supabase JWT auth, explicit RLS checks, no raw SQL string concat. ALWAYS follow these rules. version: "1.0"

Smash Mate Backend – Core Rules

Use case

Smash Mate is a social companion app for groups of badminton players who regularly meet at the same venue. After signing in with Google or Apple, a player selects or creates the venue they're currently in, follows other players who play there, records doubles-match results, and instantly sees updated TrueSkill ratings for each individual and for every fixed pair. By comparing a pair's team rating with the average of the two players' individual ratings, the app derives a "compatibility score" that highlights how well the two partners mesh and periodically recommends promising new partners.

Core functionalties

•	User authentication via Google / Apple, profile management, and choice of current venue
•	Venue creation, nearby-venue search with geo queries (PostGIS), and venue selection persistence
•	Social layer: follow / unfollow other players at the same venue and view mutual followers
•	Match recording: pick four followed players, enter scores once, shareable edit access for all participants
•	Synchronous TrueSkill computation upon match submission, updating player, team, and history records in one transaction
•	On-the-fly compatibility calculation from player and team ratings (team_mu - avg_individual_mu), computed dynamically for optimal efficiency
•	Leaderboards and personal dashboards showing individual, team, and compatibility rankings
•	Periodic partner-recommendation feed that surfaces high-compatibility players a user hasn't teamed with yet
•	Real-time updates to matches, ratings, and recommendations through Supabase Realtime channels
•	Full row-level security so only involved players can view or edit a match, with optimistic-lock versioning to avoid conflicts

Compatibility Score Calculation

• Formula: compatibility_score = team_mu - ((player1_mu + player2_mu) / 2)
• Approach: Calculated on-the-fly in application layer, not stored in database
• Benefits: Always up-to-date, more efficient than materialized views, no refresh needed
• Implementation: Located in app/services/database.py methods get_compatibility_scores() and get_recommended_partners()

Project Structure

app/
├── api/          # API endpoints
├── core/         # Core functionality
├── models/       # SQLAlchemy models
├── schemas/      # Pydantic schemas
└── services/     # Business logic

tests/
├── api/          # API tests
├── integration/  # Integration tests
└── unit/         # Unit tests

Tech Stack

• Package Manager: uv
• Framework: FastAPI
• Database: Supabase Local Development (PostgreSQL + PostGIS)
• ORM: SQLAlchemy 2.0 (Async)
• Testing: pytest, supabase-py

Virtual Environment Usage

• Always activate the virtual environment before running commands:

  source .venv/bin/activate  # On Unix/macOS

• After activating the virtual environment, run commands directly:

  pytest  # Instead of uv pip run pytest
  uvicorn app.main:app --reload  # Instead of uv pip run uvicorn

Code Style

• Follow PEP 8
• Use type hints
• Document public APIs
• Keep functions small and focused
• Use async/await for I/O operations

Database

• Use SQLAlchemy async session
• Define models in app/models/
• Use Alembic for migrations
• Follow naming conventions:
  • Tables: plural, snake_case
  • Columns: snake_case
  • Foreign keys: {table_name}_id

API Design

• RESTful endpoints
• Version all endpoints (/api/v1/...)
• Use proper HTTP methods
• Return appropriate status codes
• Document with OpenAPI/Swagger

Testing

• Write tests for all new features
• Use pytest fixtures
• Mock external services
• Test edge cases
• Use supabase-py for Supabase integration testing

Security

• Use Supabase Auth for authentication
• Implement Row Level Security (RLS)
• Validate all input
• Sanitize database queries
• Use environment variables for secrets

Error Handling

• Use custom exceptions
• Log errors properly
• Return meaningful error messages
• Handle edge cases gracefully

Performance

• Use async operations
• Optimize database queries
• Cache when appropriate
• Monitor response times

Documentation

• Keep README up to date
• Document API endpoints
• Add inline comments for complex logic
• Update migration summaries

Local Development

• Use Supabase CLI for local development
• Run tests before committing