Files
StarPunk/docs/architecture/technology-stack.md
T
PhilandClaude Opus 5.5 84411a16d9 feat: MCP server for AI clients (v2.15.0, ADR-075)
Add an MCP server at SITE_URL/mcp so AI assistants (claude.ai connectors,
Claude Code) can search, read and write notes.

- starpunk/mcp_server: official MCP SDK 2.3, stateless Streamable HTTP with
  JSON responses, served by uvicorn as a sidecar from the same image.
  Ten tools; writes go through the Micropub handlers.
- IndieAuth: RFC 8707 resource indicators bound to codes and tokens
  (migration 022), client ID metadata document + public client metadata,
  draft in scopes_supported, default MCP scopes, consent screen note.
- BACKGROUND_WORKERS_ENABLED flag so the sidecar runs no workers.
- Docs: ADR-075, architecture/mcp.md and updates; CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 16:36:58 -07:00

6.8 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)
mcp 2.3.* MCP server for AI clients (starpunk/mcp_server/, ADR-075); brings Starlette, pydantic and anyio. Only the sidecar imports it
uvicorn 0.54.* ASGI server for the MCP sidecar

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
AI clients Model Context Protocol (Streamable HTTP, stateless), OAuth 2.0 Protected Resource Metadata (RFC 9728), Resource Indicators (RFC 8707), Client ID Metadata Documents
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)