Cartyx ⚔️

D&D Campaign Management Platform — organize sessions, manage players, and run your tabletop world.

Built with TanStack Start, React, and a retro pixel-art aesthetic.

Quick Start

git clone https://github.com/biozal/cartyx-app.git
cd cartyx-app
npm install
cp .env.example .env   # fill in credentials (see docs/deployment.md)
npm run dev            # http://localhost:3000

Features

• OAuth Authentication — Google, GitHub, Apple Sign-In (via JOSE/JWT)
• Campaign Management — Create, edit, and manage D&D campaigns
• Player Invites — Share invite codes for players to join
• Session Scheduling — Weekly/bi-weekly/monthly with timezone support
• Image Uploads — Campaign images stored on Cloudflare R2
• Access Control — GM and player roles with owner-only actions
• Product Analytics & Feature Flags — PostHog integration for usage insights and progressive feature rollouts

Tech Stack

Layer	Technology
Framework	TanStack Start (full-stack React)
UI	React 19 + Tailwind CSS v4
Routing	TanStack Router (file-based, type-safe)
Auth	Custom OAuth (Google, GitHub, Apple) via JOSE JWT
Database	MongoDB Atlas (Mongoose)
Image Storage	Cloudflare R2 (S3-compatible)
Dates	Day.js with timezone + relative time plugins
Analytics	PostHog (React SDK + Node SDK)
Build	Vite + Nitro
Testing	Vitest + React Testing Library
Linting	ESLint (flat config) + Prettier
Hosting	Vercel (serverless)
CDN	Cloudflare (DNS + R2 CDN)

Project Structure

All application code lives in app/:

app/
├── components/      # React components + Storybook stories
├── hooks/           # Custom React hooks (useAuth, useCampaigns)
├── routes/          # TanStack Router file-based routes
├── server/
│   ├── functions/   # Server functions (auth, campaigns, uploads)
│   ├── models/      # Mongoose models
│   └── utils/       # Server utilities (OAuth, PostHog, helpers)
├── styles/          # Global CSS (Tailwind)
├── utils/           # Client utilities (date, image compression)
├── client.tsx       # Client entry point
├── router.tsx       # TanStack Router config
└── ssr.tsx          # SSR entry point

tests/               # Vitest test files (mirrors app/ structure)
.storybook/          # Storybook configuration and mocks

Development

npm run dev            # Vite dev server with HMR
npm run build          # Production build
npm run typecheck      # TypeScript type checking
npm run lint           # ESLint check
npm run lint:fix       # Auto-fix lint issues
npm run format         # Prettier format
npm test               # Run tests
npm run test:watch     # TDD watch mode
npm run test:coverage  # Coverage report

Feature Flags

Client-side feature flags are available through app/utils/featureFlags.tsx, which wraps PostHog's React hooks with a small app-level API:

import { FeatureFlagGate, useFeatureFlag } from '~/utils/featureFlags'

function ExperimentalPanel() {
  const { isEnabled, isLoading, payload } = useFeatureFlag('experimental-panel')

  if (isLoading) return null
  if (!isEnabled) return null

  return <section>{JSON.stringify(payload)}</section>
}

function Page() {
  return (
    <FeatureFlagGate flag="experimental-panel" fallback={null}>
      <ExperimentalPanel />
    </FeatureFlagGate>
  )
}

Set VITE_PUBLIC_POSTHOG_KEY locally or in Vercel for client-side flag evaluation. User identification is synchronized through the shared PostHog provider so person-targeted flags refresh after sign-in/sign-out.

Component Library

The published Storybook is available at https://biozal.github.io/cartyx-app.

For contributor setup, story-writing patterns, interaction tests, and Storybook-specific project conventions, see docs/STORYBOOK.md.

Environments

Environment	URL	Branch	Database
Production	app.cartyx.io	main	MongoDB Atlas (prod)
Staging	dev.cartyx.io	dev	MongoDB Atlas (dev)
PR Preview	*.vercel.app	any PR branch	MongoDB Atlas (dev)
Local	localhost:3000	any	Local or Atlas dev

Branching Strategy

feature/my-feature → PR against dev → preview URL → merge to dev (staging)
                                                   → PR dev→main → production

• Feature branches target dev
• dev → dev.cartyx.io (stable staging)
• main → app.cartyx.io (production)
• Every PR gets an automatic Vercel preview URL

Deployment

See docs/deployment.md for complete setup instructions including:

• Vercel project configuration
• MongoDB Atlas setup
• OAuth provider setup (Google, GitHub, Apple)
• Cloudflare DNS and R2 image storage
• Environment variables reference

Contributing

See CONTRIBUTING.md for development standards, testing requirements, and PR checklist.

License

MIT — see LICENSE