The idea is to have a scaffold I can clone whenever I start a new project, with auth, email, CRUD, and admin already wired up. The less Javascript I write, the happier I am. ![memebetter.com-20260617105306.jpg](/images/uploads/cb2f6fbe243b4020a682c5fc32ab541e.jpg) Here is what I built: a simple bookstore CRUD demo. ![Enregistrement de l’écran 2026-06-17 à 10.43.15.gif](/images/uploads/0abe28390b694606bae3f7c63fb58a04.gif) Here is my stack: ## Stack |Tool|Role| |---|---| | FastAPI | Backend | | SQLModel | ORM — one class is model, schema, and table | | pydantic-settings | Config from .env files | | Jinja2 | Server-side HTML rendering | | HTMX | Dynamic UI without JavaScript | | DaisyUI | Components and theming | | Alpine.js | Client-side state only | ## Project structure ``` MyApp/ ├── app/ │ ├── auth/ # Signup, login, verification, password reset │ │ ├── models.py # User model │ │ ├── schemas.py # Pydantic validation (UserCreate, UserPublic, TokenData) │ │ ├── service.py # Business logic │ │ └── router.py # Routes │ ├── crud/ # Example CRUD module │ │ ├── models.py # Book model (linked to User via foreign key) │ │ ├── schemas.py # BookPublic (controls what fields get exposed) │ │ ├── service.py # CRUD with ownership checks │ │ └── router.py # Routes with pagination & search │ ├── core/ # Shared infrastructure │ │ ├── settings.py # Pydantic-settings (.env loading) │ │ ├── db.py # Engine & session │ │ ├── security.py # Password hashing (Argon2), JWT │ │ └── dependencies.py # Auth guards (get_current_user, get_admin_user) │ ├── mail/ # Email delivery │ │ ├── service.py # SMTP logic │ │ └── templates.py # HTML email templates │ ├── admin/ # Admin panel (database introspection) │ │ ├── router.py │ │ ├── service.py │ │ └── schemas.py │ ├── templates/ # All Jinja2 templates (pages/, components/) │ ├── static/ # CSS, JS │ └── main.py # App entrypoint, middleware, exception handlers ├── pyproject.toml ├── .env.dev # Local dev config (gitignored) └── Dockerfile ``` Every module has four files: `service`, `models`, `router`, and `schemas`: - `router` calls `service` with `schemas` inputs - `service` calls the database via `models` `routers` are thin: they call a service, and get an output. `services` are heavy: computation happens here (business logic, pagination, etc). ## Setup ``` uv init uv add "fastapi[standard]" sqlmodel pydantic-settings "pwdlib[argon2]" pyjwt slowapi jinja2 ``` ## Settings Remember: never commit .env in our repo. Use `pydantic-settings` to read our env variables. - In `dev`, use a `.env.dev` file - In `prod`, use a secret manager, or pass your variables at build time `pydantic-settings` reads from `.env.dev` locally and from environment variables in production. Env vars always override the file. No code changes needed between environments. ```python # app/core/settings.py from pydantic_settings import BaseSettings, SettingsConfigDict from pydantic import model_validator class Settings(BaseSettings): model_config = SettingsConfigDict(env_file='.env.dev', env_file_encoding='utf-8', extra='ignore') # Core APP_NAME: str = "MyApp" ENVIRONMENT: str = "development" DATABASE_URL: str = "sqlite:///./dev.db" # Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))" SECRET_KEY: str ALGORITHM: str = "HS256" BASE_URL: str = "http://127.0.0.1:8000" @model_validator(mode="after") def validate_secret_key_in_production(self): if self.ENVIRONMENT == "production" and len(self.SECRET_KEY) < 32: raise ValueError("SECRET_KEY must be at least 32 characters in production") return self settings = Settings() ``` Key points: - Every field has a default except `SECRET_KEY` — if it's missing, the app crashes at startup. This is intentional. - The `model_validator` ensures we can't deploy to production with a weak key. - `extra='ignore'` means extra env vars (like `PORT` from Cloud Run) won't cause errors. ## Database ```python # app/core/db.py from app.core.settings import settings from sqlmodel import create_engine, SQLModel, Session connect_args = {} if settings.DATABASE_URL.startswith("sqlite"): connect_args["check_same_thread"] = False else: connect_args["sslmode"] = "require" engine = create_engine(settings.DATABASE_URL, connect_args=connect_args, pool_recycle=300) def create_db_and_tables(): SQLModel.metadata.create_all(engine) def get_session(): with Session(engine) as session: yield session ``` `get_session` is a generator dependency — FastAPI opens a session, injects it into our route, and closes it when the request finishes. `pool_recycle=300` prevents stale connections on managed databases (Neon, Cloud SQL). ## A simple Book model ```python from sqlmodel import SQLModel, Field from typing import Optional from uuid import uuid4 from datetime import datetime, timezone class Book(SQLModel, table=True): id: Optional[str] = Field(default_factory=lambda: str(uuid4()), primary_key=True) title: str = Field(max_length=50, index=True, nullable=False) author: str = Field(max_length=50, index=True, nullable=False) user_id: str = Field() creation_date: datetime = Field(default_factory=lambda: datetime.now(timezone.utc), nullable=False) update_date: datetime = Field(default_factory=lambda: datetime.now(timezone.utc), nullable=False) ``` `user_id` is a foreign key to `User`. Every book belongs to a user — this is how we scope data. More on that in the post about authentication. ## Public schema (controlling exposed fields) ```python # app/books/schemas.py from pydantic import BaseModel from datetime import datetime class BookPublic(BaseModel): id: str title: str author: str creation_date: datetime update_date: datetime ``` This controls what fields appear in the table UI. `user_id` is never exposed to the frontend: ## The Service ```py # app/books/service.py from sqlmodel import Session, select, SQLModel, or_ from app.crud.models import Book from datetime import datetime, timezone def get_book(book_id, session: Session): row = session.get(Book, book_id) return row def create_book(title: str, author: str, user_id: str, session: Session): book = Book(title=title, author=author, user_id=user_id) session.add(book) session.commit() session.refresh(book) return book def list_books(session: Session, user_id: str, query: str="", limit: int=10, offset: int=0): """ Args: session: Session, used to communicate with db query: str, used to filter results limit: int, number of records to be returned offset: int, allows to iterate over batches of data (pagination) Returns: books: list, data records """ statement = select(Book).where(Book.user_id == user_id) if query: statement = statement.where( or_( Book.title.contains(query), Book.author.contains(query), ) ) statement = statement.offset(offset).limit(limit+1).order_by(Book.update_date.desc()) try: results = session.exec(statement).all() return {"results": results[:limit], "has_next": len(results) == limit+1} except: return [] def update_book(book_id: str, title: str, author: str, user_id: str, session: Session): book = get_book(book_id=book_id, session=session) # Mandatory to avoid unauthorized access !!! if not book or book.user_id != user_id: return None book.title = title book.author = author book.update_date = datetime.now(timezone.utc) session.add(book) session.commit() session.refresh(book) return book def delete_book(book_id: str, user_id: str, session: Session): book = get_book(book_id=book_id, session=session) # Mandatory to avoid unauthorized access !!! if not book or book.user_id != user_id: return None session.delete(book) session.commit() return book ``` Notes: - Every mutating operation verifies the user owns the record. Forgetting this check is a famous security vulnerability called IDOR: Insecure Direct Object Reference. Happens more often that we think and can have dramatic effect (French government passport issuing website leaked data through that) : ```python def update_book(book_id: str, title: str, author: str, user_id: str, session: Session): book = get_book(book_id=book_id, session=session) if not book or book.user_id != user_id: return None book.title = title book.author = author book.update_date = datetime.now(timezone.utc) session.add(book) session.commit() session.refresh(book) return book ``` - Pagination : `limit + 1` on list queries: fetch one more than needed. If the DB returns `limit + 1` rows, there's a next page. Slice to `limit` before returning. ### The router (endpoints) Usually a 1:1 mapping between services and endpoints. Each endpoint should call a service once. This is also where auth is managed. ```py # app/books/router.py import os from typing import Optional from fastapi import APIRouter, Depends, Request, Response, Form, HTTPException from fastapi.responses import HTMLResponse from fastapi.templating import Jinja2Templates from sqlmodel import Session from app.crud import service as BookService from app.crud.schemas import BookPublic from app.core.db import get_session router = APIRouter(prefix="/app") templates_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "templates") templates = Jinja2Templates(templates_dir) USER_ID = "dev-user" # hardcoded for now — auth comes in part 2 @router.get("/", response_class=HTMLResponse) async def get_dashboard(request: Request, user: str=USER_ID): return templates.TemplateResponse( request=request, name="pages/dashboard.html", context={ "user": user, "tables": {} } ) @router.get("/books", response_class=HTMLResponse) def list_books( request: Request, user_id: str=USER_ID, q: Optional[str]="", limit:int=10, page: int=1, session: Session=Depends(get_session)): results = BookService.list_books( session=session, user_id=user_id, query=q, limit=limit, offset=(page-1)*limit ) data = { 'columns': BookPublic.model_fields.keys(), 'rows': results['results'] } return templates.TemplateResponse( request=request, name="components/table.html", context={ 'name': 'books', 'table': data, 'query': q, 'page': page, 'limit': limit, 'has_next': results['has_next'] } ) @router.get("/books/{book_id}", response_class=HTMLResponse) def get_book( request: Request, book_id: str, session: Session=Depends(get_session)): data = BookService.get_book(book_id, session) data = { 'columns': BookPublic.model_fields.keys(), 'rows': data } return templates.TemplateResponse( request=request, name="components/table.html", context={'name': 'books', 'table': data} ) @router.post("/books") def create_book( response: Response, title: str=Form(...), author: str=Form(...), session: Session=Depends(get_session)): BookService.create_book(title, author, USER_ID, session) response.headers["HX-Refresh"] = "true" return Response(status_code=200, headers={"HX-Refresh": "true"}) @router.post("/books/update") def update_book( response: Response, title: str=Form(...), author: str=Form(...), id: str=Form(...), session: Session=Depends(get_session)): book = BookService.update_book(id, title, author, USER_ID, session) if not book: raise HTTPException(403, "Forbidden") response.headers["HX-Refresh"] = "true" return Response(status_code=200, headers={"HX-Refresh": "true"}) @router.post("/books/{book_id}/delete") def delete_single_book( response: Response, book_id: str, session: Session=Depends(get_session)): book = BookService.delete_book(book_id, USER_ID, session) if not book: raise HTTPException(403, "Forbidden") response.headers["HX-Refresh"] = "true" return Response(status_code=200, headers={"HX-Refresh": "true"}) @router.post("/books/delete") def bulk_delete_books( response: Response, selected_ids: list[str] = Form(...), user_id: str=USER_ID, session: Session=Depends(get_session)): for book_id in selected_ids: BookService.delete_book(book_id, user_id, session) response.headers["HX-Refresh"] = "true" return Response(status_code=200, headers={"HX-Refresh": "true"}) ``` **-> We don't do a redirect in the CRUD routes. Sending a response with a `HX-Refresh` header is enough here. No need to use `RedirectResponse` from FastAPI.** ## Wiring this up ```py # app/main.py import os from contextlib import asynccontextmanager from fastapi import FastAPI, Request from fastapi.responses import RedirectResponse from fastapi.staticfiles import StaticFiles from app.crud.router import router as book_router from app.core.db import create_db_and_tables, get_session from app.core.settings import settings @asynccontextmanager async def lifespan(app: FastAPI): create_db_and_tables() yield app = FastAPI(lifespan=lifespan) # Static & Templates static_dir = os.path.join(os.path.dirname(__file__), "static") app.mount("/static", StaticFiles(directory=static_dir), name="static") # Routers app.include_router(book_router) @app.get("/health") async def health_check(): return {"status": "ok"} @app.get("/") async def index(request: Request): return RedirectResponse(url="/auth/login", status_code=302) ``` **-> The lifespan part is important since the DB will be initialized here.** ## Frontend: HTMX + DaisyUI + Alpine.js | Tool | Role | |------|------| | **HTMX** | Server requests (hx-get, hx-post, swap HTML fragments) | | **DaisyUI** | UI components (buttons, modals, tables, themes) | | **Alpine.js** | Client-side state only (toggles, dropdowns, checkbox counting) | **-> The server returns HTML, not JSON** ### What is HTMX? | Attribute | What it does | Example | |-----------|-------------|---------| | `hx-get` | Makes a GET request | `hx-get="/app/books"` | | `hx-post` | Makes a POST request | `hx-post="/app/books"` | | `hx-target` | Where to put the response HTML | `hx-target="#content"` | | `hx-swap` | How to insert it (default: `innerHTML`) | `hx-swap="outerHTML"` | | `hx-trigger` | What triggers the request (default: natural event) | `hx-trigger="keyup changed delay:200ms"` | | `hx-indicator` | Element to show during loading | `hx-indicator="#spinner"` | A traditional SPA flow: 1. User clicks a button 2. JavaScript sends `fetch("/api/books")` 3. Server returns JSON `[{"id": 1, "title": "..."}]` 4. JavaScript loops through JSON, builds `` elements, inserts into DOM With HTMX: 1. User clicks a button with `hx-get="/app/books"` 2. Server renders HTML with Jinja2, returns a `` fragment 3. HTMX drops it into the target element No JavaScript, no JSON parsing, no DOM manipulation. ### Base template The shell that every page extends: ```html {% block content %}{% endblock %} ``` Loading order matters: - **DaisyUI CSS first**, then **Tailwind JS** — otherwise Tailwind overrides DaisyUI's component styles. - **Alpine.js with `defer`** — ensures the DOM is ready before Alpine initializes. ### When to use what A simple rule: - **Need data from the server?** → HTMX (`hx-get`, `hx-post`) - **Need to toggle something on screen?** → Alpine.js (`x-show`, `x-data`) - **Need a styled component?** → DaisyUI class (`btn`, `modal`, `table`) **Never use Alpine.js for server requests, and never use HTMX for client-side toggles.** - Use `{% extends %}` jinja tags to inherit from base, and `{% block %}` to include content. - For reusable components, define them once and reuse using `{% include %}` - Define a `base.html` for everything related to CSS and scripts. Use a placeholder for the main content ```html {% extends "pages/base.html" %} {% block content %}

{% include "components/aside.html" %}

Dashboard

{% endblock %} ``` ## A data table ```html

{{ table.rows | length }} records

{% if table %}

{% for col in table.columns %} {% endfor %} {% for row in table.rows %} {% for col in table.columns %} {% endfor %} {% endfor %}

	{{ col }}
	{{ row[col] }}

Page {{ page }}

{% else %}

Nothing to show

{% endif %} ``` **Notes:** - Top section: search, add new, delete - Middle section: the table - Bottom section: pagination ## Modals We can add modals in two ways: - with Alpine (Client-side) - with HTMX (server-side) I choose server-side here. ### Add a new book ```html ``` Add a new route to the router. This will be triggered when we click the "New" button. ```py @router.get("/modal/new", response_class=HTMLResponse) async def new_book_form(request: Request): return templates.TemplateResponse( request=request, name="components/new_book_modal.html", context={"title": "New Book", "action": "/app/books", "method": "hx-post", "row": {}, "columns": ["title", "author"]} ) ``` ![Capture d’écran 2026-06-16 à 16.08.29.png](/images/uploads/a70c0b16d1c742a39299e5de763e9755.png) ![Capture d’écran 2026-06-16 à 16.14.09.png](/images/uploads/302d9753cd47410a9585a1deef989c11.png) ### Edit a book Reuse the previous one and just change the `hx-post` attribute to `/app/books/update`. And add the route to the router: ```py @router.get("/modal/{book_id}/edit", response_class=HTMLResponse) def edit_book_form(request: Request, book_id: str, session: Session = Depends(get_session)): book = BookService.get_book(book_id, session) return templates.TemplateResponse( request=request, name="components/edit_book_modal.html", context={"title": "Edit Book", "action": "/app/books/update", "method": "hx-post", "row": book, "columns": ["id", "title", "author"]} ) ``` Modal appears prefilled, just need to edit and save: ![Capture d’écran 2026-06-16 à 16.24.36.png](/images/uploads/0e22122f1e3347aea15fbeddf1dd5953.png) ### Delete a book Same. Need a delete modal, and the associated route. Just change the form method to `hx-delete` and change the endpoint: ```py @router.get("/modal/{book_id}/delete", response_class=HTMLResponse) async def delete_book_form(request: Request, book_id: str, session: Session = Depends(get_session)): return templates.TemplateResponse( request=request, name="components/delete_book_modal.html", context={"title": "Delete Book", "action": f"/app/books/{book_id}/delete", "method": "hx-delete", "columns": ["id", "title", "author"]} ) ``` ### Bulk delete This is where alpine comes handy. Each row in our table has a ` ` It's referring to the `x-data="{ selectedIds: [] }"` defined at the beginning of `table.html`. Each selected checkbox will be pushed to the array. It means that we can count the number of rows selected. Since all checkboxes share the same `name`, they will be grouped when sent to the server: ```html ``` Server-side: ```py @router.post("/books/delete") def bulk_delete_books( response: Response, selected_ids: list[str] = Form(...), # <-- comes from the form user_id: str=USER_ID, session: Session=Depends(get_session)): for book_id in selected_ids: BookService.delete_book(book_id, user_id, session) response.headers["HX-Refresh"] = "true" return Response(status_code=200, headers={"HX-Refresh": "true"}) ``` ## Search ![Capture d’écran 2026-06-16 à 16.57.03.png](/images/uploads/7f3608858b9b461a9ed99ef7d69ac2e1.png) Route and service are already ready to receive a search/filter: ```py @router.get("/books", response_class=HTMLResponse) def list_books( request: Request, user_id: str=USER_ID, q: Optional[str]="", # <-- HERE limit:int=10, page: int=1, session: Session=Depends(get_session)): ``` And the service: ```py def list_books(session: Session, user_id: str, query: str="", limit: int=10, offset: int=0): """ ... if query: statement = statement.where( or_( Book.title.contains(query), Book.author.contains(query), ) ) ... ``` Client-side, easy. The little search field will trigger a request with the `q` parameter: ```html ``` **Notes** - `value="{{ query }}"`: the query value is returned by the server alongside with the filtered results, so we keep track of current filter applied - `hx-push-url="true"`: updates the URL so the search is bookmarkable - `hx-trigger="keyup changed delay:500ms"`: debounce, avoids a request on every keystroke ## Pagination Already wired as well: ```py @router.get("/books", response_class=HTMLResponse) def list_books( request: Request, user_id: str=USER_ID, q: Optional[str]="", limit:int=10,# <-- HERE page: int=1,# <-- HERE session: Session=Depends(get_session)): ``` And in the `table.html`: ```html

Page {{ page }}

``` ## What's next Part 2: authentication — JWT cookies, login, token refresh middleware, and replacing `USER_ID = "dev-user"` with a real user.

Dashboard

{{ name }}

{{ title }}