LocalLink
Local places, events, products and communities for everyone. A Houston-first, English/Traditional Chinese discovery platform built around a map and shareable layers. Houston is the launch city; this is not a claim of worldwide coverage, and the feed-extraction geocoder is the US Census geocoder, which resolves US street addresses only. Taiwanese restaurants, groceries, organizations and product sightings remain supported as one set of local content among many.
Naming and legacy identifiers
The product was previously named TaiwanHub. Technical identifiers were deliberately left unchanged for compatibility: the @taiwanhub/* workspace packages, the repository directory, browser storage keys (taiwanhub:map, taiwanhub:map-view), cryptographic purpose strings, database/CI/Docker names, the .invalid demo and test mail domains, and existing environment variables. See docs/plans/locallink-rebrand-implementation-plan.md.
Start with the guides
Run locally
Requirements: Node.js 22, pnpm 10.15+, Docker Desktop with Linux containers.
pnpm install
cp .env.example .env
# Windows PowerShell: Copy-Item .env.example .env
docker compose up -d
pnpm db:migrate
pnpm db:seed
pnpm dev
Open http://localhost:3000. Set AUTH_SECRET in .env to a random value before running a shared environment. Generate one with node -e "console.log(require('crypto').randomBytes(32).toString('hex'))". .env is ignored by Git. Next loads the workspace .env through its config; database tools load it directly.
Membership is invite-only - there is no public sign-up page. Seed users have no passwords and cannot log in, and no default admin or backdoor login is installed. To create your own account in a fresh environment, set MEMBERSHIP_MODE=invite_only in .env, then bootstrap the first invitation:
pnpm membership:bootstrap [email protected]
# follow the one-time link it prints to /join, complete the Email OTP flow, then:
pnpm admin:grant [email protected]
Returning members sign in at /sign-in with an email code by default (password and Google remain for accounts that use them). Only admitted members receive a code, and application privileges require a membership admission, not just a session. Locally, with MAIL_PROVIDER unset, codes and invitations go to an in-memory test transport that nothing displays; read them from the test suites, or configure a real provider for manual testing.
Visit /admin to approve pending events, places, sightings and notes; edit content; hide, reject or soft-delete content; and use /admin/membership to open batches, invite people directly, and grant/revoke reviewer access. Moderator roles can review and edit; only admins can soft-delete. Roles are never accepted from account creation or profile requests. See docs/plans/invitation-membership-implementation-plan.md for how membership works end to end.
Stack and layout
apps/web: Next.js 16 App Router, React 19, strict TypeScript, Tailwind 4, responsive custom components, React Hook Form and Zod.packages/database: Drizzle schema, checked-in SQL migrations, PostgreSQL/PostGIS, repeatable demo seeds.packages/shared: domain types, Zod boundaries, authorization and transparent ranking functions. This is the starting point for a future Expo app.src/features/catalog: public data queries and home feed composition.src/features/community: transactional mutations and moderation, separate from HTTP routes.- Better Auth: maintained password sign-in (existing accounts only), Email OTP (the invite-only membership path), and optional Google authentication, with bearer support for future mobile clients. Selected instead of Auth.js to avoid implementing password hashing, registration and credential account management ourselves.
Drizzle keeps PostgreSQL features explicit, including typed PostGIS geometry columns and GiST indexes. Complex capacity and ranking queries use parameterized SQL through its underlying pg pool. There is one database and one ORM, no microservice or second store.
Demo content
The seed contains 20 places, 10 events, 5 organizations, 10 products, 20 sightings, 15 users and 50 recommendation votes. All catalog content is marked demo. Even real brand or store names in the seed have fictional reports and location details. Never use demo addresses or dates to plan visits. Product images are original local demo illustrations; food/event photos are generic Unsplash imagery, not photos of the named businesses.
Seeds insert deterministic UUIDs and do not erase user data. Running again refreshes the demo product artwork and grocery classifications. Event dates are relative to the first seed run; existing events retain their dates. Use a fresh development database when you want a fresh demo schedule. Never run demo seeds against the production database.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
