Files
StarPunk/docs/architecture/technology-stack.md
T
PhilandClaude Opus 5.5 0716984958 docs: Bring all documentation up to date for v2.10.1
- architecture/: overview, technology stack, auth (OIDC + built-in
  IndieAuth), syndication (POSSE) rewritten; new database.md,
  deployment.md and indieweb-protocols.md; legacy stack marked historical
- decisions/: reconstructed ADR-060 and ADR-063; 31 status corrections
  (superseded auth ADRs, proposed -> accepted); INDEX rebuilt
- design/: reconstructed the v1.6.0 documents the webmention code cites;
  reports for 18 v2 releases without a design folder; INDEX rebuilt
- projectplan/: BACKLOG rewritten (shipped items removed, open issues from
  the reviews added); RELEASE.md for v2.0.0-v2.10.1; INDEX
- standards/: development setup (uv, tests, DEV_MODE), testing (CI test
  stage), git and release flow, versioning, coding standards, cookies
- README, CLAUDE.md, .env.example (every setting the code reads, with
  defaults) brought up to date
- 137 broken links repaired (old absolute paths, moved files); stale ADR
  references in code comments corrected (comments only)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 12:40:19 -07:00

5.9 KiB

StarPunk Technology Stack

Version: 2.10.1 (2026-11-03) Status: Current. The original v0.x stack write-up is kept as technology-stack-legacy.md for history.

StarPunk deliberately uses few dependencies: a WSGI web framework, SQLite from the standard library, plain files, server-rendered templates and a handful of libraries for parsing, images and security. No JavaScript build, no external database, no task queue. See overview.md for how the pieces fit together.

Runtime

Component Choice
Language Python 3.11 (python:3.11-slim base image)
Web framework Flask 3.0 (Werkzeug, Jinja2, itsdangerous, click come with it)
WSGI server gunicorn 21.2, 4 sync workers (see deployment.md)
Database SQLite (standard-library sqlite3), WAL mode, FTS5 for search
Content storage Markdown files on disk
Background work threading daemon threads; fcntl.flock file locks to pick one process
Templates Jinja2, server-side rendered
Front end One hand-written stylesheet; one small vanilla JS file for the editor's Markdown preview
Packaging uv creates the virtual environment and installs requirements (locally and in the image)
Container Multi-stage Containerfile (Podman/Docker), non-root user
Reverse proxy Caddy in production (examples for Caddy and nginx in the repo)

Python dependencies (requirements.txt)

Package Pin Used for
Flask 3.0.* Web framework
gunicorn 21.2.* Production WSGI server
markdown 3.5.* Rendering notes (extra, codehilite, nl2br and a bare-URL linking extension)
feedgen 1.0.* RSS 2.0 feed (starpunk/feeds/rss.py); Atom and JSON Feed are generated by StarPunk's own code
httpx 0.27.* All outbound HTTP: OIDC, IndieAuth client discovery, webmention and WebSub requests (through the SSRF-safe wrapper in webmention_ssrf.py), crossposting APIs, health check
python-dotenv 1.0.* Loading .env
beautifulsoup4 4.12.* HTML parsing: IndieAuth client pages, crosspost text and link cards
mf2py 2.0.* Parsing microformats2 (webmention sources, reply contexts, author h-card)
pytest 8.0.* Test runner (listed here as well as in the image's test stage)
psutil 5.9.* Memory monitor and system metrics
Pillow 10.1.* Image validation, resizing and variants
pillow-heif 0.18.* HEIC/HEIF uploads (iPhone photos)
nh3 0.2.* HTML sanitising (rendered notes, webmention content)
PyJWT[crypto] 2.10.* Verifying OIDC ID tokens (JWKS, RS/ES signatures via cryptography)

Packages imported directly but installed only as dependencies of the above: lxml (outgoing link extraction, webmention endpoint discovery and source checks; from feedgen) and python-dateutil (dates in reply contexts; from feedgen). markupsafe comes with Flask/Jinja2.

Development dependencies (requirements-dev.txt)

Includes requirements.txt, plus pytest-cov, pytest-mock, black, flake8, mypy and gunicorn. Coding standards are in ../standards/.

Deliberately not used

No ORM (plain SQL), no Flask extensions (login, WTF, SQLAlchemy, caching), no Celery/Redis or other broker (worker threads with SQLite queues), no front-end framework or bundler, no separate search server.

Standards implemented

Area Standards
IndieWeb Micropub (create, update, delete, undelete, queries, media endpoint), IndieAuth (authorization server with PKCE, metadata endpoint, token revocation), Webmention (send and receive), WebSub (publisher and built-in hub), microformats2 (h-entry, h-feed, h-card markup and parsing), rel=me
Login OpenID Connect authorization code flow with PKCE (provider: Pocket ID)
Feeds RSS 2.0, Atom 1.0, JSON Feed 1.1, OPML 2.0, HTTP content negotiation
Crossposting Mastodon client API (GoToSocial), AT Protocol (Bluesky XRPC), Threads Graph API

Protocol details: indieweb-protocols.md, simplified-auth-architecture.md, syndication-architecture.md.

Testing

  • Framework: pytest with pytest-mock; about 1,250 tests in tests/ (test_*.py per module or feature, shared fixtures in tests/conftest.py, helpers in tests/helpers/).

  • Isolation: the app fixture calls create_app() with TESTING=True and a temporary data directory, so every test gets a fresh database (all migrations applied) and note directory. With TESTING=True no background threads start and the OIDC settings are not required; tests drive worker functions directly.

  • Network: outbound HTTP is mocked; webmention_ssrf.TRANSPORT accepts an httpx.MockTransport for fetcher tests.

  • Running locally:

    uv venv && uv pip install -r requirements-dev.txt
    .venv/bin/python -m pytest
    
  • In CI: the test stage of the Containerfile installs the production requirements plus pytest and pytest-mock and runs the whole suite. The image is only built and pushed if it passes. Checklist: ../standards/testing-checklist.md.

CI/CD

Gitea Actions, one workflow (.gitea/workflows/build-container.yml), run on vX.Y.Z tags or by hand: build the test stage (runs pytest), then build and push the runtime image to the Gitea container registry tagged with the version and latest. Builds go to a rootless BuildKit daemon; there is no Docker daemon on the runner. Production pulls the new tag through the Ansible-managed deployment. Details: deployment.md.

Versioning

Semantic versioning; the version is __version__ in starpunk/__init__.py and every release has a CHANGELOG.md entry and a vX.Y.Z git tag. See ../standards/ for the versioning and git-branching standards.


Last Updated: 2026-11-03 (v2.10.1)