desertthunder.dev / twisted
a love letter to tangled (android, iOS, and a search API)
fork atom
Go 45.8%
Vue 24.6%
TypeScript 18.3%
HTML 2.1%
Python 2.1%
JavaScript 1.2%
Shell 1.2%
CSS 1.1%
Swift 0.6%
Batchfile 0.4%
Just 0.3%
Java 0.2%
Dockerfile 0.1%
Other 2.0%
53 1 2

Clone this repository

https://tangled.org/desertthunder.dev/twisted https://tangled.org/did:plc:xg2vq45muivyy3xwatcehspu/twisted
git@tangled.org:desertthunder.dev/twisted git@tangled.org:did:plc:xg2vq45muivyy3xwatcehspu/twisted

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
README.md

Twisted#

Twisted is a monorepo for a Tangled mobile client and the supporting Tap-backed indexing API.

Projects#

  • apps/twisted: Ionic Vue client for browsing Tangled repos, profiles, issues, PRs, and indexed search results
  • packages/api: Go service that consumes Tangled records through Tap, fills gaps in the public Tangled API, and serves search
  • docs: top-level specs and plans, split by project under docs/app and docs/api

Architecture#

The app still uses Tangled's public knot and PDS APIs for canonical repo and profile data. The API project adds two complementary capabilities:

  1. Global search over indexed Tangled content
  2. Index-backed summaries for data that is hard to derive from the public API alone, such as followers

That keeps direct browsing honest while giving the client one place to ask for cross-network discovery and graph augmentation.

Development#

Use the top-level justfile for common workflows (just --list to view)

Use apps/twisted/.env.local for machine-local overrides such as a localhost API or OAuth callback.

Run Locally#

Install dependencies once from the repo root:

pnpm install

Start the Ionic/Vite app:

pnpm dev # or: just dev

That serves the client from apps/twisted with Vite.

To run the Go API locally for routine experimentation, no Turso credentials are required.

Start the API in local file mode:

pnpm api:run:api # or: just api-dev

This serves the API and search site on http://localhost:8080 using packages/api/twister-dev.db.

To run the API against remote Turso instead:

just api-dev remote

Run the API smoke checks from the repo root:

uv run --project packages/scripts/api twister-api-smoke

To verify admin endpoints as well, ensure ADMIN_AUTH_TOKEN is present in the environment before running the smoke script.

To run the indexer in local file mode as well:

pnpm api:run:indexer # or: just api-run-indexer

To run the indexer against remote Turso, packages/api/.env needs:

  • TAP_URL
  • TAP_AUTH_PASSWORD
  • INDEXED_COLLECTIONS
just api-run-indexer remote

Typical local setup is three terminals:

  1. pnpm dev
  2. pnpm api:run:api
  3. pnpm api:run:indexer

If you want the app to call the local API, put this in apps/twisted/.env.local:

VITE_TWISTER_API_BASE_URL=http://localhost:8080

Dev builds keep the current OAuth flow available. Production builds are read-only and hide auth entry points for now.

Attributions#

This project relies heavily on the work of the Tangled team (duh) and the infrastructure made available by microcosm, specifically Lightrail and Constellation.