heritagegraph: Instructions file for Claude Code

CLAUDE.md — Coding Conventions & AI Agent Style Guide

Purpose: This file tells AI coding agents exactly how to write code in this project — what patterns to follow, what to avoid, and how to stay consistent with the existing codebase.

---

🎯 Project Identity

• Project: HeritageGraph — Cultural Heritage Linked Open Data platform
• Organization: CAIR-Nepal
• Stack: Django REST Framework + Next.js 15 + NextAuth v4 + Google OAuth + Traefik + PostgreSQL
• Branch strategy: Work from v1 branch

---

🐍 Backend (Django REST Framework)

Python Version & Tooling

• Python: 3.12 (matches Dockerfile.backend and pyproject.toml)
• Formatter: ruff (configured in pyproject.toml) — replaces black/isort
• Linting: ruff — run ruff check . and ruff format .
• Package manager: pip with requirements.txt (no Poetry/PDM)
• WSGI server: gunicorn in production, runserver in dev

Django Settings Pattern

# Settings are split across files:
# settings/__init__.py reads DJANGO_ENV and dispatches
# Always import shared config:
from .base import *  # noqa: F403

• Never modify base.py for environment-specific config. Use development.py or production.py.
• All secrets must come from os.environ.get() in production. Use django-environ for .env loading.

Model Conventions

# Use UUID primary keys for new models
import uuid
from django.db import models

class MyModel(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        ordering = ["-created_at"]
        db_table = "my_model"  # explicit table name, snake_case

• New models should follow the CulturalEntity / Revision / Activity pattern (not the legacy Submission flat-field pattern).
• Use JSONField for flexible/extensible data — not 80+ CharFields.
• Always set db_table explicitly in Meta.
• Always add created_at and updated_at timestamps.