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:

   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

   ):

   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

   ):

   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:

   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)