Cline rules

1# Common Tasks
2 
3## Docker Commands
4 
5### Start Development Environment
6```bash
7./run_dev.sh
8```
9 
10### Start Production Environment
11```bash
12./run_prod.sh
13```
14> ⚠️ **Always use `./run_prod.sh` for production deploys** — it automatically backs up the database before restarting.
15 
16### On-demand Backup
17```bash
18./backup.sh dev    # Backup dev database now
19./backup.sh prod   # Backup prod database now
20```
21 
22### Restore from Backup
23```bash
24./restore.sh dev               # List available dev backups
25./restore.sh prod              # List available prod backups
26./restore.sh dev  backups/dev_20260226_090000.sql   # Restore specific backup
27./restore.sh prod backups/prod_20260226_090000.sql  # Restore specific backup
28```
29 
30### Stop Development Environment
31```bash
32./stop_dev.sh
33```
34 
35### Stop Production Environment
36```bash
37./stop_prod.sh
38```
39> ℹ️ `./stop_prod.sh` automatically backs up the database before stopping.
40 
41### ⚠️ DANGER — Volume Warning
42**NEVER** run `docker compose down -v` or `docker compose down --volumes` — this **permanently deletes all database data**.
43 
44The safe `down` command (no `-v`) is used inside all `run_*.sh` / `stop_*.sh` scripts.
45 
46### View Logs
47```bash
48# All services
49./logs_dev.sh
50 
51# Specific service
52docker logs sapi3d-backend -f
53docker logs sapi3d-frontend -f
54docker logs sapi3d-db -f
55```
56 
57### Access Database
58```bash
59docker exec -it sapi3d-db psql -U sapi3d -d sapi3d
60```
61 
62### Restart Specific Service
63```bash
64docker restart sapi3d-backend
65docker restart sapi3d-frontend
66```
67 
68## Database Backups
69 
70Backups are saved to the `backups/` directory as `dev_TIMESTAMP.sql` or `prod_TIMESTAMP.sql`.
71 
72Automatic backups happen on every `run_*.sh` and `stop_*.sh` call.
73 
74### On-demand Backup
75```bash
76./backup.sh dev    # Backup dev database now
77./backup.sh prod   # Backup prod database now
78```
79 
80### Restore from Backup
81```bash
82./restore.sh dev               # List available dev backups
83./restore.sh prod              # List available prod backups
84./restore.sh dev  backups/dev_20260226_090000.sql   # Restore specific backup
85./restore.sh prod backups/prod_20260226_090000.sql  # Restore specific backup
86```
87 
88> ℹ️ The `backups/` folder is in `.gitignore` — SQL dumps are not committed to the repo.
89 
90## Development Workflows
91 
92### Adding a New API Endpoint
93 
941. **Create/Edit Router** (`backend/app/api/routers/`)
952. **Create/Edit Service** (`backend/app/services/`)
963. **Create/Edit Repository** (`backend/app/repositories/`)
974. **Register Router** in `backend/app/main.py`
985. **Rebuild & Test**:
99```bash
100   ./run_dev.sh
101```
1026. **Test in Swagger**: http://localhost:8000/docs
103 
104### Adding a New Database Table
105 
1061. **Create Model** (`backend/app/models/`)
1072. **Create Schema** (`backend/app/schemas/`)
1083. **Create Repository** (`backend/app/repositories/`)
1094. **Rebuild Backend**:
110```bash
111   ./run_dev.sh
112```
1135. **Verify Table**: 
114```bash
115   docker exec -it sapi3d-db psql -U sapi3d -d sapi3d -c "\dt"
116```
117 
118### Adding a New React Component
119 
1201. **Create Component** (`frontend/src/components/`)
1212. **Import in Parent** (e.g., `App.jsx`)
1223. **Rebuild Frontend**:
123```bash
124   ./run_dev.sh
125```
1264. **Test**: http://localhost:3000
127 
128## Testing
129 
130### Run Backend Tests
131```bash
132cd backend
133./run_test.sh
134```
135 
136### Manual API Testing
137- **Swagger UI**: http://localhost:8000/docs
138- **ReDoc**: http://localhost:8000/redoc
139- **Curl Examples**: See `backend-curls.md`
140 
141## Debugging
142 
143### Check Container Status
144```bash
145docker ps
146```
147 
148### Check Container Logs
149```bash
150docker logs sapi3d-backend --tail 100
151docker logs sapi3d-frontend --tail 100
152docker logs sapi3d-db --tail 100
153```
154 
155### Access Backend Container Shell
156```bash
157docker exec -it sapi3d-backend bash
158```
159 
160### Access Frontend Container Shell
161```bash
162docker exec -it sapi3d-frontend sh
163```
164 
165### Check Database Connection
166```bash
167docker exec -it sapi3d-db psql -U sapi3d -d sapi3d -c "SELECT version();"
168```
169 
170### View Database Tables
171```bash
172docker exec -it sapi3d-db psql -U sapi3d -d sapi3d -c "\dt"
173```
174 
175## Common Issues
176 
177### Port Already in Use
178```bash
179# Find process using port
180sudo lsof -i :8000
181sudo lsof -i :3000
182 
183# Kill process
184kill -9 <PID>
185```
186 
187### Docker Build Cache Issues
188```bash
189# Clean rebuild (preserves database)
190./run_dev.sh
191```
192 
193### Database Connection Issues
194```bash
195# Check database is running
196docker ps | grep sapi3d-db
197 
198# Check database logs
199docker logs sapi3d-db
200 
201# Restart database
202docker restart sapi3d-db
203```
204 
205## Detailed Documentation
206 
207→ Complete workflows: `docs/development-guide.md`
208→ API testing: `docs/api-reference.md#testing-the-api`
209→ Troubleshooting: `docs/development-guide.md#troubleshooting`
210