Cline rules

1# Architecture
2 
3## Layered Architecture Pattern
4 
5```
6┌─────────────────────────────────────┐
7│   API Layer (Routers)               │  ← HTTP Request/Response
8│   backend/app/api/routers/          │  ← Pydantic validation
9└─────────────────────────────────────┘
10              ↓
11┌─────────────────────────────────────┐
12│   Service Layer                     │  ← Business logic
13│   backend/app/services/             │  ← Authentication
14└─────────────────────────────────────┘  ← Achievements
15              ↓
16┌─────────────────────────────────────┐
17│   Repository Layer                  │  ← CRUD operations
18│   backend/app/repositories/         │  ← Custom queries
19└─────────────────────────────────────┘
20              ↓
21┌─────────────────────────────────────┐
22│   Database Layer (Models)           │  ← SQLAlchemy ORM
23│   backend/app/models/               │  ← Table definitions
24└─────────────────────────────────────┘
25```
26 
27## Layer Responsibilities
28 
29### API Layer (`backend/app/api/routers/`)
30- Handle HTTP request/response
31- Use Pydantic schemas for validation
32- Inject dependencies (database session)
33- **NO business logic here**
34 
35### Service Layer (`backend/app/services/`)
36- Implement business logic
37- Handle authentication/authorization
38- Calculate achievements
39- Enforce business rules
40- **NO direct database access** (use repositories)
41 
42### Repository Layer (`backend/app/repositories/`)
43- CRUD operations only
44- Custom database queries
45- Extend `BaseRepository` for common operations
46- **NO business logic here**
47 
48### Database Layer (`backend/app/models/`)
49- SQLAlchemy ORM models
50- Define table structure
51- Define relationships
52- **NO business logic here**
53 
54## Key Design Decisions
55 
56### Async/Await Throughout
57All database operations use async/await for better performance:
58```python
59async def get_user(user_id: int, db: AsyncSession):
60    repo = UserRepository(db)
61    user = await repo.get_by_id(user_id)
62    return user
63```
64 
65### SQLAlchemy 2.0 Modern Syntax
66Using type hints and modern patterns:
67```python
68from sqlalchemy.orm import Mapped, mapped_column
69 
70class User(Base):
71    user_id: Mapped[int] = mapped_column(primary_key=True)
72    username: Mapped[str]
73```
74 
75### Dependency Injection
76FastAPI's dependency injection for database sessions:
77```python
78from fastapi import Depends
79from core.database import get_db
80 
81async def endpoint(db: AsyncSession = Depends(get_db)):
82    # Use db here
83```
84 
85## Frontend Architecture
86 
87### React Component Structure
88```
89frontend/src/
90├── components/
91│   ├── Navbar.jsx          ← Top navigation
92│   ├── Sidebar.jsx         ← Side menu
93│   ├── Login.jsx           ← Authentication
94│   ├── Register.jsx        ← User registration
95│   └── three/
96│       ├── ThreeScene.jsx  ← Main 3D scene
97│       ├── Building.jsx    ← 3D model loader
98│       ├── PlayerMovement.js ← First-person controls
99│       └── Metrics.js      ← Performance tracking
100└── services/
101    └── api.js              ← API client
102```
103 
104### Three.js Integration
105- First-person camera controls
106- GLB model loading
107- Collision detection
108- Performance metrics
109 
110## Detailed Documentation
111 
112→ Complete architecture diagrams: `docs/architecture.md`
113→ Design decisions: `docs/architecture.md#design-decisions`
114→ Directory structure: `docs/architecture.md#directory-structure`
115