Brackeys

Brackeys is the community web app for the Brackeys Discord. This repo is a single TanStack Start application that powers:

• the home / jam landing page
• the command center
• developer profiles
• the collab board

This README is the repo-level source of truth for local setup and day-to-day development. The old starter README is intentionally replaced because it no longer matched the codebase.

Stack

• TanStack Start + Vite
• React 19
• TanStack Router, Query, Store, and Devtools
• Tailwind CSS v4
• Biome
• Drizzle ORM + PostgreSQL
• Better Auth
• ORPC
• Storybook

Main App Surfaces

• / home / jam landing page
• /command-center command and macro docs
• /profile sign-in gate and profile entry
• /profile/:userId public profile view and owner edit flow
• /collab collab browse flow
• /collab/new collab post creation
• /collab/:postId collab post detail
• /oauth/github/callback GitHub account-link callback
• /oauth/itchio/callback itch.io link callback
• /api/auth/* Better Auth endpoints
• /api/rpc/* ORPC endpoints

Repo Structure

src/
  components/
    collab/
    home/
    layout/
    profile/
    ui/
  db/
  lib/
  orpc/
  routes/
drizzle/
.storybook/

Important files:

• src/routes/__root.tsx: shell, background, command palette, layout
• src/db/schema.ts: app schema
• src/lib/auth.ts: Better Auth provider config
• src/orpc/router/*: typed server procedures
• drizzle.config.ts: Drizzle config

Prerequisites

• Bun
• PostgreSQL
• Discord OAuth app credentials

Optional but relevant depending on what you are working on:

• GitHub OAuth app credentials
• itch.io client ID
• Strapi instance for collab image uploads
• MinIO credentials for profile image uploads
• PostHog project API key

Setup

1. Install dependencies.

bun install

2. Create local env vars.

Copy-Item .env.example .env.local

3. Fill in the required secrets in .env.local.

Minimum required for most local work:

• DATABASE_URL
• BETTER_AUTH_URL
• BETTER_AUTH_SECRET
• DISCORD_CLIENT_ID
• DISCORD_CLIENT_SECRET
• DISCORD_GUILD_ID

4. Apply database schema.

Only the user should ever run bun run db:generate, bun run db:migrate, or bun run db:push. Agents should update schema and migration files, but the user remains the only operator for those commands.

For an existing migration flow:

bun run db:migrate

For fast local iteration against an empty local database:

bun run db:push

5. Start the dev server.

bun run dev

The app runs on http://localhost:3000.

Environment Variables

README only documents variables that are actually referenced in the repo today.

Required

• DATABASE_URL: Postgres connection string
• BETTER_AUTH_URL: local app URL, usually http://localhost:3000
• BETTER_AUTH_SECRET: Better Auth secret
• DISCORD_CLIENT_ID: Discord OAuth client ID
• DISCORD_CLIENT_SECRET: Discord OAuth client secret
• DISCORD_GUILD_ID: guild used for member role/profile enrichment

Required for specific features

• GITHUB_CLIENT_ID: GitHub account linking
• GITHUB_CLIENT_SECRET: GitHub account linking
• VITE_ITCHIO_CLIENT_ID: itch.io linking flow
• VITE_STRAPI_URL: Strapi-backed uploads / demo content
• MINIO_ENDPOINT: MinIO server URL, for example https://your-minio-host.up.railway.app
• MINIO_PUBLIC_BASE_URL: public base URL used to render stored objects
• MINIO_BUCKET: bucket name for uploaded profile project images
• MINIO_ACCESS_KEY: MinIO access key
• MINIO_SECRET_KEY: MinIO secret key

Optional

• VITE_APP_TITLE: client title override
• SERVER_URL: server-side absolute URL override
• VITE_POSTHOG_KEY: PostHog project API key — analytics, feature flags, error tracking (all off when unset)
• VITE_POSTHOG_HOST: PostHog ingestion host, for example https://eu.i.posthog.com, or the reverse proxy path once workers/posthog-proxy is deployed. Inlined into the browser bundle at build time — changing it needs a rebuild, not just a restart.
• POSTHOG_PERSONAL_API_KEY: build-time, server-only — enables source-map upload so error stacks are un-minified. Never give this a VITE_ prefix: it is a write credential and the prefix would inline it into the browser bundle. Absent means maps are simply not uploaded.
• POSTHOG_PROJECT_ID: build-time, pairs with the personal API key
• POSTHOG_API_HOST: build-time, optional — the PostHog API/UI host for source-map upload (https://eu.posthog.com). Distinct from the ingestion host below; do not set both to the same value.
• POSTHOG_KEY / POSTHOG_HOST: read by the services/* workers for error reporting; they fall back to the VITE_-prefixed names so one Railway shared variable can cover everything

Railway CLI (optional)

If you have access to the Railway project, you can pull environment variables directly from Railway instead of maintaining .env.local manually.

Install

https://docs.railway.com/cli#installing-the-cli

npm i -g @railway/cli
# or MacOS
brew install railway
# or Linux/WSL
bash <(curl -fsSL cli.new)

Link your local repo

railway login
railway link

The interactive prompt will ask you to select the workspace, project, environment, and service.

Switch environments

railway environment       # list available environments
railway environment dev   # switch to dev

Run with Railway env vars

Use the railway:* scripts to run any command with Railway-injected environment variables:

vp run railway:dev          # dev server with Railway env vars
vp run railway:build        # production build
vp run railway:db:migrate   # run migrations against Railway database
vp run railway:db:studio    # open Drizzle Studio against Railway database

You can also pass -s <service> and -e <environment> flags inline:

railway run -e staging -- vp dev --port 3000

The standard bun run dev / vp run dev workflow with .env.local continues to work for developers who do not need Railway CLI.

Useful Commands

bun run dev
bun run build
bun run preview
bun run start

bun run db:generate
bun run db:migrate
bun run db:push
bun run db:pull
bun run db:studio

bun run lint
bun run format
bun run check
bun run test

bun run storybook
bun run build-storybook

bun run db:generate, bun run db:migrate, and bun run db:push are user-only commands. Do not have agents execute them.

Versioning

__APP_VERSION__ (footer, PostHog app_version, source-map release) is a Vite define assembled at build time in vite.config.ts:

<package.json version>+<UTC build stamp>.<short sha>
0.0.0-alpha+20260906.0441.8ab5478

The stamp orders builds and the sha pins one. Railway exposes RAILWAY_GIT_COMMIT_SHA, GitLab exposes CI_COMMIT_SHA, and a local build falls back to git rev-parse. Nothing bumps package.json automatically; change its version by hand when the release line moves:

npm version preminor --preid=beta --no-git-tag-version  # → 0.1.0-beta.0
npm version minor --no-git-tag-version                   # → 0.1.0

Development Notes

• Discord is the primary sign-in path.
• GitHub linking and GitHub contribution calendar rendering are implemented.
• itch.io linking exists and is token/client-ID based in the current implementation.
• Public profile links prefer linked provider URLs over manual URLs when available.
• OAuth-backed GitHub and itch.io links now render verified badges in the public profile UI.
• src/routes/demo/* still contains scaffold/demo routes and should not be treated as product truth.

Database Notes

The schema currently spans:

• auth
• user
• hammer
• collab
• public todos

Profile data still uses separate profile_projects and jam_participations tables. The unified typed-projects migration has not landed yet.

Validation Notes

• bun run check runs Biome across the repo.
• bun run test uses Vitest.
• First-party automated coverage appears limited at the moment, so UI and route changes still need manual verification.

Working Conventions

• Prefer reading the code over assuming the starter framework defaults still apply.
• Treat Notion as the longer-lived cross-session source of truth for architecture, drift, and planning context.
• Keep Linear issue status aligned with what actually shipped in the repo.

Known Gaps

• The repo still needs a fuller setup/runbook for external services and credential provisioning.
• Demo routes remain in-tree.
• The route tree currently has at least one existing TypeScript issue outside normal profile work (src/routes/profile.$userId.tsx), so isolated validation is sometimes more useful than full repo typechecking.