Merge branch 'dev' into test/import-sessions-speakers-v2

Author: Saksham-Sirohi

.agents/context/architecture.md

@@ -0,0 +1,40 @@
+# Django Backend Architecture Context
+
+## Core Structure & Philosophy
+
+The Django project lives entirely under `app/`. The project has evolved from a legacy structure to the unified `eventyay` (ENext) application.
+
+- The primary package is `eventyay` (`DJANGO_SETTINGS_MODULE` points here).
+- You will see legacy directories (like `src/`, `talk/`, `video/`) in older branches, but they are historical. All active product code lives strictly inside `app/eventyay/`.
+
+## Directory Map (`app/eventyay/`)
+
+```text
+app/
+├── eventyay/           # Main unifying package
+│   ├── config/         # System configuration and settings.py files
+│   ├── api/            # DRF viewsets, serializers, routers
+│   ├── base/           # Core shared models, managers, forms, and middleware
+│   ├── control/        # Organiser back-office (management UI, forms, urls)
+│   ├── presale/        # Attendee-facing (ticket purchase, public pages, urls)
+│   ├── eventyay_common/  # Modern shared UI components and base templates
+│   ├── webapp/         # Modern Vue 3 bundled front-end applications
+│   ├── static/         # Legacy/Django-served static assets (CSS, images)
+│   ├── celery.py       # Celery task application configuration
+│   └── plugins/        # Extendible plugin architecture definitions
+├── tests/              # Pytest testing suite
+└── manage.py
+```
+
+> **Crucial Rule on Sub-apps:** Models and forms are distributed *inside* their respective domain sub-apps to guarantee domain-driven design separation. 
+> - Examples: `base/models/`, `control/forms/`, `presale/forms/` 
+> - **Do NOT** place models or forms directly in a new root-level standalone directory. 
+> - By standard convention, most system models inherit from a core database class located within `app/eventyay/base/`.
+
+## System Settings Layer
+
+Configuration is strictly divided between base settings and environment-specific overrides:
+
+- **Base defaults:** Handled dynamically via `app/eventyay/config/settings.py` (review the `BaseSettings` setup class).
+- **Environment Overrides:** Configuration is TOML-based (`eventyay.development.toml`, `eventyay.production.toml`) plus an optional `eventyay.local.toml` for strict local machine overrides.
+- **Execution Context:** The active mode executes according to the `EVY_RUNNING_ENVIRONMENT` OS environment variable which defaults depending on context (`development`, `production`, etc.).

.agents/skills/django-add-form/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: django-add-form
+description: Steps for creating or modifying Django forms and adding validation
+---
+
+## When to use
+
+Use this skill when building or editing forms handling user input for views like back-office organizers (`control/`) or attendee-facing routes (`presale/`).
+
+## Steps
+
+1. Place the new form class strictly alongside its relevant sub-app (e.g., `app/eventyay/base/forms/`, `app/eventyay/control/forms/`).
+2. Add specific, individual field-level validation by implementing `clean_<field>()` methods.
+3. Add multi-field or cross-field validation logic by implementing generic `clean()` method overrides.
+
+## Validation
+
+1. Confirm the form has definitively been organized within its intended domain scope (e.g. keeping control constraints strictly out of presale domains).
+
+## Gotchas
+
+- Do not bypass Django's built-in validation mechanisms logic when working with forms.
+- Do not mix `control/forms/` configurations into `presale/` logic.

.agents/skills/django-create-api-endpoint/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: django-create-api-endpoint
+description: Steps for adding a new Django REST Framework API endpoint
+---
+
+## When to use
+
+Use this skill when exposing new data or functionality via the DRF API using viewsets and serializers.
+
+## Steps
+
+1. Create or update a serializer in the appropriate location within `app/eventyay/api/`. Prefer using explicit serializer fields covering direct model or nested relation mappings.
+2. Create or update a viewset within `app/eventyay/api/`.
+3. Register the new viewset's router in the appropriate module router or `app/eventyay/api/urls.py`.
+
+## Validation
+
+1. Verify that the serializer correctly maps exactly to the expected model or relations without unnecessary custom method wrappers.
+2. Assert the endpoint resolves effectively.
+
+## Gotchas
+
+- **Computed Data Overuse:** Only use `SerializerMethodField` for genuinely computed or conditional data. Do NOT use it if a direct field assignment natively exists.

.agents/skills/django-create-model/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: django-create-model
+description: Steps for creating or modifying a Django model
+---
+
+## When to use
+
+Use this skill when defining a new database model or modifying an existing one.
+
+## Steps
+
+1. Locate the correct sub-app for the model (e.g., `app/eventyay/base/models/` for shared models or a specific sub-app's `models.py`).
+2. Define the model class. Ensure it inherits from a base class located in `app/eventyay/base/` if applicable.
+3. Define the related model managers.
+
+## Validation
+
+1. Verify the model file is placed correctly inside the sub-app's directory hierarchy.
+2. Confirm the model isn't mistakenly placed in a standalone top-level directory.
+
+## Gotchas
+
+- Cross-check standard rules (`agents.md`) when writing model queries, especially regarding event multi-tenancy (`django_scopes.scope(event=event)`).

.agents/skills/django-run-locally/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: django-run-locally
+description: Steps for initiating the Django development server without Docker
+---
+
+## When to use
+
+Use this skill to spin up or invoke the local development backend sequence for rapid testing processes.
+
+## Steps
+
+1. Navigate securely into the active architecture directory: `cd app`
+2. Synchronously install or update environment dependencies strictly through `uv`: `uv sync --all-extras --all-groups`
+3. Activate the standard CLI venv wrapper: `. .venv/bin/activate`
+4. Deploy local DB schema synchronization calls: `python manage.py migrate`
+5. *(Optional)* Setup initial admin: `python manage.py create_admin_user`
+6. Build Frontend Assets:
+   ```bash
+   make npminstall
+   python manage.py collectstatic --noinput
+   python manage.py compress --force
+   ```
+7. Initialize the development environment natively: `python manage.py runserver`
+
+## Validation
+
+1. Verify server startup output bindings properly format against standard generic ports (ex. `127.0.0.1:8000`).
+2. There should be **no pending/unapplied migration warnings** displayed.
+3. Verify `http://127.0.0.1:8000` loads properly without missing CSS/MIME type errors.
+
+## Gotchas
+
+- **Strict Environment Imports**: If context dynamically requires variable settings locally, ALWAYS safely fetch these utilizing `from django.conf import settings`. Never import the isolated system settings configuration natively (e.g. absolutely never execute `from eventyay.config import settings`).
+- **CSS not loading / MIME type errors**: Ensure you have successfully run `collectstatic` and `compress --force` steps to properly build the Javascript/CSS chunks.

.agents/skills/django-run-migrations/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: django-run-migrations
+description: Steps for generating and applying Django migrations
+---
+
+## When to use
+
+Use this skill continuously after modifying any `models.py` schema logic to apply the changes to the database.
+
+## Steps
+
+1. Navigate to the app context: `cd app/`
+2. Generate the required migration definitions by running: `python manage.py makemigrations`
+3. Execute and apply the generated migration file to the DB safely: `python manage.py migrate`
+
+## Validation
+
+1. Verify that the terminal explicitly outputs "Applying..." states and succeeds without tracebacks.
+2. Quickly review the auto-generated `.py` migration output to ensure logical alignment with your model edits.
+
+## Gotchas
+
+- **Do not manually edit auto-generated migration files** unless executing an explicitly necessary, advanced requirement (i.e. complex data backfill operations). Never rewrite migrations that have already been applied to a shared or production database; instead, create a new migration for any additional schema changes.
+
+## Tips
+If your changes in Django models don't cause a change in the actual database schema, you don't need to create a migration at all. 
+
+Typical changes that do **not** affect the DB schema include:
+- `choices`
+- `verbose_name`
+- `help_text`
+
+In these cases:
+- Do not run `makemigrations` just to capture these metadata-only changes.
+- Do not edit existing migration files that may already have been applied. The only safe exception is in a narrowly scoped, pre-merge situation where a migration has never been applied to any shared or production database and you are cleaning up that pending migration before it lands. Otherwise, always create a new migration to capture real schema changes.

.agents/skills/docker-deployment/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: docker-deployment
+description: Docker Compose, container services, deployment
+---
+
+# Skill: Docker Deployment
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `docker-compose.yml` | Development / local Compose stack |
+| `deployment/docker-compose.yml` | Production Compose stack |
+| `deployment/env.sample` | Sample production environment variables |
+| `deployment/env.dev.sample` | Sample development environment variables |
+| `deployment/nginx/` | Nginx reverse-proxy configuration |
+| `DEPLOYMENT.md` | Step-by-step production deployment guide |
+
+## Services (Development Stack)
+
+| Service | Image / Build | Role |
+|---|---|---|
+| `web` | `./app` (Dockerfile) | Django dev server on port 8000 |
+| `worker` | `./app` (Dockerfile) | Celery task worker |
+| `redis` | `redis:latest` | Message broker and cache |
+| `db` | `postgres:15` | PostgreSQL database |
+
+## Building and Running (Development)
+
+```bash
+# Copy and edit environment variables
+cp deployment/env.dev.sample .env.dev
+
+# Build images and start all services
+docker compose up --build
+
+# Run with detached containers
+docker compose up -d --build
+
+# View logs
+docker compose logs -f web
+docker compose logs -f worker
+
+# Stop all services
+docker compose down
+```
+
+## Running a Management Command Inside a Container
+
+```bash
+docker compose exec web python manage.py migrate
+docker compose exec web python manage.py createsuperuser
+```
+
+## Development vs Production
+
+| Aspect | Development (`docker-compose.yml`) | Production (`deployment/docker-compose.yml`) |
+|---|---|---|
+| Web server | Django `runserver` | Gunicorn behind Nginx |
+| Static files | Served by Django | Pre-built and served by Nginx |
+| Env file | `.env.dev` | `.env` |
+| Hot reload | Yes (volume mount) | No |
+
+## Environment Variables
+
+Required variables are documented in `deployment/env.sample` and `deployment/env.dev.sample`. At minimum, set:
+
+- `EVY_SECRET_KEY`
+- individual `EVY_POSTGRES_*` vars
+- `EVY_REDIS_URL`
+- `EVY_SITE_URL` (production only)
+
+See `DEPLOYMENT.md` for the full production setup walkthrough, including Nginx, SSL (certbot), and backup configuration.

.agents/skills/documentation/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: documentation
+description: How to update project documentation
+---
+
+# Skill: Documentation
+
+## Documentation Files
+
+| File | Purpose |
+|---|---|
+| `README.rst` | Project overview and getting-started guide (reStructuredText) |
+| `CONTRIBUTING.md` | Contributor guidelines and development setup |
+| `DEPLOYMENT.md` | Production deployment walkthrough |
+| `.github/instructions/dockerfile.instructions.md` | Docker Compose usage and container reference |
+| `doc/` | Extended project documentation |
+
+## How to Update `README.rst`
+
+- Written in **reStructuredText** (`.rst`).
+- Keep the getting-started steps current when CLI commands or workflows change.
+- Maintain existing section structure; add new sections at a logical location.
+
+## How to Update `doc/`
+
+- Files may be `.rst` or `.md` depending on the sub-section.
+- Follow the existing style of the surrounding files.
+- Run a documentation build locally if a build pipeline is configured.
+
+## How to Update `CONTRIBUTING.md`
+
+- Keep the setup instructions in sync with `README.rst`.
+- Document any new tooling or workflow changes that affect contributors.
+
+## General Guidelines
+
+- Keep documentation concise and accurate.
+- Prefer concrete examples over abstract descriptions.
+- When changing a CLI command, update all documentation that references it.
+- Documentation changes do not require tests unless there are specific doc-tests.

.agents/skills/repo-navigation/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: repo-navigation
+description: Repository layout and where to find code
+---
+
+# Skill: Repository Navigation
+
+## Top-level Layout
+
+```
+.
+├── app/                    # Main Django application
+├── deployment/             # Infrastructure and deployment configs
+├── doc/                    # Project documentation
+├── .github/instructions/   # File-scoped AI coding guidance
+├── .agents/skills/         # AI agent skill files (this directory)
+├── agents.md               # Canonical AI agent policy
+├── docker-compose.yml      # Docker Compose for local/dev environment
+├── DEPLOYMENT.md           # Production deployment walkthrough
+├── CONTRIBUTING.md         # Contributor guidelines
+└── README.rst              # Project overview
+```
+
+## Application Root: `app/`
+
+```
+app/
+├── eventyay/               # Core Django application package
+├── tests/                  # Test suite
+├── pyproject.toml          # Project metadata and dependencies
+└── manage.py               # Django management entry point
+```
+
+## Core Application: `app/eventyay/`
+
+| Directory | Purpose |
+|---|---|
+| `api/` | REST API endpoints (Django REST Framework) |
+| `base/` | Shared models (`base/models/`), utilities, middleware, and forms (`base/forms/`) |
+| `control/` | Organiser/back-office views, forms, and URLs |
+| `presale/` | Attendee-facing (ticket purchase) views and forms |
+| `common/` | Cross-cutting helpers shared across modules |
+| `config/` | Application configuration and settings |
+| `plugins/` | Plugin infrastructure |
+| `static/` | Static assets (CSS, JS, images) |
+| `jinja-templates/` | Jinja HTML templates |
+| `locale/` | Translation files |
+| `mail/` | Email rendering and sending |
+| `celery.py` / `celery_app.py` | Celery task configuration |
+
+> **Note:** Models, forms, and templates are distributed inside sub-apps
+> (e.g. `base/models/`, `control/forms/`, `presale/templates/`), not in
+> standalone top-level directories.
+
+## Deployment: `deployment/`
+
+```
+deployment/
+├── docker-compose.yml      # Production Compose file
+├── env.sample              # Sample environment variables
+├── env.dev.sample          # Sample dev environment variables
+└── nginx/                  # Nginx configuration
+```
+
+## Documentation: `doc/`
+
+Contains extended project documentation written in reStructuredText or Markdown.
+
+## Key Lookup Shortcuts
+
+- **Add a model** → `app/eventyay/<sub-app>/models.py` or `app/eventyay/base/models/`
+- **Add an API endpoint** → `app/eventyay/api/`
+- **Add a form** → `app/eventyay/<sub-app>/forms.py` or `app/eventyay/<sub-app>/forms/`
+- **Add a migration** → run `python manage.py makemigrations` from `app/`
+- **Add a test** → `app/tests/`