heritagegraph: Instructions file for Codex

AGENTS.md — AI Agent Instructions for HeritageGraph

Purpose: This file gives AI coding agents (GPT, Claude, Copilot, Cursor, Cody, etc.) the full context they need to work effectively in this codebase. Read this file first before making any changes.

🧠 What Is This Project?

HeritageGraph is a full-stack platform by CAIR-Nepal for digitally preserving and publishing cultural heritage data as linked open data. It has:

• A Django REST Framework backend (API, auth, data models)
• A Next.js 15 main app (heritage_graph_ui) — dashboard, contribution forms, graph visualization
• A Next.js 15 marketing landing (heritage_graph_landing) — public site; same brand colors as the dashboard
• NextAuth v4 + Google OAuth for authentication
• Traefik as reverse proxy (routes traffic, handles TLS)
• PostgreSQL as database (Django backend)

📁 Repository Structure

heritagegraph/
│
├── heritage_graph/              # Django backend (DRF)
│   ├── apps/
│   │   ├── heritage_data/       # Main app: submissions, moderation, profiles
│   │   ├── cidoc_data/          # CIDOC-CRM ontology, identity layer, RDF projection
│   │   ├── graph/               # KG engine (Oxigraph), museum enrichment, KG APIs
│   │   ├── document_processing/ # Document upload (OCR pipeline suspended)
│   │   ├── assistant/           # Grounded in-app chat (OpenRouter)
│   │   └── health_check.py      # /health/ endpoints for Docker/Traefik
│   ├── celery_app.py            # **NEW** Celery app initialization (imported from `heritage_graph/__init__.py`)
│   ├── settings/
│   │   ├── __init__.py          # Env-based dispatch (DJANGO_ENV → dev or prod)
│   │   ├── base.py              # Shared settings (apps, middleware, DRF config, Celery)
│   │   ├── development.py       # Dev: SQLite, DEBUG=True, Celery eager mode
│   │   └── production.py        # Prod: PostgreSQL, env-based secrets
│   ├── urls.py                  # Root URL configuration
│   ├── entrypoint.sh            # Docker entrypoint (migrate, superuser, start)
│   ├── manage.py                # Django management
│   └── requirements.txt         # Python dependencies
│
├── heritage_graph_ui/           # Next.js 15 main app (authenticated product UI)
│   ├── src/
│   │   ├── app/                 # App Router pages
│   │   │   ├── layout.tsx       # Root layout (SessionProvider, ThemeProvider)
│   │   │   ├── (dashboard)/     # Dashboard route group (sidebar layout)
│   │   │   │   ├── page.tsx     # Dashboard home (/)
│   │   │   │   ├── knowledge/   # Knowledge base CRUD (entity, person, etc.)
│   │   │   │   ├── contribute/  # Contribution forms
│   │   │   │   ├── curation/    # Moderation & activity logs
│   │   │   │   │   ├── contributions/  # Contribution queue
│   │   │   │   │   ├── activity/       # Activity log
│   │   │   │   │   ├── review/         # Triaged review queue
│   │   │   │   │   │   └── [id]/       # Three-panel review workspace
│   │   │   │   │   ├── identity/       # Identity resolution queue + workspace
│   │   │   │   │   ├── conflicts/      # Conflict resolution
│   │   │   │   │   └── dashboard/      # Reviewer dashboard
│   │   │   │   ├── community/   # Contributors & organizations
│   │   │   │   └── graphview/   # Graph visualization (Cytoscape)
│   │   │   └── api/auth/        # NextAuth API route
│   │   ├── components/          # Shared components (shadcn/ui, data tables, chat)
│   │   ├── providers/           # Context providers (ChatContext)
│   │   ├── hooks/               # Custom hooks (use-mobile)
│   │   └── lib/                 # Utilities (auth.ts, utils.ts, chat/)
│   ├── types/                   # TypeScript type augmentations
│   └── public/                  # Static assets
│
├── heritage_graph_landing/      # Next.js 15 marketing site (port 3001 locally)
│   ├── src/app/                 # Public landing + chat widget (calls same assistant API)
│   └── README.md                # Env: NEXT_PUBLIC_APP_URL → main app origin
│
├── infra/                       # Infrastructure configs
│   ├── traefik/                 # Traefik reverse proxy config
│   ├── postgres/                # Database init scripts
│   └── docker/                  # Legacy docker-compose files (reference only)
│
├── docker-compose.yml           # Main compose: all services (dev)
├── docker-compose-coolify.yml   # Coolify (platform proxy; no in-repo Traefik)
├── docker-compose-dokploy.yml   # Dokploy (same + MIGRATION_AUTO_REPAIR, landing build args)
├── documentation/deployment/    # DEPLOYMENT.md, DOKPLOY.md, Coolify runbooks
├── docker-compose.prod.yml      # Production override (HTTPS, Let's Encrypt)
├── Dockerfile.backend           # Backend multi-stage build
├── Dockerfile.frontend          # Same as heritage_graph_ui/Dockerfile (repo-root `-f` alias)
├── Makefile                     # Convenience commands
├── .env.example                 # Environment variable template
├── tests/                       # E2E runners (see documentation/testing/TESTING.md)
└── documentation/               # Topic guides (see DOCS.md)