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>
126 lines
6.4 KiB
Markdown
126 lines
6.4 KiB
Markdown
# 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](../design/v0.x/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](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](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/](../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](indieweb-protocols.md),
|
|
[simplified-auth-architecture.md](simplified-auth-architecture.md),
|
|
[syndication-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**:
|
|
|
|
```bash
|
|
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](../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](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/](../standards/) for the versioning and git-branching
|
|
standards.
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-11-10 (v2.14.0)
|