Cline rules

1# Validation Rules
2 
3## Critical Backend Rules
4 
5### Import Paths
6**MUST** be relative to `backend/app/` (NO `app.` prefix)
7 
8✅ **CORRECT**:
9```python
10from core.database import get_db
11from schemas.user import UserCreate
12from services.user_service import UserService
13from models.user import User
14from repositories.user_repository import UserRepository
15```
16 
17❌ **WRONG**:
18```python
19from app.core.database import get_db
20from backend.app.schemas.user import UserCreate
21```
22 
23### Password Handling
24**ALWAYS** hash passwords before storing in database
25 
26```python
27from core.security import hash_password, verify_password
28 
29# Hash before storing
30hashed = hash_password(plain_password)
31 
32# Verify on login
33is_valid = verify_password(plain_password, hashed)
34```
35 
36### Database Operations
37**ALWAYS** use async/await for all database operations
38 
39```python
40# ✅ CORRECT
41async def get_user(user_id: int, db: AsyncSession):
42    repo = UserRepository(db)
43    user = await repo.get_by_id(user_id)
44    return user
45```
46 
47### Database Writes
48**ALWAYS** commit after write operations
49 
50```python
51# ✅ CORRECT
52async def create_user(data: UserCreate, db: AsyncSession):
53    repo = UserRepository(db)
54    user = await repo.create(**data.model_dump())
55    await db.commit()  # Don't forget!
56    await db.refresh(user)  # Refresh to get updated data
57    return user
58```
59 
60### SQLAlchemy 2.0 Patterns
61Use modern syntax with type hints
62 
63```python
64from sqlalchemy.orm import Mapped, mapped_column
65 
66class User(Base):
67    __tablename__ = "users"
68    
69    user_id: Mapped[int] = mapped_column(primary_key=True)
70    username: Mapped[str]
71    email: Mapped[str]
72```
73 
74## Architecture Layer Rules
75 
76### API Layer (`backend/app/api/routers/`)
77- Handle HTTP request/response
78- Use Pydantic schemas for validation
79- Inject dependencies (database session)
80- NO business logic here
81 
82### Service Layer (`backend/app/services/`)
83- Implement business logic
84- Handle authentication/authorization
85- Calculate achievements
86- Enforce business rules
87- NO direct database access (use repositories)
88 
89### Repository Layer (`backend/app/repositories/`)
90- CRUD operations only
91- Custom database queries
92- Extend `BaseRepository` for common operations
93- NO business logic here
94 
95### Database Layer (`backend/app/models/`)
96- SQLAlchemy ORM models
97- Define table structure
98- Define relationships
99- NO business logic here
100 
101## Docker Rules
102 
103### Always Rebuild After Code Changes
104```bash
105docker compose down && docker compose up --build -d
106```
107 
108**Why?** Docker caches layers. Code changes won't reflect without rebuild.
109 
110## Pydantic Schema Rules
111 
112### Use `model_config` for ORM mode
113```python
114from pydantic import BaseModel, ConfigDict
115 
116class UserResponse(BaseModel):
117    model_config = ConfigDict(from_attributes=True)
118    
119    user_id: int
120    username: str
121```
122 
123### Separate Create/Update/Response schemas
124- `UserCreate` - For creating new records
125- `UserUpdate` - For updating existing records
126- `UserResponse` - For API responses
127 
128## FastAPI Dependency Injection
129 
130### Database Session
131```python
132from fastapi import Depends
133from core.database import get_db
134from sqlalchemy.ext.asyncio import AsyncSession
135 
136async def endpoint(db: AsyncSession = Depends(get_db)):
137    # Use db here
138    pass
139```
140 
141## Common Pitfalls to Avoid
142 
143❌ Forgetting to commit after database writes
144❌ Using sync code instead of async/await
145❌ Not hashing passwords before storing
146❌ Wrong import paths (using `app.` prefix)
147❌ Not rebuilding Docker containers after changes
148❌ Putting business logic in API layer
149❌ Direct database access from service layer (skip repository)
150 
151## Quick Reference
152 
153→ Detailed patterns: `docs/development-guide.md#common-patterns`
154→ Architecture details: `docs/architecture.md`
155→ Adding features: `docs/development-guide.md#adding-a-new-feature`
156