Skip to content

architecture.md

Latest commit

 

History

History
225 lines (176 loc) · 7.78 KB

architecture.md

File metadata and controls

225 lines (176 loc) · 7.78 KB

PyNuxtBase Architecture

Status: In Development

This document will be populated as features are implemented. See tech-stack.md and PyNuxtBase Constitution for current specifications.

Overview

PyNuxtBase follows a modern, full-stack architecture with clear separation of concerns between frontend, backend, and infrastructure layers.

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Client Layer                         │
│                    (Browser / Mobile App)                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Caddy Reverse Proxy                     │
│              (Routing: /, /api, /cp + HTTPS)                 │
└─────────────────────────────────────────────────────────────┘
                              │
                ┌─────────────┼─────────────┐
                │             │             │
                ▼             ▼             ▼
        ┌───────────┐  ┌──────────┐  ┌──────────┐
        │  Nuxt 4   │  │ FastAPI  │  │  Django  │
        │ (SSR+CSR) │  │  (Async  │  │  Admin   │
        │  Port     │  │   API)   │  │  (CRUD)  │
        │  3000     │  │  /api/*  │  │  /cp/*   │
        └───────────┘  └──────────┘  └──────────┘
                              │             │
                              ▼             │
                    ┌──────────────────┐   │
                    │  Django ORM      │◄──┘
                    │  (Shared Models) │
                    └──────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │  PostgreSQL 17   │
                    │  (UUID PKs)      │
                    └──────────────────┘

Core Architectural Principles

Based on the PyNuxtBase Constitution:

  1. Latest Stable Versions: Always use current versions from official sources
  2. Strict Type Safety: TypeScript (strictest) + Python type hints (mypy)
  3. Modern Full-Stack Architecture: Nuxt 4 + Vue 3 + FastAPI/Django hybrid
  4. JWT Authentication: Token-based auth with refresh tokens
  5. UUID Primary Keys: All database models use UUIDs
  6. Tailwind CSS-Only: No tailwind.config.ts (CSS configuration)
  7. No TDD Required: Tests optional, not mandatory

Technology Stack

Frontend Layer

  • Framework: Nuxt 4.x
  • UI Library: Vue 3 (Composition API)
  • Language: TypeScript (strictest configuration)
  • Styling: Tailwind CSS 4.x (CSS-only configuration)
  • State Management: Pinia
  • Validation: Zod (runtime schema validation)
  • HTTP Client: useAsyncData / useFetch (Nuxt composables)

Backend Layer

API Layer (FastAPI)

  • Purpose: High-performance async HTTP/WebSocket endpoints
  • Mount Point: /api
  • Features:
    • JWT validation
    • Current user resolution
    • OpenAPI documentation
    • Async database queries

Admin Layer (Django)

  • Purpose: ORM, migrations, admin interface
  • Mount Point: /cp (control panel)
  • Features:
    • Session-based authentication
    • CRUD interface for data management
    • Migration management
    • User administration

Database Layer

  • ORM: Django ORM
  • Database: PostgreSQL 17.x
  • Primary Keys: UUID (all models)
  • Migrations: Django migrations
  • Connection: Shared between Django and FastAPI

Infrastructure Layer

  • Reverse Proxy: Caddy (automatic HTTPS, routing)
  • Database: PostgreSQL 17 (Docker container)
  • Email (Dev): Mailpit (SMTP testing)
  • Container Orchestration: Docker Compose
  • Package Management: uv (Python), npm/pnpm (Node.js)

Authentication Flow

(To be documented in Feature 3.1: JWT Authentication)

User Login → Validate Credentials → Generate Tokens
  ↓
{ access_token: JWT (15min), refresh_token: JWT (7days), user: {...} }
  ↓
Frontend stores: access (memory), refresh (httpOnly cookie)
  ↓
All API requests: Authorization: Bearer <access_token>
  ↓
FastAPI dependency validates JWT
  ↓
If expired: Use refresh token → Get new access token
  ↓
If refresh expired: Re-login required

Directory Structure

See Repository Structure in README.md for complete file organization.

Key conventions:

  • Application code: src/
  • Frontend: src/frontend/ (Nuxt root)
  • Backend: src/backend/
  • Infrastructure: docker/
  • Documentation: docs/
  • CI/CD: .github/workflows/

Data Model

(To be documented in Feature 1.2: Database Foundation)

Core Principles:

  • All models use UUID primary keys
  • Timestamps (created_at, updated_at) on all models
  • Django ORM for all database operations
  • PostgreSQL native UUID type

API Design

(To be documented in Feature 2.1: Django + FastAPI Integration)

Versioning: All endpoints under /api/v1/

Standards:

  • RESTful design
  • JSON request/response
  • OpenAPI 3.0 specification
  • JWT authentication required (except public endpoints)

Frontend Architecture

(To be documented in Feature 4.1: Nuxt Project Setup)

Patterns:

  • Composition API with <script setup lang="ts">
  • Composables for shared logic
  • Pinia stores for global state
  • File-based routing (Nuxt pages)
  • SSR for initial render, CSR for interactions

Deployment Architecture

(To be documented in Phase 9: Production Readiness)

  • Platform-agnostic design
  • Dockerfiles for frontend and backend
  • Environment-based configuration
  • Horizontal scaling support

Security Considerations

(To be expanded in Feature 3.2: Password Management and beyond)

  • JWT tokens (access + refresh)
  • httpOnly cookies for refresh tokens
  • CORS configuration (dev: all origins, prod: whitelist)
  • CSRF protection for Django admin
  • Environment variables for secrets
  • .gitignore for sensitive files

Performance Considerations

(To be documented as features are implemented)

  • Async API endpoints (FastAPI)
  • Database query optimization (select_related, prefetch_related)
  • Frontend code splitting (Nuxt automatic)
  • Static asset optimization
  • Docker volume mounts for development

Future Enhancements

Deferred to later phases:

  • OAuth/Social authentication (Google, GitHub)
  • WebSocket features (deferred from initial scope)
  • CDN integration
  • Advanced caching strategies
  • Monitoring and observability
  • Multi-tenant support

Additional Resources

Document Status:

  • Created: 2026-01-02
  • Last Updated: 2026-01-02
  • Next Update: After Feature 1.2 (Database Foundation)