karura-trails

tigawanna/karura-trails

Forest trail maps, field marker capture, and an admin sync hub for Karura Forest.

expo
op-sqlite
pglite
react-native
spatialite
tanstack-start

karura-trails

Karura Trails

Forest trail maps, field marker capture, and an admin sync hub for Karura Forest.

App	Stack	Purpose
mobile	Expo, MapLibre, SpatiaLite	Offline maps, navigation, marker edits in the field
web	TanStack Start, Cloudflare Workers, D1	Landing page, admin dashboard, auth, sync API

Architecture detail: ARCHITECTURE.md

Prerequisites

Node.js 18+
pnpm 9+
For mobile: Android Studio and/or Xcode, Expo CLI workflow
For web deploy: Cloudflare account + Wrangler

Monorepo

typescript

1apps/
2  mobile/     Expo app (primary product)
3  web/        TanStack Start on Cloudflare Workers
4packages/     Shared TS / ESLint configs

Managed with pnpm workspaces and Turborepo.

Getting started

Install

bash

1pnpm install

Web (admin + sync API)

bash

1cd apps/web
2cp .env.example .env
3cp .dev.vars.example .dev.vars   # edit secrets — see ARCHITECTURE.md
4pnpm db:migrate:local
5pnpm dev                         # http://localhost:3050

Mobile

bash

1cd apps/mobile
2pnpm dev                         # Expo dev server
3# or
4pnpm run:android
5pnpm run:ios

See apps/mobile/GAMEPLAN.md for schema, routing, and build profiles.

All apps (from root)

bash

1pnpm dev
2pnpm build
3pnpm check-types

Filter to one app:

bash

1pnpm dev --filter=web
2pnpm dev --filter=mobile

Web environment

Two files in apps/web:

File	Scope
`.env`	Vite client (`VITE_API_URL`, `VITE_GOOGLE_AUTH_ENABLED`)
`.dev.vars`	Worker secrets (auth, CORS, sync secret, Google OAuth)

Full variable list: ARCHITECTURE.md — Environment

Deploy web to Cloudflare

bash

1cd apps/web
2# 1. Set real database_id in wrangler.jsonc (wrangler d1 create karura-trails-db)
3# 2. wrangler secret put BETTER_AUTH_SECRET  (and other secrets)
4pnpm db:migrate:remote
5pnpm deploy

Sync API (dev)

Mobile clients (or curl) can push events:

bash

1curl -X POST http://localhost:3050/api/sync/events \
2  -H "Content-Type: application/json" \
3  -H "x-sync-secret: local-dev-sync-secret" \
4  -d '{"deviceId":"test","events":[{"id":"01932f8a-7c3a-7000-8000-000000000001","deviceId":"test","table":"points","rowId":"42","action":"create","payload":{},"createdAt":"2026-06-08T12:00:00.000Z"}]}'

Admins verify events at /events. Verified events are returned on GET /api/sync/events.

Protocol: apps/mobile/docs/EVENT-SYNC-PLAN.md

Quality

bash

1pnpm lint
2pnpm format
3pnpm quality        # lint + format check
4pnpm quality:fix

License

See per-app license files where applicable (apps/mobile/LICENSE).