CLAUDE.md

Codebase Guidelines

Architecture

• This is a Django project built on Python 3.14.
• User authentication uses django-allauth.
• The front end is mostly standard Django views and templates.
• HTMX and Alpine.js are used to provide single-page-app user experience with Django templates. HTMX is used for interactions which require accessing the backend, and Alpine.js is used for browser-only interactions.
• JavaScript files are kept in the /assets/ folder and built by vite. JavaScript code is typically loaded via the static files framework inside Django templates using django-vite.
• APIs use Django Rest Framework, and JavaScript code that interacts with APIs uses an auto-generated OpenAPI-schema-baesd client.
• The front end uses Tailwind (Version 4) and DaisyUI.
• The main database is Postgres.
• Celery is used for background jobs and scheduled tasks.
• Redis is used as the default cache, and the message broker for Celery (if enabled).

Commands you can run

The following commands can be used for various tools and workflows. A Makefile is provided to help centralize commands:

make  # List available commands

First-time Setup

make init

Starting the Application

Start background services:

make start     # Run in foreground with logs
make start-bg  # Run in background

Start the app:

make dev       # Run in foreground with logs

Access the app at http://localhost:8000

Stopping Services

Stop background services:

make stop

Common Commands

Development

make shell            # Open Python / Django shell
make dbshell          # Open PostgreSQL shell
make manage ARGS='command'  # Run any Django management command

Database

make migrations       # Create new migrations
make migrate          # Apply migrations

Testing

make test                              # Run all tests
make test ARGS='apps.module.tests.test_file'  # Run specific test
make test ARGS='path.to.test --keepdb'        # Run with options

Python Code Quality

make ruff-format      # Format code
make ruff-lint        # Lint and auto-fix
make ruff             # Run both format and lint

Python

make uv add '<package>'         # Add a new package
make uv run '<command> <args>'  # Run a Python command

Frontend

make npm-install      # Install npm packages
make npm-install package-name  # Install specific package
make npm-uninstall package-name  # Uninstall package
make npm-dev          # Run the Vite development server
make npm-build        # Build for production
make npm-type-check   # Run TypeScript type checking

Note: Vite runs automatically with hot-reload when using make dev.

Code generation

make uv run 'pegasus startapp <app_name> <Model1> <Model2Name>'  # Start a new Django app (models are optional)

General Coding Preferences

• Always prefer simple solutions.
• Avoid duplication of code whenever possible, which means checking for other areas of the codebase that might already have similar code and functionality.
• You are careful to only make changes that are requested or you are confident are well understood and related to the change being requested.
• When fixing an issue or bug, do not introduce a new pattern or technology without first exhausting all options for the existing implementation. And if you finally do this, make sure to remove the old implementation afterwards so we don’t have duplicate logic.
• Keep the codebase clean and organized.
• Avoid writing scripts in files if possible, especially if the script is likely only to be run once.
• Try to avoid having files over 200-300 lines of code. Refactor at that point.
• Don't ever add mock data to functions. Only add mocks to tests or utilities that are only used by tests.
• Always think about what other areas of code might be affected by any changes made.
• Never overwrite my .env file without first asking and confirming.

Python Code Guidelines

Code Style

• Follow PEP 8 with 120 character line limit.
• Use double quotes for Python strings (ruff enforced).
• Sort imports with isort (via ruff).
• Try to use type hints in new code. However, strict type-checking is not enforced and you can leave them out if it's burdensome. There is no need to add type hints to existing code if it does not already use them.

Type annotation conventions

Type checking runs with mypy + django-stubs (make type-check). Conventions:

• Routed views leave request unannotated (all of them, even views that don't touch request.user). mypy can't see the guarantees made by @login_required and similar decorators, so annotating request: HttpRequest makes accesses like request.user.<related> fail type checking. Everything that isn't a routed view — middleware, context processors, signal handlers, forms, internal helpers — should annotate request: HttpRequest normally.
• In DRF views where a permission class guarantees authentication, get the typed user via apps.users.helpers.get_authenticated_user(request) rather than casting request.user inline.

Python 3.14 syntax notes

• Unparenthesized except with multiple exception types is valid (PEP 758, Python 3.14+). except ValueError, TypeError: is equivalent to except (ValueError, TypeError): — it is not Python 2 syntax and will not raise a SyntaxError. Parentheses are still required when using as (e.g. except (ValueError, TypeError) as e:). Do not "fix" unparenthesized forms unless an as clause is being added.

Preferred Practices

• Use Django signals sparingly and document them well.
• Always use the Django ORM if possible. Use best practices like lazily evaluating querysets and selecting or prefetching related objects when necessary.
• Use function-based views by default, unless using a framework that relies on class-based views (e.g. Django Rest Framework).
• Always validate user input server-side.
• Handle errors explicitly, avoid silent failures.

Django models

• All Django models should extend apps.utils.models.BaseModel (which adds created_at and updated_at fields).
• The project's user model is apps.users.models.CustomUser and should be imported directly.

Django Template Coding Guidelines for HTML files

• Indent templates with two spaces.
• Use standard Django template syntax.
• For multi-line comments, use {% comment %}...{% endcomment %}. The {# ... #} syntax is single-line only and does NOT work across multiple lines — never write {# first line\n second line #}.
• JavaScript and CSS files built with vite should be included with the {% vite_asset %} template tag provided by django-vite (must have {% load django_vite %} at the top of the template)
• Any react components also need {% vite_react_refresh %} for Vite + React's HMR functionality, from the same django_vite template library)
• Use the Django {% static %} tag for loading images and external JavaScript / CSS files not managed by vite.
• Prefer using alpine.js for page-level JavaScript, and avoid inline <script> tags where possible.
• Break re-usable template components into separate templates with {% include %} statements. These normally go into a components folder.
• Use DaisyUI styling markup for available components. When not available, fall back to standard TailwindCSS classes.
• Stick with the DaisyUI color palette whenever possible.

JavaScript Code Guidelines

Code Style

• Use ES6+ syntax for JavaScript code.
• Use 2 spaces for indentation in JavaScript, JSX, and HTML files.
• Use single quotes for JavaScript strings.
• End statements with semicolons.
• Use camelCase for variable and function names.
• Use PascalCase for component names (React).
• Use explicit type annotations in TypeScript files.
• Use ES6 import/export syntax for module management.

Preferred Practices

• When using HTMX, follow progressive enhancement patterns.
• Use Alpine.js for client-side interactivity that doesn't require server interaction.
• Avoid inline <script> tags wherever posisble.
• Validate user input on both client and server side.
• Handle errors explicitly in promise chains and async functions.

Build System

• Code is bundled using vite and served with django-vite.