CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Running the Project

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)

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/

3.2 KiB Raw Blame History