Cline rules

1# File Locations
2 
3## Backend Structure (`backend/app/`)
4 
5### API Layer
6```
7backend/app/api/routers/
8├── auth_router.py      ← Authentication endpoints
9├── health.py           ← Health check endpoint
10├── model.py            ← 3D model serving endpoints
11└── user_router.py      ← User management endpoints
12```
13 
14### Service Layer
15```
16backend/app/services/
17├── auth_service.py     ← Authentication business logic
18└── user_service.py     ← User management business logic
19```
20 
21### Repository Layer
22```
23backend/app/repositories/
24├── base.py             ← BaseRepository with common CRUD
25├── session_repository.py ← Session data access
26└── user_repository.py  ← User data access
27```
28 
29### Database Models
30```
31backend/app/models/
32├── achievement.py      ← Achievement & UserAchievement models
33├── base.py             ← Base model class
34├── location.py         ← Location model
35├── metrics.py          ← Metrics & MetricSnapshot models
36├── session.py          ← Session & Device models
37└── user.py             ← User, Role, UserRole models
38```
39 
40### Pydantic Schemas
41```
42backend/app/schemas/
43├── achievement.py      ← Achievement schemas
44├── location.py         ← Location schemas
45├── metrics.py          ← Metrics schemas
46├── model.py            ← 3D model schemas
47├── session.py          ← Session schemas
48└── user.py             ← User schemas
49```
50 
51### Core Configuration
52```
53backend/app/core/
54├── config.py           ← Application settings
55├── database.py         ← Database connection & session
56├── logging.py          ← Logging configuration
57└── security.py         ← Password hashing & JWT
58```
59 
60### Static Files
61```
62backend/static/models/
63├── sapi3D_V1.2.glb     ← Main 3D building model
64└── sapi3Dasynctrigger.glb ← Alternative model
65```
66 
67## Frontend Structure (`frontend/src/`)
68 
69### Components
70```
71frontend/src/components/
72├── Login.jsx           ← Login form
73├── Login.css           ← Login styles
74├── Register.jsx        ← Registration form
75├── Register.css        ← Registration styles
76├── Navbar.jsx          ← Top navigation bar
77├── Sidebar.jsx         ← Side menu
78└── three/
79    ├── ThreeScene.jsx  ← Main 3D scene container
80    ├── Building.jsx    ← 3D model loader
81    ├── PlayerMovement.js ← First-person controls
82    └── Metrics.js      ← Performance tracking
83```
84 
85### Services
86```
87frontend/src/services/
88└── api.js              ← API client (axios)
89```
90 
91### Main Files
92```
93frontend/src/
94├── App.jsx             ← Main application component
95├── App.css             ← Application styles
96├── main.jsx            ← React entry point
97└── index.css           ← Global styles
98```
99 
100## Documentation (`docs/`)
101 
102```
103docs/
104├── index.md            ← Documentation hub
105├── architecture.md     ← Architecture diagrams & details
106├── api-reference.md    ← API endpoint reference
107├── development-guide.md ← Development workflows
108└── features.md         ← Feature documentation
109```
110 
111## Configuration Files
112 
113### Root Level
114```
115/
116├── docker-compose.base.yml   ← Base Docker config
117├── docker-compose.dev.yml    ← Development overrides
118├── docker-compose.prod.yml   ← Production overrides
119├── .env.dev                  ← Development environment
120├── .env.prod                 ← Production environment
121├── run_dev.sh                ← Start development
122├── run_prod.sh               ← Start production
123├── stop_dev.sh               ← Stop development
124├── stop_prod.sh              ← Stop production
125└── logs_dev.sh               ← View development logs
126```
127 
128### Backend Config
129```
130backend/
131├── Dockerfile          ← Backend container definition
132├── pyproject.toml      ← Python dependencies (Poetry)
133└── run_test.sh         ← Run tests
134```
135 
136### Frontend Config
137```
138frontend/
139├── Dockerfile          ← Frontend container definition
140├── nginx.conf          ← Nginx configuration (production)
141├── package.json        ← Node dependencies
142└── vite.config.js      ← Vite configuration
143```
144 
145## Quick File Lookup
146 
147### Need to add a new endpoint?
148→ `backend/app/api/routers/` (create or edit router)
149→ `backend/app/main.py` (register router)
150 
151### Need to add business logic?
152→ `backend/app/services/` (create or edit service)
153 
154### Need to add database queries?
155→ `backend/app/repositories/` (create or edit repository)
156 
157### Need to add a database table?
158→ `backend/app/models/` (create or edit model)
159 
160### Need to add API schemas?
161→ `backend/app/schemas/` (create or edit schema)
162 
163### Need to add a React component?
164→ `frontend/src/components/` (create component)
165 
166### Need to modify 3D scene?
167→ `frontend/src/components/three/` (edit Three.js components)
168 
169## Detailed Documentation
170 
171→ Complete directory structure: `docs/architecture.md#directory-structure`
172→ Adding new features: `docs/development-guide.md#adding-a-new-feature`
173