FastHTML Plus

FastHTML Plus is a layered web application architecture experiment built around literal HTML, small amounts of JavaScript, HTMX fragment swaps, a FastHTML backend, and auth offload via Traefik plus Authelia.

The main detailed write-up is the accompanying blog post: https://weisser-zwerg.dev/posts/software-engineering-fasthtml-plus/

This repository is meant to stand on its own as a runnable prototype. You can work from the inside out:

1. Open static HTML directly from file://.
2. Add a FastHTML backend that serves the same pages plus HTMX fragments and JSON APIs.
3. Put Traefik and Authelia in front for local auth and authorization checks.
4. Deploy the full stack into an Incus-based integration environment and then onto a VPS.

Core ideas

• Keep markup literal. The same HTML files can be opened from disk and later served by the backend.
• Keep JavaScript small. TypeScript handles local behavior and progressive enhancement instead of owning the whole UI.
• Treat HTML fragments as first-class responses. HTMX endpoints return HTML, not just JSON.
• Keep JSON APIs explicit. Canonical API routes still exist under /api/public/* and /api/private/*.
• Move login outward. Traefik plus Authelia handle authentication so the backend can focus on authorization and trust boundaries.
• Let each layer be useful on its own. The inner layers stay productive even before the outer layers are running.

Repository layout

.
├── 010-dev/
│   ├── 0010-systems/          # Local Traefik + Authelia stack
│   └── 0100-app/
│       ├── 010-web/           # Static HTML + TypeScript frontend
│       └── 020-fasthtml/      # FastHTML backend
├── 020-ops/                   # Rendering and deployment tooling
├── 050-integration-tests/     # HTTPS integration tests against Incus/VPS deployments
└── AUTHENTICATION-AND-AUTHORIZATION.md

Prerequisites

• nvm with Node v22.12.0 available for the frontend
• uv for Python environments
• Docker + Docker Compose
• mkcert plus libnss3-tools for trusted local TLS
• tmux for the optional systems workflow
• incus for the full integration-test layer

Quick start

1) Frontend-only via file://

cd 010-dev/0100-app/010-web
nvm install
nvm use
npm ci
npm run build

Then open:

• file://.../index.html
• file://.../public.html
• file://.../private.html

This validates the innermost layer: plain HTML, CSS, and TypeScript, with HTMX attributes present but inert until a backend exists.

2) Backend in functional mode

cd 010-dev/0100-app/020-fasthtml
uv sync
uv run pytest
make run-local

Open:

• http://127.0.0.1:5001/public
• http://127.0.0.1:5001/private

In this mode RUN_LOCAL=1 keeps auth friction low so you can work on pages, fragments, and APIs quickly.

3) Systems mode with Traefik + Authelia

In one shell:

cd 010-dev/0010-systems
make certs
make render-config
make check-sync
make up

In a second shell:

cd 010-dev/0100-app/020-fasthtml
make run-systems

Then visit:

• https://app.localhost:8080/public
• https://app.localhost:8080/private
• https://auth.app.localhost:8080

This mode exercises the proxy trust model, ForwardAuth flow, and private-route authorization behavior.

4) Full integration and production-oriented flows

• Incus integration runbook: 050-integration-tests/README.md
• Deployment runbook: 020-ops/DEPLOY.md
• Auth model and trust boundaries: AUTHENTICATION-AND-AUTHORIZATION.md

Layer summary

Layer 1: 010-web

• Static HTML pages that work directly from file://
• Vite build emits both dist/main.js and dist/main.file.js
• HTMX is vendored into dist/vendor/htmx.min.js for offline use

Layer 2: 020-fasthtml

• Serves the same frontend files from ../010-web
• Returns literal HTML fragments for HTMX interactions
• Exposes JSON APIs for public and private routes
• Supports two backend modes:
  • functional mode for fast iteration
  • access/authz mode for trusted-proxy validation

Layer 3: 0010-systems

• Local HTTPS entrypoints via Traefik
• Login and policy evaluation via Authelia
• Forwarded identity headers plus proxy-secret proof into the backend

Layer 4: 050-integration-tests and 020-ops

• Incus-backed end-to-end environment
• mkcert for local integration TLS, Let's Encrypt for production
• Redis-backed sessions and scaled fasthtml containers in outer layers

Validation workflow

When changing a layer, run that layer's checks:

• Frontend: npm run build
• Backend: uv sync then uv run pytest
• Systems: make render-config, make check-sync, make up
• Ops: uv sync, make check-sync
• Integration: make test and optionally make test-scale

Notes

• 010-dev/0010-systems/ contains generated local config outputs. The canonical templates live in 020-ops/templates/.
• 010-dev/0100-app/010-web/dist/vendor/htmx.min.js is generated and intentionally not committed.
• The backend defaults to the safer access/authz mode unless you use make run-local.