# 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/
```