Files
StarPunk/docs/architecture/technology-stack.md
T
PhilandClaude Opus 5.5 ceef048003 docs: documentation review for v2.14.0
Architecture, README, standards, CLAUDE.md, settings reference, indexes,
backlog, release plans and CHANGELOG checked against the code at v2.14.0:
backfeed, notifications, counts line and web actions documented; test
policy (changed area locally, full suite in CI); stale versions, statuses
and links fixed; legacy and superseded docs moved.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 14:51:57 -07:00

6.4 KiB

StarPunk Technology Stack

Version: 2.14.0 (2026-11-10) 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.14 (python:3.14-slim base image; since v2.11.0)
Web framework Flask 3.1 (Werkzeug, Jinja2, itsdangerous, click come with it)
WSGI server gunicorn 26.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; small inline scripts on admin pages; no JavaScript on public pages
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)

Pinned to a minor series. Upgraded in v2.11.0, when the set had no known vulnerabilities (pip-audit); check again before each release.

Package Pin Used for
Flask 3.1.* Web framework
gunicorn 26.2.* Production WSGI server
markdown 3.11.* Rendering notes (extra, codehilite, nl2br and a bare-URL linking extension)
nh3 0.3.* HTML sanitising (rendered notes, webmention content)
beautifulsoup4 4.15.* HTML parsing: IndieAuth client pages, crosspost text and link cards
lxml 6.1.* Outgoing link extraction, webmention endpoint discovery and source checks
mf2py 2.0.* Parsing microformats2 (webmention sources, reply contexts, author h-card)
python-dateutil 4.0.* Dates in reply contexts
feedgen 1.0.* RSS 2.0 feed (starpunk/feeds/rss.py); Atom and JSON Feed are generated by StarPunk's own code
httpx 0.28.* All outbound HTTP; requests to user-supplied URLs go through webmention_ssrf.safe_get/safe_post
apprise 2.2.* Notifications to the owner's services (starpunk/notifications.py, ADR-074); sends to the URLs the owner configures, outside the SSRF-safe fetcher
PyJWT[crypto] 2.15.* Verifying OIDC ID tokens (JWKS, RS/ES signatures via cryptography)
python-dotenv 1.2.* Loading .env
Pillow 13.0.* Image validation, resizing and variants; converting response avatars to 96 px WebP (avatars.py)
pillow-heif 1.8.* HEIC/HEIF uploads (iPhone photos)

markupsafe comes with Flask/Jinja2.

Test and development dependencies

  • requirements-test.txt: pytest 9.2 and pytest-mock 3.15, used by the Containerfile test stage (CI).
  • requirements-dev.txt: runtime and test requirements plus pytest-cov, black, flake8, mypy (not enforced) and pip-audit. 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, web actions (<indie-action>), backfeed of responses from the silos
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; the same APIs are read for backfeed

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

Testing

  • Framework: pytest with pytest-mock; about 1,260 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 --python 3.14 && uv pip install -r requirements-dev.txt
    SESSION_SECRET=test uv run pytest tests/test_<area>.py
    

    Locally, run the tests for the area you changed; CI runs the full suite.

  • In CI: the test stage of the Containerfile installs the production requirements plus requirements-test.txt 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-10 (v2.14.0)