Internal
Public Access
Add CLAUDE.md documentation for Claude Code
Provides comprehensive guidance for future Claude Code instances including development commands, architecture overview, and common patterns. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Keith Smith
co-authored by
Claude Sonnet 4.5
Claude Sonnet 4.5
parent
7b4d024334
commit
cdcae378b7
@@ -0,0 +1,446 @@
|
|||||||
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||||
|
|
||||||
|
## Development Commands
|
||||||
|
|
||||||
|
### Local Development (Non-Docker)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Set environment for development
|
||||||
|
export DJANGO_SETTINGS_MODULE=config.settings.development
|
||||||
|
|
||||||
|
# Create and activate virtual environment
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||||
|
|
||||||
|
# Install dependencies
|
||||||
|
pip install -r requirements.txt
|
||||||
|
|
||||||
|
# Database operations
|
||||||
|
python manage.py migrate
|
||||||
|
python manage.py makemigrations
|
||||||
|
python manage.py createsuperuser
|
||||||
|
|
||||||
|
# Run development server
|
||||||
|
python manage.py runserver
|
||||||
|
|
||||||
|
# Run tests
|
||||||
|
python manage.py test
|
||||||
|
|
||||||
|
# Django shell
|
||||||
|
python manage.py shell
|
||||||
|
|
||||||
|
# Collect static files (for production)
|
||||||
|
python manage.py collectstatic --noinput
|
||||||
|
```
|
||||||
|
|
||||||
|
### Docker Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Development with live reload
|
||||||
|
make dev
|
||||||
|
make dev-build # Rebuild containers
|
||||||
|
|
||||||
|
# Production mode
|
||||||
|
make prod
|
||||||
|
make build # Build production containers
|
||||||
|
make deploy # Full deployment (pull, build, migrate, restart)
|
||||||
|
|
||||||
|
# Database operations
|
||||||
|
make migrate
|
||||||
|
make makemigrations
|
||||||
|
make createsuperuser
|
||||||
|
make dbshell # Access database shell
|
||||||
|
make backup # Backup database
|
||||||
|
|
||||||
|
# Monitoring
|
||||||
|
make logs # All container logs
|
||||||
|
make logs-web # Web container logs only
|
||||||
|
make logs-celery # Celery worker logs
|
||||||
|
make status # Container status
|
||||||
|
|
||||||
|
# Control
|
||||||
|
make stop
|
||||||
|
make restart
|
||||||
|
make clean # Stop and remove all containers/volumes
|
||||||
|
|
||||||
|
# Shell access
|
||||||
|
make shell # Django shell
|
||||||
|
make test # Run tests in container
|
||||||
|
```
|
||||||
|
|
||||||
|
### Celery (Background Tasks)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Local development (non-Docker)
|
||||||
|
# Terminal 1: Run Celery worker
|
||||||
|
celery -A config worker -l info
|
||||||
|
|
||||||
|
# Terminal 2: Run Celery beat (scheduled tasks)
|
||||||
|
celery -A config beat -l info
|
||||||
|
|
||||||
|
# In Docker, Celery runs automatically as separate services
|
||||||
|
```
|
||||||
|
|
||||||
|
## High-Level Architecture
|
||||||
|
|
||||||
|
### Django Apps
|
||||||
|
|
||||||
|
**users/** - User authentication and management
|
||||||
|
- Custom User model with email-based authentication (no username)
|
||||||
|
- Three-tier verification: email verification → admin approval → login
|
||||||
|
- JWT token authentication with refresh tokens
|
||||||
|
- Device token management for push notifications
|
||||||
|
- Rate-limited registration (5/hour) and login (10/hour)
|
||||||
|
|
||||||
|
**tasks/** - Core task management
|
||||||
|
- Hierarchical tasks with parent/subtask relationships
|
||||||
|
- Task status (pending, in_progress, completed, cancelled) and priority (low, medium, high, urgent)
|
||||||
|
- Recurrence patterns (daily, weekly, monthly, yearly, custom RRULE)
|
||||||
|
- Time tracking with start/stop timer functionality
|
||||||
|
- Tag system with colors and icons for organization
|
||||||
|
- Task sharing with permission levels (viewer/editor)
|
||||||
|
- Soft-delete architecture (is_deleted flag) for sync compatibility
|
||||||
|
|
||||||
|
**sync/** - Mobile app synchronization
|
||||||
|
- Offline-first bidirectional sync protocol
|
||||||
|
- Timestamp-based conflict detection with three resolution strategies (local, server, merged)
|
||||||
|
- Multi-device support with independent sync tokens per device
|
||||||
|
- Incremental sync (delta updates) and full sync support
|
||||||
|
- Uses sync_id (UUID) separate from Django id for mobile compatibility
|
||||||
|
- Soft-delete propagation to enable client-side deletion
|
||||||
|
|
||||||
|
**notifications/** - Email notifications and reminders
|
||||||
|
- Daily email digest (overdue + due today tasks)
|
||||||
|
- Timezone-aware scheduling (6-7 AM in user's local time)
|
||||||
|
- Deduplication (one email per user per day)
|
||||||
|
- Celery-based background processing
|
||||||
|
- Recurring task safety net (creates missed recurrences)
|
||||||
|
|
||||||
|
### Key Architectural Patterns
|
||||||
|
|
||||||
|
**UUID Primary Keys** - All models use UUID as primary key for distributed system compatibility and security.
|
||||||
|
|
||||||
|
**Dual ID System** - Each entity has both `id` (Django PK) and `sync_id` (for mobile sync). Sync protocol uses `sync_id` to maintain consistency across devices.
|
||||||
|
|
||||||
|
**Soft Delete Pattern** - All entities have `is_deleted` boolean instead of hard deletes. Dual managers enable filtering:
|
||||||
|
- `objects` - Default manager (excludes deleted)
|
||||||
|
- `all_objects` - Includes deleted items (used in sync)
|
||||||
|
|
||||||
|
**Multiple Serializers Per Context** - Different serializers for list/detail/sync endpoints to optimize performance:
|
||||||
|
- `TaskListSerializer` - Lightweight for list views
|
||||||
|
- `TaskSerializer` - Full details with nested subtasks
|
||||||
|
- `TaskSyncSerializer` - Uses sync_id, includes is_deleted
|
||||||
|
|
||||||
|
**Permission System** - Custom `IsOwnerOrReadOnlyIfShared` permission:
|
||||||
|
- Read access: Owner OR users with shared access
|
||||||
|
- Write access: Owner only
|
||||||
|
- Security filtering in serializers prevents tag/task leakage
|
||||||
|
|
||||||
|
**Custom Authentication Backend** - `EmailVerifiedApprovedBackend` enforces:
|
||||||
|
1. Email verification check
|
||||||
|
2. Admin approval check
|
||||||
|
3. Superusers bypass both checks
|
||||||
|
4. Stores error state in session for web UI
|
||||||
|
|
||||||
|
**Timezone-Aware Operations** - All time calculations use user's timezone:
|
||||||
|
- Daily emails scheduled in user's local 6-7 AM
|
||||||
|
- Overdue calculation relative to user's local date
|
||||||
|
- UTC storage, converted for display and logic
|
||||||
|
|
||||||
|
**Mobile App Support** - `AllowMobileAppFramingMiddleware` detects mobile app via User-Agent and removes X-Frame-Options to allow WebView embedding while maintaining security for web browsers.
|
||||||
|
|
||||||
|
### Sync Protocol Details
|
||||||
|
|
||||||
|
The sync endpoint (`POST /api/sync/`) handles offline-first synchronization:
|
||||||
|
|
||||||
|
**Request Format:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"device_id": "unique-device-id",
|
||||||
|
"last_sync_token": "previous-token-or-null",
|
||||||
|
"changes": {
|
||||||
|
"tasks": [...],
|
||||||
|
"tags": [...],
|
||||||
|
"time_entries": [...]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response Format:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"sync_token": "new-sync-token",
|
||||||
|
"server_time": "2025-01-10T12:00:00Z",
|
||||||
|
"server_changes": {
|
||||||
|
"tasks": [...],
|
||||||
|
"tags": [...],
|
||||||
|
"time_entries": [...]
|
||||||
|
},
|
||||||
|
"conflicts": [...]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Conflict Detection:** Compares `updated_at` timestamp between client's last sync and server's current state. If server modified entity since last sync, conflict is flagged.
|
||||||
|
|
||||||
|
**Conflict Resolution Strategies:**
|
||||||
|
- **local** - Apply client changes (overwrite server)
|
||||||
|
- **server** - Keep server version (discard client)
|
||||||
|
- **merged** - Accept manually merged data
|
||||||
|
|
||||||
|
### Celery Task Schedule
|
||||||
|
|
||||||
|
Configured in `config/celery.py`:
|
||||||
|
|
||||||
|
**send_daily_task_email** - Runs every hour
|
||||||
|
- Fetches users with email notifications enabled
|
||||||
|
- Converts UTC to user's timezone
|
||||||
|
- Sends email only if user's local time is 6-7 AM
|
||||||
|
- Checks for existing notification to prevent duplicates
|
||||||
|
- Groups tasks: overdue + due today (pending/in_progress only)
|
||||||
|
|
||||||
|
**process_recurring_tasks** - Runs daily at midnight
|
||||||
|
- Safety net for recurring task creation
|
||||||
|
- Processes completions from last 48 hours
|
||||||
|
- Creates next recurrence if missing
|
||||||
|
- Prevents duplicate recurrences
|
||||||
|
|
||||||
|
### Settings Modules
|
||||||
|
|
||||||
|
**config.settings.development** - Local development
|
||||||
|
- DEBUG=True
|
||||||
|
- SQLite database
|
||||||
|
- Console email backend
|
||||||
|
- Minimal security
|
||||||
|
|
||||||
|
**config.settings.production** - Production deployment
|
||||||
|
- DEBUG=False
|
||||||
|
- PostgreSQL required
|
||||||
|
- SMTP email backend
|
||||||
|
- Full security (HTTPS, CSP, HSTS)
|
||||||
|
- Gunicorn with multiple workers
|
||||||
|
|
||||||
|
**config.settings.selfhosted** - Docker/self-hosted
|
||||||
|
- Environment-based configuration
|
||||||
|
- PostgreSQL with health checks
|
||||||
|
- Redis for Celery
|
||||||
|
- Configurable workers and timeout
|
||||||
|
- WhiteNoise for static files
|
||||||
|
|
||||||
|
### Database Models Reference
|
||||||
|
|
||||||
|
**Task Model Fields:**
|
||||||
|
- Hierarchy: `parent` (ForeignKey to self)
|
||||||
|
- Status: pending, in_progress, completed, cancelled
|
||||||
|
- Priority: low, medium, high, urgent
|
||||||
|
- Recurrence: `recurrence_type`, `recurrence_interval`, `recurrence_rule` (RRULE)
|
||||||
|
- Timing: `due_date`, `due_time`, `completed_at`, `created_at`, `updated_at`
|
||||||
|
- Soft delete: `is_deleted` (filters via `SoftDeleteManager`)
|
||||||
|
- Sync: `sync_id` (UUID for mobile sync)
|
||||||
|
- Relationships: `tags` (ManyToMany), `time_entries` (reverse FK)
|
||||||
|
|
||||||
|
**User Model Fields:**
|
||||||
|
- Authentication: `email` (unique), `password`, `first_name`, `last_name`
|
||||||
|
- Verification: `email_verified`, `is_approved`, `approved_by`
|
||||||
|
- Preferences: `timezone`, `reminder_minutes_before`, `notifications_enabled`, `email_notifications_enabled`
|
||||||
|
- UUID primary key for security
|
||||||
|
|
||||||
|
**TimeEntry Model:**
|
||||||
|
- `start_time`, `end_time`, `duration` (auto-calculated)
|
||||||
|
- Foreign keys: `task`, `user`
|
||||||
|
- Soft delete: `is_deleted`
|
||||||
|
|
||||||
|
**TaskShare Model:**
|
||||||
|
- `shared_by`, `shared_with` (User FKs)
|
||||||
|
- `permission_level`: viewer, editor
|
||||||
|
- Can share tasks or tags
|
||||||
|
- Generic relation pattern
|
||||||
|
|
||||||
|
### API Endpoint Overview
|
||||||
|
|
||||||
|
**Authentication:**
|
||||||
|
- `POST /api/users/register/` - Create account (rate limited 5/hour)
|
||||||
|
- `POST /api/users/token/` - Login (rate limited 10/hour)
|
||||||
|
- `POST /api/users/token/refresh/` - Refresh JWT
|
||||||
|
- `POST /api/users/verify-email/` - Verify email token
|
||||||
|
- `POST /api/users/resend-verification/` - Resend verification email
|
||||||
|
|
||||||
|
**Tasks:**
|
||||||
|
- `GET/POST /api/tasks/` - List/create tasks (supports filtering by status, priority, tags, search)
|
||||||
|
- `GET/PUT/DELETE /api/tasks/<id>/` - Task detail operations
|
||||||
|
- `POST /api/tasks/<id>/start-timer/` - Start time tracking
|
||||||
|
- `POST /api/tasks/time-entries/<id>/stop/` - Stop timer
|
||||||
|
- `GET/POST /api/tasks/tags/` - Tag management
|
||||||
|
- `GET/POST /api/tasks/shares/` - Share management
|
||||||
|
|
||||||
|
**Sync:**
|
||||||
|
- `POST /api/sync/` - Main sync endpoint (rate limited 100/hour)
|
||||||
|
- `GET /api/sync/conflicts/` - List pending conflicts
|
||||||
|
- `POST /api/sync/conflicts/<id>/resolve/` - Resolve conflict
|
||||||
|
|
||||||
|
**Notifications:**
|
||||||
|
- `GET /api/notifications/` - List notifications
|
||||||
|
- `POST /api/notifications/<id>/read/` - Mark as read
|
||||||
|
- `POST /api/notifications/mark-all-read/` - Mark all read
|
||||||
|
- `GET /api/notifications/unread-count/` - Get unread count
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
Key variables (see `.env.example` and `stack.env.example`):
|
||||||
|
|
||||||
|
**Django Core:**
|
||||||
|
- `SECRET_KEY` - Django secret (generate with `python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"`)
|
||||||
|
- `DEBUG` - Debug mode (False in production)
|
||||||
|
- `ALLOWED_HOSTS` - Comma-separated hosts
|
||||||
|
- `CSRF_TRUSTED_ORIGINS` - HTTPS origins
|
||||||
|
- `SITE_DOMAIN` - Domain for email links
|
||||||
|
|
||||||
|
**Database:**
|
||||||
|
- `DATABASE_URL` - Connection string (e.g., `postgresql://user:pass@host:5432/db`)
|
||||||
|
|
||||||
|
**Redis & Celery:**
|
||||||
|
- `REDIS_URL` - Redis connection (e.g., `redis://localhost:6379/0`)
|
||||||
|
|
||||||
|
**Email:**
|
||||||
|
- `EMAIL_HOST`, `EMAIL_PORT`, `EMAIL_USE_TLS`
|
||||||
|
- `EMAIL_HOST_USER`, `EMAIL_HOST_PASSWORD`
|
||||||
|
- `DEFAULT_FROM_EMAIL` - Sender address
|
||||||
|
- `EMAIL_VERIFICATION_TOKEN_EXPIRY_HOURS` - Token validity (default: 24)
|
||||||
|
|
||||||
|
**Docker/Gunicorn:**
|
||||||
|
- `GUNICORN_WORKERS` - Worker processes (default: 3)
|
||||||
|
- `GUNICORN_TIMEOUT` - Request timeout (default: 60)
|
||||||
|
- `WEB_PORT` - External port (default: 8000)
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
|
||||||
|
Tests located in each app's `tests.py`. Run with:
|
||||||
|
```bash
|
||||||
|
python manage.py test # All tests
|
||||||
|
python manage.py test users # Specific app
|
||||||
|
python manage.py test users.tests.TestUserModel # Specific test
|
||||||
|
```
|
||||||
|
|
||||||
|
Docker:
|
||||||
|
```bash
|
||||||
|
make test # Run tests in container
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deployment Notes
|
||||||
|
|
||||||
|
**Docker Deployment:**
|
||||||
|
- Production uses PostgreSQL (postgres:16-alpine)
|
||||||
|
- Redis for Celery message broker (redis:7-alpine)
|
||||||
|
- Web service runs Gunicorn with configurable workers
|
||||||
|
- Celery worker and beat run as separate services
|
||||||
|
- Health checks on all services
|
||||||
|
- Named volumes for persistence (db_data, redis_data, static_files)
|
||||||
|
- Networks: frontend (web-facing), backend (internal services)
|
||||||
|
|
||||||
|
**Manual Deployment:**
|
||||||
|
- Use `config.settings.production` settings module
|
||||||
|
- Requires PostgreSQL (not SQLite)
|
||||||
|
- Configure SMTP for email
|
||||||
|
- Use Gunicorn behind Nginx reverse proxy
|
||||||
|
- Set up systemd services for Gunicorn, Celery worker, Celery beat
|
||||||
|
- Configure SSL/TLS certificates (Let's Encrypt recommended)
|
||||||
|
- Enable firewall (UFW) with SSH, HTTP, HTTPS only
|
||||||
|
|
||||||
|
**Production Checklist:**
|
||||||
|
- Set DEBUG=False
|
||||||
|
- Use strong SECRET_KEY
|
||||||
|
- Configure ALLOWED_HOSTS (no wildcards)
|
||||||
|
- Set CSRF_TRUSTED_ORIGINS for HTTPS
|
||||||
|
- Use PostgreSQL (not SQLite)
|
||||||
|
- Configure email backend (SMTP)
|
||||||
|
- Enable security headers (in settings)
|
||||||
|
- Set up SSL/TLS certificates
|
||||||
|
- Configure database backups
|
||||||
|
- Set up log rotation
|
||||||
|
- Monitor error logs and uptime
|
||||||
|
|
||||||
|
### Common Development Patterns
|
||||||
|
|
||||||
|
**Creating Recurring Tasks:** When a recurring task is marked complete, the next recurrence is automatically created in `tasks/models.py` `create_next_recurrence()` method. Celery task `process_recurring_tasks()` runs as safety net.
|
||||||
|
|
||||||
|
**Time Entry Workflow:**
|
||||||
|
1. `POST /api/tasks/<id>/start-timer/` creates TimeEntry with start_time
|
||||||
|
2. Running timer tracked in UI
|
||||||
|
3. `POST /api/time-entries/<id>/stop/` sets end_time and calculates duration
|
||||||
|
|
||||||
|
**Email Verification Flow:**
|
||||||
|
1. User registers → `email_verified=False`, `is_approved=False`
|
||||||
|
2. EmailVerificationToken created with 24-hour expiry
|
||||||
|
3. User clicks link → `email_verified=True`, token marked used
|
||||||
|
4. Admins notified via email
|
||||||
|
5. Admin approves in Django admin → `is_approved=True`
|
||||||
|
6. User notified and can now login
|
||||||
|
|
||||||
|
**Adding New Celery Tasks:**
|
||||||
|
1. Create task function in app's `tasks.py` with `@shared_task` decorator
|
||||||
|
2. Add to beat schedule in `config/celery.py` if periodic
|
||||||
|
3. Import in app's `__init__.py` to ensure task registration
|
||||||
|
4. Restart Celery worker and beat services
|
||||||
|
|
||||||
|
**Extending User Model:** The User model is in `users/models.py`. Add fields there, create migration, update serializers and admin if needed.
|
||||||
|
|
||||||
|
**Security Filtering:** When adding new endpoints that query related objects, filter by user in viewset's `get_queryset()`. Example from TaskViewSet:
|
||||||
|
```python
|
||||||
|
def get_queryset(self):
|
||||||
|
return Task.objects.filter(user=self.request.user)
|
||||||
|
```
|
||||||
|
|
||||||
|
### File Structure Reference
|
||||||
|
|
||||||
|
```
|
||||||
|
config/ # Django project configuration
|
||||||
|
settings/ # Environment-specific settings
|
||||||
|
base.py # Shared settings
|
||||||
|
development.py # Local development
|
||||||
|
production.py # Production deployment
|
||||||
|
selfhosted.py # Docker/self-hosted
|
||||||
|
celery.py # Celery configuration
|
||||||
|
urls.py # Root URL configuration
|
||||||
|
wsgi.py # WSGI entry point
|
||||||
|
|
||||||
|
users/ # User management app
|
||||||
|
models.py # User, DeviceToken, EmailVerificationToken
|
||||||
|
views.py # Registration, login, profile
|
||||||
|
serializers.py # User serializers
|
||||||
|
backends.py # EmailVerifiedApprovedBackend
|
||||||
|
utils.py # Email utilities
|
||||||
|
|
||||||
|
tasks/ # Task management app
|
||||||
|
models.py # Task, Tag, TimeEntry, TaskShare
|
||||||
|
views.py # Task CRUD, filtering, timers
|
||||||
|
serializers.py # Multiple serializers per context
|
||||||
|
middleware.py # AllowMobileAppFramingMiddleware
|
||||||
|
permissions.py # IsOwnerOrReadOnlyIfShared
|
||||||
|
|
||||||
|
sync/ # Mobile sync app
|
||||||
|
models.py # SyncLog, SyncConflict
|
||||||
|
views.py # Sync endpoint, conflict resolution
|
||||||
|
serializers.py # SyncSerializer with sync_id
|
||||||
|
|
||||||
|
notifications/ # Notifications app
|
||||||
|
models.py # Notification, ScheduledReminder
|
||||||
|
views.py # Notification CRUD
|
||||||
|
tasks.py # Celery tasks (daily email, recurring tasks)
|
||||||
|
|
||||||
|
templates/ # Django templates
|
||||||
|
base.html # Base template with dark mode
|
||||||
|
tasks/ # Task-related templates
|
||||||
|
users/ # User-related templates
|
||||||
|
|
||||||
|
static/ # Static assets
|
||||||
|
css/ # Stylesheets
|
||||||
|
js/ # JavaScript
|
||||||
|
|
||||||
|
docker/ # Docker-related files
|
||||||
|
docker-compose.yml # Production Docker setup
|
||||||
|
docker-compose.dev.yml # Development overrides
|
||||||
|
Dockerfile # Production image
|
||||||
|
Dockerfile.dev # Development image
|
||||||
|
Makefile # Docker command shortcuts
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user