# 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)