modern-django-starter/WARP.md

# WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

## Project Overview

This is a production-ready Django template with built-in authentication, social login (Google OAuth), role-based permissions, modern UI with Tailwind CSS, and Docker support. The project uses a custom User model with email-based authentication and role management through Django groups.

## Development Commands

### Initial Setup (Docker)
```bash
# Start all services (web, database, redis)
docker-compose up --build

# In separate terminals:
# Run database migrations and setup
docker-compose exec web python manage.py migrate
docker-compose exec web python manage.py create_groups
docker-compose exec web python manage.py createsuperuser

# Start Tailwind CSS development server (hot reloading)
docker-compose exec web python manage.py tailwind start
```

### Development Workflow
```bash
# Start development environment
docker-compose up -d

# View logs
docker-compose logs -f web

# Access Django shell
docker-compose exec web python manage.py shell

# Run migrations
docker-compose exec web python manage.py makemigrations
docker-compose exec web python manage.py migrate

# Create new Django app
docker-compose exec web python manage.py startapp myapp
# Remember to add 'apps.myapp' to INSTALLED_APPS in django_project/settings/base.py
```

### Testing & Quality
```bash
# Run tests (basic Django test runner)
docker-compose exec web python manage.py test

# Run tests with coverage (if coverage package is added)
docker-compose exec web coverage run --source='.' manage.py test
docker-compose exec web coverage report
```

### Tailwind CSS Development
```bash
# Start Tailwind watch mode for CSS hot reloading
docker-compose exec web python manage.py tailwind start

# Build production CSS
docker-compose exec web python manage.py tailwind build

# Install/update Tailwind dependencies
docker-compose exec web python manage.py tailwind install
```

### User Management
```bash
# Create user groups (admin, staff, user)
docker-compose exec web python manage.py create_groups

# Create superuser with admin role
docker-compose exec web python manage.py create_superuser --email admin@example.com --password admin123

# Setup social authentication apps
docker-compose exec web python manage.py setup_social_apps
```

### Production Deployment
```bash
# Production build
docker-compose -f docker-compose.prod.yml up --build -d

# Production database operations
docker-compose -f docker-compose.prod.yml exec web python manage.py migrate
docker-compose -f docker-compose.prod.yml exec web python manage.py collectstatic --noinput
```

## Architecture Overview

### Project Structure
- **django_project/**: Main Django project configuration
  - **settings/**: Environment-specific settings (base.py, development.py, production.py)
  - **urls.py**: Root URL configuration
- **apps/**: Django applications following app-per-feature pattern
  - **accounts/**: Custom user model, authentication, user management
  - **core/**: Core utilities, views, role-based decorators and mixins
- **templates/**: Global HTML templates
- **static/**: Static files (CSS, JS, images)
- **theme/**: Tailwind CSS integration
  - **static_src/**: Tailwind source files and Node.js setup
  - **static/css/dist/**: Generated CSS output

### Key Architectural Decisions

#### Authentication & User Management
- **Custom User Model**: `apps.accounts.User` extends AbstractUser with email as username field
- **Email-based Authentication**: Users authenticate with email instead of username
- **Role-based Access Control**: Uses Django groups (admin, staff, user) with custom methods:
  - `user.has_role(role_name)` - Check user role
  - `user.assign_role(role_name)` - Assign role to user
  - `@admin_required` and `@staff_required` decorators for views
  - `AdminRequiredMixin` and `StaffRequiredMixin` for class-based views
- **Django Allauth Integration**: Handles registration, email verification, password reset, and social authentication

#### Database Configuration
- **Flexible Database Setup**: Supports both individual environment variables and DATABASE_URL
- **External Database Support**: Ready for services like Neon, Supabase, Railway
- **SSL Support**: Configurable SSL mode for secure connections

#### Frontend & Styling
- **Tailwind CSS Integration**: Uses django-tailwind for seamless CSS development
- **Hot Reloading**: CSS automatically rebuilds during development
- **Production Optimization**: Compressed and minified CSS for production builds

#### Docker & Deployment
- **Multi-stage Dockerfile**: Separate development and production builds
- **Development Setup**: Docker Compose with PostgreSQL, Redis, hot reloading
- **Production Ready**: Gunicorn, Nginx, SSL support, security best practices

### Custom Management Commands
Located in `apps/accounts/management/commands/`:
- `create_groups`: Creates default user groups with appropriate permissions
- `create_superuser`: Creates admin user with default credentials
- `setup_social_apps`: Configures social authentication providers

### Settings Architecture
- **base.py**: Common settings for all environments
- **development.py**: Development-specific settings (DEBUG=True, console email backend)
- **production.py**: Production settings (security, performance optimizations)
- **Environment Variables**: All sensitive data configured via .env files

## Development Guidelines

### Adding New Features
1. Create new Django app: `docker-compose exec web python manage.py startapp feature_name`
2. Add to `INSTALLED_APPS` in `django_project/settings/base.py` as `apps.feature_name`
3. Create models, views, templates following existing patterns
4. Use role-based decorators/mixins for access control
5. Add URL patterns to both app-level and project-level URLs

### Database Migrations
- Always create migrations after model changes: `python manage.py makemigrations`
- Review migration files before applying
- Test migrations on copy of production data when possible

### Role-Based Access Control
- Use `@login_required` decorator for authenticated views
- Use `@admin_required` or `@staff_required` for role-specific views
- In templates, use `{% if user.has_role:'admin' %}` for conditional content
- For class-based views, inherit from `AdminRequiredMixin` or `StaffRequiredMixin`

### Tailwind CSS Development
- Edit templates with Tailwind utility classes
- Custom CSS goes in `theme/static_src/src/styles.css`
- Run `python manage.py tailwind start` for development with hot reloading
- Build for production with `python manage.py tailwind build`

### Environment Configuration
- Development: Copy `.env.example` to `.env`
- Production: Use strong SECRET_KEY, set DEBUG=False, configure email settings
- Database: Use DATABASE_URL for external services or individual DB_* variables for Docker

### Security Considerations
- Custom User model stores email as primary identifier
- Email verification required for account activation
- Login attempt limiting (5 attempts, 300s timeout)
- SSL support for external database connections
- CSRF and clickjacking protection enabled
- WhiteNoise for secure static file serving

### Social Authentication Setup
- Google OAuth: Configure in Google Cloud Console, set GOOGLE_OAUTH2_CLIENT_ID and GOOGLE_OAUTH2_CLIENT_SECRET
- Add more providers by extending SOCIALACCOUNT_PROVIDERS in settings
- Use `python manage.py setup_social_apps` to configure in Django admin

## URLs & Endpoints
- **Home**: `/` - Main landing page
- **Authentication**: `/accounts/` - Login, registration, email verification (django-allauth)
- **Admin**: `/admin/` - Django admin interface
- **API**: Ready for Django REST Framework integration

## Common Issues & Solutions

### CSS Not Loading
- Ensure Tailwind development server is running: `python manage.py tailwind start`
- Check that `theme` app is in INSTALLED_APPS
- Verify static files configuration

### Database Connection Issues
- For external databases, ensure SSL mode is correct (require/prefer)
- Check DATABASE_URL format for external services
- Verify PostgreSQL service is running in Docker

### Email Configuration
- Development: Uses console backend by default
- Production: Configure SMTP settings in environment variables
- Test email functionality with password reset flow

### Role Assignment
- Use management command: `python manage.py create_groups`
- Assign roles programmatically: `user.assign_role('admin')`
- Check roles in templates: `user.has_role:'staff'`

### Dokploy Deployment Issues
- **Static Files Permission Error**: If you see "Permission denied" errors during `collectstatic`:
  - This occurs when Docker volumes have different ownership than the container user
  - The project includes multiple fallback mechanisms in the entrypoint script
  - Static files are collected during Docker build as a backup
  - If collectstatic fails at runtime, the application will use build-time static files
- **Build Settings**: The project includes `django_project/settings/build.py` for static collection during Docker build
- **Volume Permissions**: Dokploy mounts volumes that may have host-system ownership