desertthunder.dev
a love letter to tangled (android, iOS, and a search API)
1# Twisted
2
3Twisted is a monorepo for a Tangled mobile client and a Tap-backed indexing API.
4
5## Projects
6
7- `apps/twisted`: Ionic Vue client for browsing Tangled repos, profiles, issues, PRs, and search
8- `packages/api`: Go service for ingest, search, read-through indexing, and activity cache
9- `docs`: project docs, ADRs, and operational references
10
11## Architecture
12
13The app still reads canonical repo and profile data from Tangled and AT Protocol APIs.
14The API adds:
15
161. network-wide search over indexed Tangled content
172. index-backed summaries that are hard to derive from public APIs alone
18
19The backend now targets PostgreSQL for both local and remote deployments.
20
21## Development
22
23Install JS dependencies once:
24
25```bash
26pnpm install
27```
28
29Default local database URL:
30
31```bash
32postgresql://localhost/${USER}_dev?sslmode=disable
33```
34
35That matches the Postgres.app-style local workflow and also matches the repo's
36`docker-compose.dev.yaml` if you want disposable local Postgres and Tap
37containers instead.
38
39Start the local database:
40
41```bash
42just db-up
43```
44
45Bootstrap the schema once:
46
47```bash
48just api-build
49DATABASE_URL="postgresql://localhost/${USER}_dev?sslmode=disable" \
50 ./packages/api/twister migrate
51```
52
53Run the mobile app:
54
55```bash
56pnpm dev
57```
58
59Run the API against local Postgres:
60
61```bash
62just api-dev
63```
64
65Run the indexer against local Postgres:
66
67```bash
68just api-run-indexer
69```
70
71Use `just api-dev sqlite` or `just api-run-indexer sqlite` only for the
72temporary SQLite rollback path.
73
74If you want the app to call the local API, put this in `apps/twisted/.env.local`:
75
76```bash
77VITE_TWISTER_API_BASE_URL=http://localhost:8080
78```
79
80Run the API smoke checks from the repo root:
81
82```bash
83uv run --project packages/scripts/api twister-api-smoke
84```
85
86If `ADMIN_AUTH_TOKEN` is present, the smoke script also checks admin status.
87
88## Deployment
89
90`docker-compose.prod.yaml` is now the source-of-truth VPS stack. It runs
91`postgres`, `migrate`, `api`, `indexer`, `tap`, and `llama-embeddings`.
92
93The llama.cpp service is only deployment groundwork for a later embedding
94adapter. Search remains keyword-only for now.
95
96See [`docs/reference/deployment-walkthrough.md`](docs/reference/deployment-walkthrough.md)
97for the full setup, bootstrap, backup, and cutover flow.
98
99## Attributions
100
101This project relies heavily on the work of the
102[Tangled team](https://tangled.org/tangled.org) and the infrastructure made
103available by [microcosm](https://microcosm.blue), especially Lightrail and
104Constellation.