mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-24 21:31:09 -05:00
Add secret management guide, client-side performance monitoring, and search accessibility enhancements
- 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.
This commit is contained in:
108
docs/architecture/adr-001-django-htmx-architecture.md
Normal file
108
docs/architecture/adr-001-django-htmx-architecture.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user