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

120 lines
5.9 KiB
Markdown

# 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](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.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](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/](../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](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,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**:
```bash
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](../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-03 (v2.10.1)