Skip to main content

Repository & Workflow

Guardrails​

  • Monorepo managed by pnpm workspaces + Turborepo
  • Layout:
sokuho/
  apps/
    web/           # Next.js 16 App Router (frontend + API routes)
    functions/     # Firebase Cloud Functions (backend)
    docs/          # Docusaurus 3 documentation site
    cypress/       # Cypress E2E test suite
  packages/
    schema/        # @soku/schema — shared Zod schemas
    shared/        # @repo/shared — shared utilities
  .github/         # GitHub Actions workflows
  .claude/         # Claude Code agent/command configs
  .cursor/         # Cursor IDE rules
  turbo.json
  pnpm-workspace.yaml
  firebase.json
  firestore.rules
  storage.rules
  • GitHub Flow: short-lived branches from main → PR → merge to main. Merge strategy: merge commits. One review required.
  • Conventional Commits naming is expected (e.g., feat:, fix:, docs:, chore:). Commitlint is not enforced but encouraged.
  • Husky pre-commit hooks run lint/typecheck before commits.

LLM Notes​

  • Generate new code under apps/ (deployables) or packages/ (shared libs). Do not introduce new top-level folders without an ADR.
  • Use merge commits, not squash/rebase, in instructions or examples.
  • When adding a new integration, follow the existing pattern in apps/functions/integrations/.

Reference configs​

pnpm-workspace.yaml​

packages:
  - "apps/*"
  - "packages/*"

turbo.json​

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": { "outputs": [] },
    "typecheck": { "outputs": [] },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    }
  },
  "globalEnv": [
    "NEXT_PUBLIC_FIREBASE_API_KEY",
    "NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN",
    "NEXT_PUBLIC_FIREBASE_PROJECT_ID",
    "NEXT_PUBLIC_FIREBASE_APP_ID"
  ]
}

Root scripts​

{
  "scripts": {
    "dev": "turbo run dev --parallel",
    "build": "turbo run build",
    "test": "turbo run test --filter='!./apps/docs' -- --coverage --passWithNoTests",
    "lint": "turbo run lint",
    "typecheck": "turbo run typecheck",
    "check": "turbo run lint typecheck --filter='!./apps/docs' && pnpm -w test",
    "ci": "turbo run lint typecheck test build --filter='!./apps/docs'",
    "dev:web": "pnpm --filter web dev",
    "dev:functions": "pnpm --filter @repo/functions dev",
    "deploy:functions": "firebase deploy --only functions",
    "sync:schema": "pnpm --filter @soku/schema build && node scripts/sync-schema.js"
  }
}

Key decisions​

  • Node.js 22 for all apps (enforced in root engines field)
  • pnpm 9.12.2 (locked via packageManager field)
  • @soku/schema is the shared Zod schema package consumed by both apps/web and apps/functions
  • Functions receive @soku/schema via file reference ("@soku/schema": "file:.schema") after the sync:schema script copies the build output
  • The apps/docs package is excluded from test and ci scripts to avoid unnecessary builds