feat: User tier & limits system (#96)

[DevanshuNEU]

Summary

Implements centralized user tier and limits management system as foundation for #94, #95, and #93.

Tier System

Tier	Repos	Files/Repo	Functions/Repo	Playground/Day
Free	3	500	2,000	50
Pro	20	5,000	20,000	∞
Enterprise	∞	50,000	200,000	∞

New API Endpoints

GET /api/v1/users/usage        - Get tier, limits, current usage
GET /api/v1/users/limits/check-repo-add  - Pre-check before adding repo

Files Changed

New Files

File	Purpose
backend/services/user_limits.py	Core tier/limits service (454 lines)
backend/routes/users.py	User usage API endpoints
supabase/migrations/001_user_profiles.sql	Database migration
supabase/README.md	Migration documentation
docs/TIER_SYSTEM_DESIGN.md	Full design document

Modified Files

File	Change
backend/dependencies.py	Initialize UserLimitsService
backend/main.py	Register users router

Production-Ready Features

Security

• ✅ RLS policies - users can only read own profile
• ✅ No UPDATE policy for users (prevents self-upgrade)
• ✅ Tier updates only via service role key
• ✅ Input validation on user_id

Error Handling

• ✅ Sentry integration for exception capture
• ✅ Fail-CLOSED on DB errors during limit checks
• ✅ Graceful Redis degradation (continue without cache)
• ✅ Proper error codes: REPO_LIMIT_REACHED, REPO_TOO_LARGE, INVALID_USER, SYSTEM_ERROR

Observability

• ✅ Structured logging with user_id, tier, limits
• ✅ Metrics: user_limit_exceeded with tags
• ✅ Cache hit/miss tracking

Usage Example

from dependencies import user_limits

# Check if user can add repo (fails CLOSED if DB down)
result = user_limits.check_repo_count(user_id)
if not result.allowed:
    raise HTTPException(403, detail=result.to_dict())

# Response includes tier for upgrade prompts
# {"allowed": false, "tier": "free", "error_code": "REPO_LIMIT_REACHED", ...}

Database Migration

Run supabase/migrations/001_user_profiles.sql in Supabase SQL Editor:

• Creates user_profiles table
• Auto-creates profile on signup (trigger)
• RLS enabled (SELECT/INSERT only for users)

Testing Checklist

• Run migration in Supabase
• Test GET /users/usage endpoint
• Test GET /users/limits/check-repo-add endpoint
• Verify tier caching works (check Redis)
• Test fail-closed behavior (stop DB, try to add repo)

Related Issues

• Foundation for security(backend): Add repository size limits before indexing - prevent API cost abuse #94 (repo size limits)
• Foundation for feat(backend): Add repo count limits per user tier #95 (repo count limits)
• Foundation for security(playground): Rate limit resets on page refresh - API cost exposure #93 (playground rate limiting)

Closes #96

[vercel]

@DevanshuNEU is attempting to deploy a commit to the Dev's projects Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
opencodeintel	Ignored	Preview	Dec 13, 2025 1:27am