desertthunder.dev
a love letter to tangled (android, iOS, and a search API)
1// Twister is the Tap-backed indexing and search API for Tangled.
2//
3// Requirements
4//
5// - Go 1.25+
6// - PostgreSQL for the normal local and production workflow
7//
8// Running locally
9//
10// cd /Users/owais/Projects/Twisted
11// just db-up
12// just api-build
13// DATABASE_URL=postgresql://localhost/${USER}_dev?sslmode=disable ./packages/api/twister migrate
14// just api-dev
15// just api-run-indexer
16//
17// The default local database URL is:
18//
19// postgresql://localhost/${USER}_dev?sslmode=disable
20//
21// That matches a Postgres.app-style setup and the repo's dev compose file.
22//
23// # Legacy fallback
24//
25// `--local` is deprecated and switches the service to the temporary SQLite
26// fallback at packages/api/twister-dev.db.
27//
28// go run . api --local
29//
30// Smoke checks
31//
32// uv run --project packages/scripts/api twister-api-smoke
33//
34// Optional base URL override:
35//
36// TWISTER_API_BASE_URL=http://localhost:8080 \
37// uv run --project packages/scripts/api twister-api-smoke
38//
39// Environment variables
40//
41// - DATABASE_URL: primary database connection URL
42// - HTTP_BIND_ADDR: API bind address, default :8080
43// - INDEXER_HEALTH_ADDR: indexer health bind address, default :9090
44// - LOG_LEVEL: debug, info, warn, or error
45// - LOG_FORMAT: json or text
46// - TAP_URL: Tap WebSocket URL, default ws://localhost:2480/channel in local indexer runs
47// - TAP_AUTH_PASSWORD: Tap admin password, default twisted-dev in local indexer runs
48// - INDEXED_COLLECTIONS: comma-separated AT collections to index
49// - READ_THROUGH_MODE: off or missing; default missing
50// - READ_THROUGH_COLLECTIONS: read-through allowlist
51// - READ_THROUGH_MAX_ATTEMPTS: retries before dead_letter
52// - ENABLE_ADMIN_ENDPOINTS: default false
53// - ADMIN_AUTH_TOKEN: bearer token for admin routes
54//
55// CLI commands
56//
57// twister api
58// twister indexer
59// twister migrate
60// twister backfill
61// twister reindex
62// twister enrich
63// twister healthcheck
64//
65// # Deployment
66//
67// Production uses docker-compose.prod.yaml as the source-of-truth VPS stack:
68// PostgreSQL, migrate, api, indexer, tap, and llama-embeddings.
69//
70// Semantic search is still deferred. The llama.cpp service is present only as
71// operational groundwork for a later embedding adapter.
72package main