CLAUDE.md Template: Angular Material + Django File Upload App

Overview

This CLAUDE.md template documents how to scaffold a full-stack project using Angular Material on the frontend and Django for the backend with a robust file-upload feature. It targets a stack with Angular, Django REST Framework, and Claude Code workflows to generate repeatable boilerplates.

When to Use This CLAUDE.md Template

• You are building a file-upload capable app with Angular Material UI and a Django REST API for upload endpoints.
• You want a fixed, copyable CLAUDE.md block to paste into your CLAUDE.md file for standardization.
• You require explicit architecture, authentication, validation, and deployment rules tailored to this stack.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Full-stack Developer (Angular Material frontend, Django backend)

Architecture rules:
- Use Django REST Framework for API endpoints, including a dedicated /api/uploads/ endpoint for files.
- Frontend uses Angular Material components and HttpClient for API calls.
- Separate concerns: backend API handles business logic; frontend handles rendering and input validation.

File structure rules:
- frontend/ (Angular app)
- backend/ (Django project)
- shared/libs/ (shared utilities, types)

Authentication rules:
- JWT authentication using djangorestframework-simplejwt. Tokens stored in HttpOnly cookies.
- CSRF protection enabled for HTML views; API should accept a valid JWT in Authorization header.

Database rules:
- PostgreSQL recommended. Models: FileUpload (id, file, filename, mime_type, size, uploaded_at, uploaded_by).
- Use database constraints for unique filenames per user per upload session when required.

Validation rules:
- Accept only allowed MIME types: image/*, application/pdf, text/plain, and application/zip (configurable).
- Enforce max file size of 10MB by default; provide a per-upload override via API if needed.

Security rules:
- Do not expose filesystem paths. Store files under MEDIA_ROOT and use signed URLs where possible.
- Enable CORS with a strict allowed-origin list for your frontend.

Testing rules:
- Backend: pytest tests for upload API, serializer validation, and permissions.
- Frontend: unit tests for Angular services and components; e2e tests for upload flows.
- End-to-end: verify file uploads store metadata and the binary in the storage backend.

Deployment rules:
- Docker Compose: services for frontend, backend, and a PostgreSQL container. Use environment variables and secrets management.
- CI/CD: run tests on PRs; build and publish Docker images on merge.

Things Claude must not do:
- Do not bypass authentication checks.
- Do not write uploads to source-controlled directories.
- Do not ignore file size or MIME-type validation.

Recommended Project Structure

frontend/
  angular-app/
    src/
      app/
        components/
        services/
        views/
      assets/
      index.html
    angular.json
    package.json
backend/
  django-project/
    settings.py
    urls.py
    wsgi.py
  project/
    asgi.py
  app/
    models.py
    serializers.py
    views.py
    urls.py
    tests/
  manage.py
shared/
  libs/
    interfaces.ts

Core Engineering Principles

• Explicit contracts between frontend and backend via clear REST API schemas.
• Type-safe data transfer (TypeScript interfaces; Python serializers).
• Idempotent API endpoints and predictable side effects for uploads.
• Security-first design: authentication, authorization, input validation, and rate limiting.
• Automated tests and reproducible builds; avoid environment drift.

Code Construction Rules

• Frontend: Angular Material components for file chooser, drag-and-drop, and progress indicators.
• Backend: DRF viewsets/APIView for uploads with proper permissions.
• Use serializers to validate upload input and to store metadata in DB.
• Files stored in Django MEDIA_ROOT with a storage backend abstraction.
• Define URL schemas and namespace routing that aligns with REST conventions.
• Do not bypass CSRF or rely on insecure CORS settings.

Security and Production Rules

• Use HTTPS in production; enforce HSTS where applicable.
• Secure cookies for tokens; HttpOnly and Secure flags.
• Validate and sanitize all inputs; restrict allowed MIME types and sizes.
• Regularly rotate secrets and use environment-based overrides for deployments.

Testing Checklist

• Unit tests for serializers and validators in Django app.
• Integration tests for upload API endpoints with representative files.
• Frontend tests for file input, validation, and API integration.
• End-to-end tests to verify file storage and metadata persistence.

Common Mistakes to Avoid

• Omitting file type and size validation on the server side.
• Storing uploads outside MEDIA_ROOT or in version-controlled directories.
• Weak authentication or poor token management for file uploads.
• Assuming the frontend will enforce all constraints without backend checks.

FAQ

What is a CLAUDE.md template?

A blueprint for Claude Code-driven templates tailored to a stack.

Which stack is covered here?

An Angular Material frontend with a Django REST Framework backend for file uploads.

What should I paste into CLAUDE.md?

The copyable CLAUDE.md template block with project role, rules, and deployment guidance.

How do I secure uploads?

Use JWT, HttpOnly cookies, server-side validation, and restricted storage under MEDIA_ROOT.

Where are the files stored?

Files should be stored in a storage backend under MEDIA_ROOT; do not commit binaries to code.