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.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and How skill files guide dependency choices for production AI workflows.

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.