Monorepo & apps

PlaylogiQ is a Turborepo monorepo managed with pnpm workspaces.

Layout

apps/
  web/        Operator dashboard (Next.js, App Router)
  player/     Player portal (Next.js, App Router)
  api/        Public REST API v1 (Next.js route handlers)
  docs/       Developer documentation (Nextra)
  worker/     BullMQ worker (derivation, lifecycle, segments, notifications, campaigns, journeys, webhooks, reports/exports, alerts, fraud/ML, tasks)

packages/
  ui/             Shared React components (shadcn base)
  db/             Supabase client + generated TS types + queries
  auth/           RBAC, API-key utilities, middleware
  gamification/   Rule engine, points, levels, missions
  crm-core/       Segmentation, lifecycle, scoring
  notifications/  Omnichannel notification engine
  analytics/      Metrics & KPI utilities
  bonus-engine/   Bonus types, wagering, eligibility
  integrations/   PAM mapping + event-normalization engine (shared by api & web)
  i18n/           Translations: EN, IT, ES
  sdk/            Public @playlogiq/sdk
  config/         Shared TS / ESLint / Tailwind configs

supabase/
  migrations/     Sequential SQL migrations (NNN_description.sql)
  tests/          SQL RLS/RBAC tests (run against a real Postgres)
  seed/           Dev seed data

infra/            Self-hosted deployment (Docker Compose, Caddy, migrate script)
docs/ADR/         Architecture Decision Records

Common commands

pnpm install            # install everything
pnpm dev                # run all apps
pnpm --filter @playlogiq/web dev   # run one app
pnpm build              # build all
pnpm lint               # eslint
pnpm typecheck          # tsc --noEmit across the workspace

Shared packages

Workspace packages are consumed as @playlogiq/<name> with workspace:*. They export TypeScript source directly (no build step) — the Next.js apps transpile them. This is why the shared config disables declaration output for apps (see Conventions).

The @playlogiq/integrations package holds the pure PAM mapping engine, so the ingestion API (apps/api) and the dashboard mapping tester (apps/web) run one identical implementation — see ADR-013.

Apps talk to Supabase

web / player use @supabase/ssr with cookie-based sessions and operate under RLS (the signed-in user’s scope).
api authenticates the caller’s API key, then uses a service-role admin client (RLS-bypassing) — so authorization is enforced explicitly in the route (auth → rate-limit → validation → scoped writes).

CI/CD

GitHub Actions runs lint → typecheck → build on every push to main/develop, and a separate workflow builds and pushes Docker images to GHCR. The self-hosted server pulls those images and applies new migrations. See infra/ and the project README.

Local development Database & RLS