# ADR 0004: Astro + Svelte for Frontend

- **Status**: Accepted
- **Date**: 2025-02-01
- **Track**: Software

## Context

KoproGo targets low carbon footprint (< 0.5g CO2/request) which requires minimal JavaScript in the browser. We need a frontend that:
1. Renders fast with minimal JS
2. Provides interactivity where needed (forms, dashboards)
3. Supports multi-language (FR, NL, EN)
4. SEO-friendly for marketing pages
5. Easy deployment (static hosting)

## Decision

We chose **Astro** as the meta-framework with **Svelte** for interactive components.

**Astro** provides:
- **Zero JS by default**: Only ships JavaScript for interactive components
- **Islands Architecture**: Hydrate only what's needed
- **Framework agnostic**: Can mix Svelte, React, Vue in same project
- **Static Site Generation**: Build to static HTML/CSS/JS

**Svelte** for interactivity:
- **No virtual DOM**: Compiles to vanilla JS, smaller bundles
- **Reactive by default**: Simple syntax without hooks/lifecycle boilerplate
- **Excellent DX**: Less code than React/Vue for same functionality

## Consequences

**Positive**:
- ✅ **Minimal JavaScript**: Astro pages ship ~0-5KB JS vs 100KB+ React SPAs
- ✅ **Fast load times**: Static HTML loads instantly, JS hydrates progressively
- ✅ **Low carbon**: Less data transfer = less energy = lower CO2
- ✅ **SEO-friendly**: Server-rendered HTML crawlable by search engines
- ✅ **Developer experience**: Svelte's syntax is clean and intuitive

**Negative**:
- ⚠️ **Smaller ecosystem**: Fewer Svelte component libraries than React
- ⚠️ **Server rendering**: Complex real-time features need separate architecture

**Measured results**:
- Bundle size: ~15KB JS (gzipped) for interactive pages
- Initial load: < 1s on 3G
- Lighthouse scores: 95+ across all metrics

## Alternatives Considered

1. **React + Next.js**:
   - ✅ Largest ecosystem, most developers
   - ❌ Heavy bundles (100KB+ baseline)
   - ❌ Complex hydration (CLS issues)
   - **Verdict**: Rejected due to JS size

2. **Vue + Nuxt**:
   - ✅ Good DX, lighter than React
   - ❌ Still ships more JS than needed
   - **Verdict**: Close second, Astro+Svelte preferred for performance

3. **HTMX + Go templates**:
   - ✅ Minimal JS, server-driven
   - ❌ Limited interactivity without custom JS
   - **Verdict**: Considered for future admin panel, too limiting for MVP

## Next Steps

- ✅ Implement core pages (login, dashboard, buildings) (**Done**)
- ⏳ Add Storybook for component documentation
- ⏳ Optimize images (WebP, lazy loading)
- ⏳ Evaluate Astro DB for user preferences (Phase 2)

## References

- Astro: https://astro.build
- Svelte: https://svelte.dev
- Islands Architecture: https://jasonformat.com/islands-architecture/