danabra.mov
an app to share curated trails
sidetrail.app
atproto
nextjs
react
rsc
1# Sidetrail
2
3[Sidetrail](https://sidetrail.app/) is an app to create and share "trails". Create sequential paths with 2-12 stops, walk through them one step at a time, and share them with others.
4
5Built on [AT](https://atproto.com/) protocol: trails, walks, and completions are stored in users' repositories and synced via Jetstream.
6
7## Architecture
8
9Three services:
10
11- **Next.js app** — Web frontend + API. Reads from PostgreSQL, writes to users' ATProto repos via OAuth.
12- **Ingester** — Subscribes to [Jetstream](https://docs.bsky.app/blog/jetstream) and indexes `app.sidetrail.*` records into PostgreSQL.
13- **Realtime** — Rebroadcasts Jetstream events to browser clients for real-time updates on some pages.
14
15## Local Development
16
17### Prerequisites
18
19- Node.js 22.16.0+
20- PostgreSQL
21- Redis
22
23### Setup
24
25```bash
26# Install dependencies
27npm install
28
29# Copy environment file and configure DATABASE_URL and REDIS_URL
30cp .env.example .env
31
32# Push database schema
33npm run db:push
34
35# Start all services (run in separate terminals)
36npm run dev # Next.js app on :3000
37npm run dev:ingester # Jetstream ingester
38npm run dev:realtime # Realtime server
39```
40
41Then open `127.0.0.1:300` (it has to be `127.0.0.1`, not `localhost`).
42
43### Environment Variables
44
45See `.env.example`. For local development, `DATABASE_URL` and `REDIS_URL` are required.
46
47Production requires:
48
49- `PUBLIC_URL` - Your app's public URL
50- `PRIVATE_KEY_ES256` - OAuth signing key (generate with `node scripts/gen-jwk.mjs`)
51- `COOKIE_SECRET` - Session encryption (32+ chars)
52
53## Lexicons
54
55Sidetrail uses three ATProto record types:
56
57- `app.sidetrail.trail` - Trail with embedded stops
58- `app.sidetrail.walk` - User's current walk state (deleted on completion)
59- `app.sidetrail.completion` - Permanent completion record
60
61See [lexicons/LEXICONS.md](lexicons/LEXICONS.md) for details.
62
63## Testing
64
65```bash
66# Create test database (one-time)
67psql -c "CREATE DATABASE sidetrail_test"
68
69npm test
70```
71
72## Scripts
73
74```bash
75npm run dev # Start Next.js dev server
76npm run dev:ingester # Start Jetstream ingester
77npm run dev:realtime # Start realtime server
78
79npm run build # Production build
80npm run db:push # Push schema to database
81npm run db:studio # Open Drizzle Studio
82
83npm run test # Run tests
84npm run check # Lint + typecheck
85```
86
87## Deployment
88
89Uses [Railway](https://railway.app/) with three services. Deploy with:
90
91```bash
92npm run deploy:app
93npm run deploy:ingester
94npm run deploy:realtime
95```
96
97## License
98
99MIT