80 lines
3.2 KiB
Markdown
80 lines
3.2 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Running the Project
|
||
|
|
|
||
|
|
```bash
|
||
|
|
docker compose up # Start all services (db, backend, frontend)
|
||
|
|
docker compose up -d # Start in detached mode
|
||
|
|
docker compose down # Stop all services
|
||
|
|
docker compose build # Rebuild images after Dockerfile/requirements changes
|
||
|
|
```
|
||
|
|
|
||
|
|
Services:
|
||
|
|
- Django API: `http://localhost:8000`
|
||
|
|
- Frontend (Nginx): `http://localhost:5173`
|
||
|
|
|
||
|
|
Default dev admin: `admin@shooterhub.local` / `changeme`
|
||
|
|
|
||
|
|
## Django Commands (inside container or with venv)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
python manage.py migrate
|
||
|
|
python manage.py makemigrations
|
||
|
|
python manage.py compilemessages # Required after editing .po translation files
|
||
|
|
python manage.py shell
|
||
|
|
python manage.py create_default_admin
|
||
|
|
```
|
||
|
|
|
||
|
|
No test suite or linter is configured yet.
|
||
|
|
|
||
|
|
## Architecture Overview
|
||
|
|
|
||
|
|
**Backend**: Django 4.2 + Django REST Framework, PostgreSQL 16, JWT auth (simplejwt) + OAuth2 (allauth for Google/Apple).
|
||
|
|
|
||
|
|
**Frontend**: Vanilla JS + Bootstrap 5.3 served by Nginx. No build step — files are served as-is. `frontend/js/api.js` is the central API client handling JWT refresh logic.
|
||
|
|
|
||
|
|
### Django Apps (`apps/`)
|
||
|
|
|
||
|
|
| App | Responsibility |
|
||
|
|
|-----|----------------|
|
||
|
|
| `users` | Custom User model (email-based auth), language preference, avatar |
|
||
|
|
| `gears` | Firearm & equipment catalog + per-user inventory + reloading (recipes, ammo batches) |
|
||
|
|
| `tools` | Chronograph data ingestion, shot group analysis, PDF/chart generation |
|
||
|
|
| `photos` | Binary image storage in PostgreSQL, bullet-hole annotation, ballistic overlays |
|
||
|
|
|
||
|
|
### Key Architectural Patterns
|
||
|
|
|
||
|
|
- **Gear catalog moderation**: Items have PENDING/VERIFIED/REJECTED status. Verified items are shared community-wide; unverified are private. `GearCatalogMixin` in `gears/views.py` enforces this.
|
||
|
|
- **Ownership permissions**: Custom permission classes (`IsOwnerOrUnclaimed`, `IsAdminOrReadOnly`) in each app's `permissions.py`.
|
||
|
|
- **Photo storage**: Images are stored as raw bytes in a PostgreSQL `bytea` field (`Photo.data`) — no filesystem or S3 involved.
|
||
|
|
- **Chronograph analysis pipeline**: `apps/tools/analyzer/` contains independent modules — `parser.py` (CSV→DataFrame), `grouper.py` (shot clustering), `stats.py` (velocity stats), `charts.py` (matplotlib), `pdf_report.py` (fpdf2).
|
||
|
|
- **Anonymous sessions**: `ChronographAnalysis` can be unclaimed (no user FK), later claimed after login.
|
||
|
|
- **Nested routing**: Shot groups and shots are nested under chronograph analyses in the URL structure.
|
||
|
|
- **i18n**: 4 languages (en, fr, de, es). Django backend uses `.po`/`.mo` files; frontend uses `frontend/js/i18n.js`.
|
||
|
|
|
||
|
|
### URL Structure
|
||
|
|
|
||
|
|
All API routes are under `/api/`:
|
||
|
|
|
||
|
|
```
|
||
|
|
/api/auth/token/refresh/
|
||
|
|
/api/auth/social/google/
|
||
|
|
/api/auth/social/apple/
|
||
|
|
/api/users/profile/
|
||
|
|
/api/users/admin/
|
||
|
|
/api/gears/firearms/ /api/gears/scopes/ /api/gears/suppressors/ ...
|
||
|
|
/api/gears/ammo/
|
||
|
|
/api/gears/components/primers|brass|bullets|powders/
|
||
|
|
/api/inventory/
|
||
|
|
/api/rigs/
|
||
|
|
/api/reloading/recipes/ /api/reloading/batches/
|
||
|
|
/api/tools/chronograph/
|
||
|
|
/api/tools/chronograph/{id}/groups/
|
||
|
|
/api/tools/chronograph/{id}/groups/{gid}/shots/
|
||
|
|
/api/photos/upload/
|
||
|
|
/api/photos/{pk}/data/
|
||
|
|
/api/photos/group-photos/
|
||
|
|
```
|