# AGENTS.md

## Project Overview

This repository is a foundational Dockerized Django portfolio website. Local
development currently uses SQLite and a single Docker Compose `web` service.
Do not assume a frontend stack, deployment platform, or CI provider unless the
repository explicitly defines one.

## Working Principles

- Prefer small, reviewable changes with a clear purpose.
- Inspect the repository before making changes. Follow existing patterns once
  they exist instead of introducing parallel conventions.
- Keep local development Docker-first. Add and document Docker Compose commands
  when the Compose configuration is introduced.
- Do not hard-code credentials, secret keys, hostnames, or environment-specific
  configuration.
- Update `README.md`, this file, and `SECURITY.md` when implementation changes
  make their instructions inaccurate.

## Django Conventions

- Keep environment-specific settings outside committed source code. Load
  sensitive values from environment variables or a deployment secret store.
- Organize Django apps by domain responsibility. Avoid creating apps solely to
  mirror technical layers.
- Use Django migrations for schema changes. Commit generated migration files
  with the code that requires them.
- Review migrations before committing them. Avoid destructive schema changes
  without an explicit data migration or rollout plan.
- Keep views, forms, serializers, templates, and models focused. Extract shared
  behavior only when there is a concrete reuse case.
- Use Django's built-in security protections unless there is a documented
  reason to override them.

## Docker Workflow

Docker Compose is the preferred local interface:

```sh
docker compose up --build -d
docker compose exec web python manage.py check
docker compose exec web python manage.py migrate
docker compose exec web python manage.py test
docker compose run --rm frontend npm run test
docker compose run --rm frontend npm run build
docker compose down
```

Keep containers reproducible:

- Pin runtime versions and dependency versions using the chosen package
  manager's lock mechanism.
- Run application processes as a non-root user where practical.
- Do not bake secrets or local environment files into images.
- Add a `.dockerignore` when Docker files are introduced.
- Use a `.env.example` to record environment variables, and do not touch the production `.env`.
- The Web Container should be entirely self contained, without splitting the functionality into multiple containers. It should include both backend, frontend, integrated database, webserver, etc.

## Frontend Conventions

- Keep Django responsible for page rendering and use React only for focused
  interactive islands unless the architecture is intentionally changed.
- Build frontend assets with the one-shot Docker Compose `frontend` service.
- Keep npm dependencies pinned and commit `frontend/package-lock.json`.
- Keep generated frontend bundles out of version control. The Docker image
  builds its own production bundle.
- Treat committed TopoJSON map files as generated assets derived from Natural
  Earth data. Regenerate them deliberately rather than editing them by hand.

## Validation

Before considering a change complete, run the checks supported by the current
repository. Once available, this should include:

- Django system checks.
- The automated test suite.
- Migration consistency checks.
- Formatting, linting, and type checks selected by the project.
- A Docker image build and a basic container startup check for infrastructure
  changes.

If a check is not yet configured or cannot be run, state that clearly in the
change summary. Do not invent placeholder commands that appear executable.

## Change Hygiene

- Never commit `.env` files, secret values, local databases, uploaded media,
  caches, or generated build output.
- Add tests for behavior changes and regression fixes once the test harness
  exists.
- Keep documentation aligned with actual repository behavior.
- Avoid unrelated refactors in focused feature or bug-fix changes.