Django + Vue.js + Flutter Fullstack Development

Overview

This skill guides development with the fullstack-starter-djvurn template: a Docker-based monorepo with Django (DRF) backend, Vue.js (TypeScript) frontend, and Flutter mobile app.

Template location: \\wsl.localhost\Ubuntu\home\hmesfin\dev\templates\fullstack-starter-djvurn

Core Architecture

Stack Components

• Backend: Django 5.x + DRF + Celery + PostgreSQL + Redis
• Frontend: Vue 3 + TypeScript + Vite + Shadcn-vue + Tailwind v4
• Mobile: Flutter + Expo + TypeScript
• Infrastructure: Docker Compose (local/staging/production)
• Package Management: Backend uses uv, Frontend uses npm

Key Architectural Decisions

1. Monorepo structure: backend/, frontend/, mobile/ at root level
2. API-only backend: Django serves only API endpoints + admin (no template views)
3. Custom User model: Email-based auth (apps.users.User, no username)
4. Auto-generated API clients: OpenAPI schema → TypeScript client
5. UUID primary keys: Recommended for API-exposed models
6. All services in Docker: Including Vite dev server

Mandatory Development Standards

1. File Size Limit: 500 Lines Maximum

• Enforcement: No file should exceed 500 lines
• When approaching limit: Split into multiple files or modules
• Backend: Split large views into multiple ViewSets, models into separate files
• Frontend: Split large components, create composables, extract utilities

2. Strict TDD (Test-Driven Development)

• RED-GREEN-REFACTOR cycle mandatory
  1. RED: Write failing test first
  2. GREEN: Write minimal code to pass
  3. REFACTOR: Improve code while keeping tests green
• No production code without tests: Every function, view, component gets tests
• Test files co-located:
  • Backend: apps/<app>/tests.py or apps/<app>/tests/
  • Frontend: src/<feature>/__tests__/<component>.test.ts
  • Mobile: src/<feature>/__tests__/<component>.test.tsx

3. Strict Typing

• Backend (Python):
  • Type hints for all functions/methods
  • Run docker compose run --rm django mypy apps before commits
  • Configure in backend/pyproject.toml
• Frontend (TypeScript):
  • Strict mode enabled in tsconfig.json
  • No any types without explicit reason
  • Run docker compose run --rm frontend npm run type-check
• Mobile (TypeScript):
  • Strict mode enabled
  • Props and state explicitly typed

4. Efficiency Tools Usage

• API Client Generation: Always use npm run generate:api after backend changes
• Code Quality: Pre-commit hooks for linting, formatting, type checking
• Docker: All commands run via docker compose run --rm <service>

Project Structure Reference

See references/PROJECT_STRUCTURE.md for complete directory layout and file organization patterns.

Development Workflows

Starting a New Project

Process:

1. Copy template: cp -r templates/fullstack-starter-djvurn new-project-name
2. Update configuration (see references/NEW_PROJECT_SETUP.md)
3. Initialize git: cd new-project-name && git init
4. Start services: docker compose up -d
5. Create superuser: docker compose run --rm django python manage.py createsuperuser

Creating a New Django App

TDD Workflow:

1. Plan the app (models, endpoints, functionality)
2. Create app structure:
   bashCopy

   docker compose run --rm django python manage.py startapp <app_name> backend/apps/<app_name>
   

3. Write model tests first (backend/apps/<app_name>/tests.py):
   pythonCopy

   import pytest
   from apps.<app_name>.models import ModelName
   
   @pytest.mark.django_db
   class TestModelName:
       def test_create_instance(self):
           # Test should FAIL initially (RED)
           instance = ModelName.objects.create(name="Test")
           assert instance.name == "Test"
   

4. Run tests (verify they FAIL): docker compose run --rm django pytest apps/<app_name>/
5. Create models (backend/apps/<app_name>/models.py):
   pythonCopy

   import uuid
   from django.db import models
   from typing import Optional  # Type hints
   
   class ModelName(models.Model):
       id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
       name: str = models.CharField(max_length=255)  # Type annotation
       created = models.DateTimeField(auto_now_add=True)
       modified = models.DateTimeField(auto_now=True)
   
       def __str__(self) -> str:
           return self.name
   

6. Add to INSTALLED_APPS (backend/config/settings/base.py)
7. Create and run migrations:
   bashCopy

   docker compose run --rm django python manage.py makemigrations
   docker compose run --rm django python manage.py migrate
   

8. Run tests (should PASS now - GREEN)
9. Add serializers, views, register with router (see references/DRF_PATTERNS.md)
10. Type check: docker compose run --rm django mypy apps/<app_name>/

Adding API Endpoints

Complete workflow in references/API_WORKFLOW.md

Quick reference:

1. Write serializer tests (TDD)
2. Create serializer with type hints
3. Write ViewSet tests
4. Create ViewSet
5. Register in backend/config/api_router.py
6. Regenerate frontend client: docker compose run --rm frontend npm run generate:api
7. Type check both: docker compose run --rm django mypy apps && docker compose run --rm frontend npm run type-check

Creating Vue.js Components

TDD workflow:

1. Write component tests first
2. Run tests (should FAIL): docker compose run --rm frontend npm run test
3. Create component with strict TypeScript
4. Run tests (should PASS)
5. Type check: docker compose run --rm frontend npm run type-check
6. File size check: Keep under 500 lines

See references/VUE_COMPONENT_PATTERNS.md for complete examples

Database Migrations

Process:

1. Modify models in backend/apps/<app>/models.py
2. Run tests to ensure model logic works
3. Generate migration: docker compose run --rm django python manage.py makemigrations
4. Review migration file
5. Apply: docker compose run --rm django python manage.py migrate
6. Regenerate API client: docker compose run --rm frontend npm run generate:api

Flutter Features

See references/REACT_NATIVE_PATTERNS.md for mobile development workflows

Code Quality Enforcement

Running Tests

Backend:

# All tests
docker compose run --rm django pytest

# Specific app
docker compose run --rm django pytest apps/<app_name>/

# With coverage
docker compose run --rm django pytest --cov=apps --cov-report=html

Frontend:

# Unit tests
docker compose run --rm frontend npm run test

# E2E tests (Playwright)
docker compose run --rm frontend npm run test:e2e

# Coverage
docker compose run --rm frontend npm run test:coverage

Mobile:

docker compose run --rm mobile npm run test

Type Checking

Backend (mypy):

# Type check entire backend
docker compose run --rm django mypy apps

# Specific app
docker compose run --rm django mypy apps/<app_name>

Frontend:

docker compose run --rm frontend npm run type-check

Mobile:

docker compose run --rm mobile npm run type-check

Linting & Formatting

Backend (Ruff):

# Check
docker compose run --rm django ruff check apps

# Fix
docker compose run --rm django ruff check apps --fix

# Format
docker compose run --rm django ruff format apps

Frontend (ESLint + Prettier):

# Lint
docker compose run --rm frontend npm run lint

# Format
docker compose run --rm frontend npm run format

Common Patterns

API Client Usage Pattern

After regenerating API client (npm run generate:api):

import { projectsList, projectsCreate } from '@/api/sdk.gen'
import { apiClient } from '@/lib/api-client'

// Fetch data
const response = await projectsList({ client: apiClient })

// Create
const newProject = await projectsCreate({
  client: apiClient,
  body: { name: 'New Project', status: 'active' }
})

// Error handling (CRITICAL for generated SDK)
if (response && 'error' in response && response.error) {
  throw response  // SDK returns errors instead of throwing
}

Composable Pattern

// src/composables/useProjects.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/vue-query'
import { projectsList, projectsCreate } from '@/api/sdk.gen'
import { apiClient } from '@/lib/api-client'

export function useProjects() {
  const queryClient = useQueryClient()

  const { data, isLoading } = useQuery({
    queryKey: ['projects'],
    queryFn: () => projectsList({ client: apiClient })
  })

  const createMutation = useMutation({
    mutationFn: (data) => projectsCreate({ client: apiClient, body: data }),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['projects'] })
  })

  return { projects: data, isLoading, createProject: createMutation.mutate }
}

Type Checking

Backend: docker compose run --rm django mypy apps Frontend: docker compose run --rm frontend npm run type-check Mobile: docker compose run --rm mobile npm run type-check

Linting & Formatting

Backend (Ruff):

• Check: docker compose run --rm django ruff check apps
• Fix: docker compose run --rm django ruff check apps --fix

Frontend (ESLint):

• Lint: docker compose run --rm frontend npm run lint
• Format: docker compose run --rm frontend npm run format

Quick Reference

Essential Commands

Start services: docker compose up -d View logs: docker compose logs -f <service> Stop services: docker compose down Run tests: docker compose run --rm <service> <test-command> Shell access: docker compose exec <service> bash

Key Files

• Django settings: backend/config/settings/
• API router: backend/config/api_router.py
• Frontend API client: frontend/src/api/ (auto-generated)
• Environment vars: .envs/.local/

Documentation

For detailed patterns, workflows, and examples, see:

• references/PROJECT_STRUCTURE.md - Directory organization
• references/API_WORKFLOW.md - Complete API development flow
• references/DRF_PATTERNS.md - Django REST Framework patterns
• references/VUE_COMPONENT_PATTERNS.md - Vue.js best practices
• references/REACT_NATIVE_PATTERNS.md - Mobile development
• references/TESTING_PATTERNS.md - TDD workflows and examples
• references/TYPE_SAFETY.md - Type checking guidelines
• references/NEW_PROJECT_SETUP.md - Project initialization

TDD Checklist

Before committing code, verify:

• All tests written BEFORE implementation
• All tests passing
• Type checking passes (mypy + TypeScript)
• No files over 500 lines
• Linting passes
• API client regenerated (if backend changed)