Merge saas branch: add SaaS infrastructure

.cursor/mcp.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

.cursor/rules/railway.mdc

@@ -0,0 +1,6 @@
+---
+description: Railway.app is the service we use for production environments 
+globs: 
+alwaysApply: false
+---
+The build container system deletes any .md files, so if you need prompts, always use a .txt file 

.cursor/rules/routes.mdc

@@ -0,0 +1,92 @@
+---
+globs: src/api/routes/**
+alwaysApply: false
+---
+# API Routes
+
+All routes are automatically registered through `src/api/routes/__init__.py` → `server.py`.
+
+## Quick Start: Adding a New Route
+
+### 1. Create Route Module (e.g., `src/api/routes/my_feature.py`)
+
+```python
+"""My Feature Route - description"""
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+router = APIRouter()
+
+class MyResponse(BaseModel):
+    """Response model."""
+    message: str
+    data: dict
+
+@router.get("/my-feature", response_model=MyResponse)
+async def my_feature() -> MyResponse:
+    """Endpoint description."""
+    return MyResponse(message="success", data={"key": "value"})
+```
+
+### 2. Register in `src/api/routes/__init__.py`
+
+```python
+from .ping import router as ping_router
+from .my_feature import router as my_feature_router  # Add import
+
+all_routers = [
+    ping_router,
+    my_feature_router,  # Add to list
+]
+
+__all__ = ["all_routers", "ping_router", "my_feature_router"]  # Add to exports
+```
+
+### 3. Write Tests in `tests/e2e/test_my_feature.py`
+
+```python
+"""E2E tests for my feature endpoint"""
+from tests.e2e.e2e_test_base import E2ETestBase
+
+class TestMyFeature(E2ETestBase):
+    """Tests for my feature endpoint"""
+
+    def test_my_feature_endpoint(self):
+        """Test that endpoint works"""
+        response = self.client.get("/my-feature")
+        assert response.status_code == 200
+        assert response.json()["message"] == "success"
+```
+
+## Authentication
+
+For protected endpoints:
+
+```python
+from fastapi import Request, Depends
+from sqlalchemy.orm import Session
+from src.api.auth.unified_auth import get_authenticated_user_id
+from src.db.database import get_db_session
+
+@router.get("/protected")
+async def protected(request: Request, db: Session = Depends(get_db_session)):
+    user_id = await get_authenticated_user_id(request, db)  # Validates WorkOS JWT
+    return {"user_id": user_id}
+```
+
+## Subdirectory Routes
+
+For routes in subdirectories (e.g., `src/api/routes/payments/checkout.py`):
+
+```python
+# src/api/routes/payments/__init__.py
+from .checkout import router as checkout_router
+__all__ = ["checkout_router"]
+
+# src/api/routes/__init__.py
+from .payments import checkout_router
+all_routers = [ping_router, checkout_router]
+```
+
+## Reference: See `src/api/routes/ping.py` and `tests/e2e/test_ping.py` for complete examples

Makefile

@@ -116,6 +116,16 @@ ralph: check_jq ## Run Ralph agent loop
 	@echo "$(GREEN)✅ Ralph Agent finished.$(RESET)"
 
 
+########################################################
+# Run Server
+########################################################
+
+server: check_uv ## Start the server with uvicorn
+	@echo "$(GREEN)🚀Starting server...$(RESET)"
+	@PYTHONWARNINGS="ignore::DeprecationWarning:pydantic" uv run uvicorn src.server:app --host 0.0.0.0 --port $${PORT:-8000}
+	@echo "$(GREEN)✅Server stopped.$(RESET)"
+
+
 ########################################################
 # Run Tests
 ########################################################
@@ -259,3 +269,54 @@ requirements:
 	@echo "$(YELLOW)🔍Checking requirements...$(RESET)"
 	@cp requirements-dev.lock requirements.txt
 	@echo "$(GREEN)✅Requirements checked.$(RESET)"
+
+########################################################
+# Database & Migrations
+########################################################
+
+db_test: check_uv ## Test database connection and validate it's remote
+	@echo "$(YELLOW)🔍Testing database connection...$(RESET)"
+	@uv run python -c "from common import global_config; from urllib.parse import urlparse; \
+	    db_uri = str(global_config.database_uri); \
+	    assert db_uri, f'Invalid database: {db_uri}'; \
+	    parsed = urlparse(db_uri); \
+	    host = parsed.hostname or 'Unknown'; \
+	    print(f'✅ Remote database configured: {host}')"
+	@uv run alembic current >/dev/null 2>&1 && echo "$(GREEN)✅Database connection successful$(RESET)" || echo "$(RED)❌Database connection failed$(RESET)"
+
+db_migrate: check_uv ## Run pending database migrations
+	@echo "$(YELLOW)🔄Running database migrations...$(RESET)"
+	@uv run alembic upgrade head
+	@echo "$(GREEN)✅Database migrations completed.$(RESET)"
+
+db_validate: check_uv ## Validate database models and dependencies before migration
+	@echo "$(YELLOW)🔍Validating database models and dependencies...$(RESET)"
+	@uv run python scripts/validate_models.py
+	@echo "$(GREEN)✅Database validation completed.$(RESET)"
+
+db_migration: check_uv db_validate ## Create new database migration (requires msg='message')
+	@echo "$(YELLOW)📝Creating new migration...$(RESET)"
+	@if [ -z '$(msg)' ]; then \
+		echo "$(RED)❌ Please provide a message: make db_migration msg='your migration message'$(RESET)"; \
+		exit 1; \
+	fi
+	@uv run alembic revision --autogenerate -m '$(msg)'
+	@echo "$(GREEN)✅Migration created successfully.$(RESET)"
+
+db_downgrade: check_uv ## Downgrade database by one revision
+	@echo "$(YELLOW)⬇️ Downgrading database by 1 revision...$(RESET)"
+	@uv run alembic downgrade -1
+	@echo "$(GREEN)✅Database downgraded.$(RESET)"
+
+db_status: check_uv ## Show database migration status
+	@echo "$(YELLOW)📊Checking database migration status...$(RESET)"
+	@uv run alembic current
+	@uv run alembic history --verbose
+	@echo "$(GREEN)✅Database status check completed.$(RESET)"
+
+db_reset: check_uv ## Reset database (WARNING: destructive operation)
+	@echo "$(RED)🗑️ WARNING: This will drop all database tables!$(RESET)"
+	@read -p "Are you sure? (y/N): " confirm && [ "$$confirm" = "y" ] || exit 1
+	@uv run alembic downgrade base
+	@uv run alembic upgrade head
+	@echo "$(GREEN)✅Database reset completed.$(RESET)"

Procfile

@@ -0,0 +1 @@
+web: PYTHONWARNINGS="ignore::DeprecationWarning:pydantic" uvicorn src.server:app --host 0.0.0.0 --port $PORT --timeout-keep-alive 300 --timeout-graceful-shutdown 30