mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-24 17:31:09 -05:00
edcd8f2076
- Introduced a comprehensive Secret Management Guide detailing best practices, secret classification, development setup, production management, rotation procedures, and emergency protocols. - Implemented a client-side performance monitoring script to track various metrics including page load performance, paint metrics, layout shifts, and memory usage. - Enhanced search accessibility with keyboard navigation support for search results, ensuring compliance with WCAG standards and improving user experience.
3.7 KiB
3.7 KiB
ADR-001: Django + HTMX Architecture
Status
Accepted
Context
ThrillWiki needed to choose a frontend architecture for building an interactive web application. The options considered were:
- Single Page Application (SPA) with React/Vue.js and a separate API backend
- Django monolith with HTMX for server-driven interactivity
- Traditional Multi-Page Application (MPA) with full page reloads
The team needed an architecture that would:
- Minimize development complexity
- Provide good SEO out of the box
- Enable fast initial page loads
- Support dynamic interactions without full page reloads
- Be maintainable by a small team
Decision
We chose to build ThrillWiki as a Django monolith with HTMX for dynamic interactivity, supplemented by minimal Alpine.js for client-side UI state.
Key Components
- Django Templates: Server-side rendering for all pages
- HTMX: Dynamic partial updates without full page reloads
- Alpine.js: Minimal client-side state (form validation, UI toggles)
- Tailwind CSS: Utility-first styling
- REST API: Available for programmatic access (mobile apps, integrations)
Architecture Pattern
Browser Request
│
▼
┌─────────────┐
│ Django │
│ Views │
└─────────────┘
│
▼
┌─────────────────────────────────┐
│ HTMX Request? │
│ ├── Yes: Render partial │
│ └── No: Render full page │
└─────────────────────────────────┘
│
▼
┌─────────────┐
│ Response │
│ (HTML) │
└─────────────┘
Consequences
Benefits
- Reduced Complexity: Single codebase, no separate frontend build process
- SEO-Friendly: Server-rendered HTML by default
- Fast Initial Load: No JavaScript bundle to download before content appears
- Progressive Enhancement: Works without JavaScript, enhanced with HTMX
- Easier Debugging: Server logs show all application state
- Simpler Deployment: Single Django container
- Django Ecosystem: Full access to Django's batteries-included features
Trade-offs
- Learning Curve: Developers need to learn HTMX patterns
- Limited Offline Support: No client-side data caching
- Network Dependency: Every interaction requires a server round-trip
- Complex Client State: Harder to manage complex client-side state (mitigated by Alpine.js)
HTMX Patterns Adopted
- Partial Templates: Views return partial HTML for HTMX requests
- HX-Trigger Events: Cross-component communication via custom events
- Loading Indicators: Skeleton loaders shown during requests
- Field Validation: Real-time form validation via HTMX
Alternatives Considered
React/Vue.js SPA
Rejected because:
- Increased development complexity with separate codebases
- SEO requires server-side rendering setup (Next.js, Nuxt.js)
- Larger bundle sizes for initial load
- More complex deployment with API + frontend containers
- Overkill for this application's interactivity needs
Traditional MPA
Rejected because:
- Poor user experience with full page reloads
- Higher server load for every interaction
- Slower perceived performance