mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-24 17:51: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.
109 lines
3.7 KiB
Markdown
109 lines
3.7 KiB
Markdown
# 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:
|
|
|
|
1. **Single Page Application (SPA)** with React/Vue.js and a separate API backend
|
|
2. **Django monolith with HTMX** for server-driven interactivity
|
|
3. **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
|
|
|
|
1. **Django Templates**: Server-side rendering for all pages
|
|
2. **HTMX**: Dynamic partial updates without full page reloads
|
|
3. **Alpine.js**: Minimal client-side state (form validation, UI toggles)
|
|
4. **Tailwind CSS**: Utility-first styling
|
|
5. **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
|
|
|
|
1. **Reduced Complexity**: Single codebase, no separate frontend build process
|
|
2. **SEO-Friendly**: Server-rendered HTML by default
|
|
3. **Fast Initial Load**: No JavaScript bundle to download before content appears
|
|
4. **Progressive Enhancement**: Works without JavaScript, enhanced with HTMX
|
|
5. **Easier Debugging**: Server logs show all application state
|
|
6. **Simpler Deployment**: Single Django container
|
|
7. **Django Ecosystem**: Full access to Django's batteries-included features
|
|
|
|
### Trade-offs
|
|
|
|
1. **Learning Curve**: Developers need to learn HTMX patterns
|
|
2. **Limited Offline Support**: No client-side data caching
|
|
3. **Network Dependency**: Every interaction requires a server round-trip
|
|
4. **Complex Client State**: Harder to manage complex client-side state (mitigated by Alpine.js)
|
|
|
|
### HTMX Patterns Adopted
|
|
|
|
1. **Partial Templates**: Views return partial HTML for HTMX requests
|
|
2. **HX-Trigger Events**: Cross-component communication via custom events
|
|
3. **Loading Indicators**: Skeleton loaders shown during requests
|
|
4. **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
|
|
|
|
## References
|
|
|
|
- [HTMX Documentation](https://htmx.org/docs/)
|
|
- [Django + HTMX Guide](https://htmx.org/essays/hypermedia-applications/)
|
|
- [Alpine.js Documentation](https://alpinejs.dev/)
|
|
- [ThrillWiki HTMX Patterns](../htmx-patterns.md)
|