PyNuxtBase

An opinionated, modern, full-stack web application foundation built with Nuxt 4, FastAPI, and Django ORM, following strict architectural principles and best practices.

Status

This is ALPHA SOFTWARE and is under heavy development and design. It is not ready for production use.

Overview

PyNuxtBase provides a production-ready bootstrapping foundation for modern web applications with:

• Frontend: Nuxt 4 (Vue 3, TypeScript, Tailwind CSS 4)
• Backend: Python 3.12 with Django ORM + FastAPI (hybrid architecture)
• Database: PostgreSQL 17 with UUID primary keys
• Infrastructure: Docker Compose for local development
• Authentication: JWT-based with refresh tokens
• Type Safety: Strictest TypeScript + Python mypy configuration

Prerequisites

Before you begin, ensure you have the following installed:

Required

• Docker (v20.10+) and Docker Compose (v2.0+)
  • Install Docker Desktop
• Git (v2.30+)
  • Install Git
• uv (Python package manager)
  • Install: curl -LsSf https://astral.sh/uv/install.sh | sh

Optional (for local development)

• Node.js (v20 LTS+) - for frontend development
• Python 3.12 - for backend development

Quick Start

1. Clone the repository

git clone <repository-url>
cd PyNuxtBase

2. Set up environment variables

cp .env.example .env
# Edit .env with your configuration (optional for development)

3. Start infrastructure services

cd docker
docker compose up -d

This starts:

• PostgreSQL 17 (port 5432)
• Caddy reverse proxy (ports 80, 443)
• Mailpit email testing (SMTP: 1025, Web UI: 8025)

4. Verify setup

# Check services are running
docker compose ps

# Access Mailpit web interface
open http://localhost:8025

5. Set up Python environment (backend)

cd src/backend
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt  # When requirements.txt is created

6. Set up frontend (when ready)

cd src/frontend
npm install  # or pnpm install
npm run dev

Project Structure

PyNuxtBase/
├── src/
│   ├── frontend/          # Nuxt 4 application
│   │   ├── assets/        # Tailwind CSS config
│   │   ├── components/    # Vue components
│   │   ├── composables/   # Composition API composables
│   │   ├── layouts/       # Nuxt layouts
│   │   ├── pages/         # Nuxt pages (file-based routing)
│   │   ├── plugins/       # Nuxt plugins
│   │   ├── store/         # Pinia stores
│   │   └── tests/         # Frontend tests
│   │
│   └── backend/           # Python backend
│       ├── app/
│       │   ├── django_app/  # Django project + apps
│       │   └── api/         # FastAPI routers
│       ├── main.py        # Entry point (Django /cp + FastAPI /api)
│       └── tests/         # Backend tests
│
├── docker/               # Infrastructure configuration
│   ├── docker-compose.yml
│   ├── caddy/           # Caddy reverse proxy config
│   └── postgres/        # PostgreSQL initialization
│
├── scripts/             # Utility scripts
├── docs/                # Additional documentation
└── .env.example         # Environment variables template

See the PyNuxtBase Constitution for detailed architecture decisions and coding standards.

Development Workflow

Docker Services

# Start all services
cd docker && docker compose up -d

# Stop all services
docker compose down

# View logs
docker compose logs -f [service-name]

# Restart a service
docker compose restart [service-name]

Backend Development (Python + uv)

# Create virtual environment
cd src/backend
uv venv

# Activate environment
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

# Install dependencies
uv pip install -r requirements.txt

# Run Django migrations (when Django is set up)
python manage.py migrate

# Run development server (when configured)
python main.py

Frontend Development (Nuxt)

cd src/frontend

# Install dependencies
npm install

# Run development server with hot-reload
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Type check
npm run typecheck

# Lint and fix
npm run lint
npm run lint:fix

Frontend Project Structure

src/frontend/
├── app/
│   ├── assets/           # Global styles (main.css with Tailwind)
│   ├── components/       # Vue components
│   │   └── ui/          # Design system UI components
│   ├── composables/      # Composition API functions (auto-imported)
│   ├── constants/        # App constants (API endpoints, etc.)
│   ├── layouts/          # Nuxt layouts
│   ├── middleware/       # Route middleware
│   ├── pages/            # Nuxt pages (file-based routing)
│   ├── store/            # Pinia stores
│   └── types/            # TypeScript type definitions
├── public/               # Static assets (favicon, etc.)
├── nuxt.config.ts        # Nuxt configuration
├── package.json
├── tsconfig.json
└── eslint.config.mjs

Design System

The frontend includes a comprehensive design system with:

• UI Components (app/components/ui/):

  • Button.vue - Primary, secondary, outline, ghost, danger variants
  • Input.vue - Form inputs with validation states
  • Select.vue - Searchable dropdown component
  • Modal.vue - Dialog with teleport
  • Card.vue - Content containers with hoverable variant
  • Toast.vue - Notification toasts (success, error, warning, info)
  • Loading.vue - Spinners and skeleton loaders
  • ErrorState.vue - Error display with retry button
  • BackToTop.vue - Scroll-to-top button
  • OfflineIndicator.vue - Network status indicator

• Design Tokens (app/assets/main.css):

  • CSS custom properties for colors, spacing, shadows, transitions
  • Consistent color palette (primary, neutral, success, warning, error)
  • Design token interfaces in app/types/design-system.ts

• Composables (app/composables/):

  • useNavigation - Route utilities, online/offline detection
  • useNotifications - Toast notification queue management
  • useFormPreservation - Form state preservation across navigation

• State Management (app/store/):

  • auth.ts - Authentication state with JWT token management

API Integration

All API calls use composables from app/composables/api/:

• base.ts - Core API client with auth interceptor
• useAuth.ts - Authentication operations (login, logout, token refresh)
• useUsers.ts - User CRUD operations
• useFetch.ts - Wrapper around Nuxt useFetch with auth

API endpoints are configured in app/constants/index.ts

Database Access

# Connect to PostgreSQL
docker compose -f docker/docker-compose.yml exec postgres psql -U pynuxtbase -d pynuxtbase

# Run SQL file
docker compose -f docker/docker-compose.yml exec -T postgres psql -U pynuxtbase -d pynuxtbase < script.sql

Contributing

This project follows the PyNuxtBase Constitution which defines:

• 7 Core Principles (latest versions, type safety, architecture, auth, UUIDs, Tailwind, no TDD)
• Repository structure conventions
• Development workflow standards
• Code quality requirements
• Git and PR guidelines

Code Quality Standards

Python:

• Black (formatting)
• flake8 (linting)
• isort (import sorting)
• mypy (static typing)

TypeScript/Vue:

• ESLint (linting)
• Strictest TypeScript configuration
• nuxt typecheck (Vue type checking)
• Prettier (formatting)

Conventional Commits

Use Conventional Commits format:

feat: add user authentication
fix: resolve token refresh bug
docs: update setup instructions
chore: upgrade dependencies
refactor: simplify API error handling
test: add integration tests for auth flow

Documentation

• Setup Guide - Detailed environment setup
• Architecture - Technical architecture (coming soon)
• Constitution - Project principles and standards

Technology Stack

Frontend:

• Nuxt 4.x (SSR + CSR)
• Vue 3 (Composition API)
• TypeScript (strictest mode)
• Tailwind CSS 4.x (CSS-only config)
• Pinia (state management)
• Nuxt UI (component library)
• Zod (runtime validation)

Backend:

• Python 3.12
• Django 6.0 (ORM, admin, migrations)
• FastAPI 0.115 (async API endpoints)
• Uvicorn (ASGI server)
• Pydantic 2.x (schemas)
• psycopg 3.1 (PostgreSQL driver)

Infrastructure:

• PostgreSQL 17.x
• Docker & Docker Compose
• Caddy (reverse proxy)
• Mailpit (dev email testing)

License

[Specify your license here]

Support

For issues and feature requests, please use the GitHub Issues page.