ad/ARCHITECTURE.md

Architectuur

Lagen

• molodetz/main.py: FastAPI-object (/swagger, /openapi.json), lifespan (init-lock, init_db, bootstrap, services met service-lock), statische mounts (uploads, versioned /static/v<STATIC_VERSION>/, fallback), middleware in templatevolgorde, exception handlers, routers.
• molodetz/config.py: enige plek voor load_dotenv, paden, env-bindingen met prefix MOLODETZ_, APP_VERSION via tomllib, BOOT_ID, STATIC_VERSION.
• molodetz/database/: synchrone dataset-handle (SQLAlchemy NullPool, WAL-PRAGMA's), per-tabel modules, soft delete met registries, init_db met indexen en ANALYZE. Geen async driver en geen threadpool rond databasecalls: de synchrone laag wordt direct in async handlers aangeroepen (sectie 7.1). Alleen CPU- en bestandswerk (PBKDF2, archiefbouw, DNS) gaat via asyncio.to_thread.
• molodetz/routers/: een module per oppervlak. Elke HTML-route geeft JSON bij Accept: application/json via responses.respond en een Pydantic-uitvoerschema uit schemas/.
• molodetz/templating.py: de enige Jinja2Templates. Globals static_url, local_dt, avatar_url, render_content en meer.
• molodetz/rendering.py: server-side markdown (mistune, escape aan), emoji, URL-allowlist, streepjesnormalisatie. Gepubliceerde inhoud wordt altijd server-side gerenderd.
• molodetz/stealth.py: enige fabriek voor uitgaande HTTP-clients (httpx met curl_cffi-transport, net_guard SSRF-bescherming). link_check.py gebruikt hem voor de repo-linkcontrole bij aanmeldingen.
• molodetz/services/: achtergrondservices (presence, housekeeping, backup) onder een ServiceManager, zichtbaar en bestuurbaar via /admin/services.
• molodetz/gallery.py: flyers en memes uit static/media/, Pillow-thumbnails (webp) als blobs onder data/uploads, perceptuele hash (imagehash) tegen duplicaten.
• molodetz/cli/: argparse-CLI molodetz.
• molodetz/static/js/: ES6-modules zonder bundler. Application.js laadt components/index.js (custom elements in light DOM) en zet singletons op window.app. Vendor: marked, DOMPurify, highlight.js als ES-modules in static/vendor/.
• molodetz/static/css/: handgeschreven, tokens in variables.css, breakpoints exact 360/480/768/1024.

Auth

Sessiecookie (HttpOnly, SameSite=Lax, Secure achter TLS), rijen in sessions. Daarnaast X-API-KEY, Authorization: Bearer <api key> en Basic voor scripts. Wachtwoorden met passlib PBKDF2-SHA256. Geen JWT, geen OAuth. De eerste gebruiker is de beheerder uit .env; er is geen publieke registratie.

Datastromen

• Schrijven: beheerder -> /admin/posts -> content.create_post / edit_post -> SQLite -> server-render bij lezen (lru-cache op tekst).
• Aanmelden: bezoeker -> POST /binnen (honeypot, rate limit) -> join_requests -> melding aan beheerders -> /admin/joins.
• Galerij: start -> sync_gallery -> media-tabel + thumbnails -> /flyers, /memes met lightbox.