Skip to content

Conventions

Team-wide rules for Git, database management, API development, and coding standards across all SMACKZ repositories.

Git & Branching

Rule Details
All commits go to qa only Never commit directly to main, staging, or production. Exception: Yum-Ensemble-Apps uses main.
Never skip pre-commit hooks Do not use --no-verify or --no-gpg-sign. Fix the underlying issue instead.
"Commit" means commit + push Always push after committing unless explicitly told otherwise.
Never commit package-lock.json These are generated at build time for the target platform.
Run review agents before commit Run code-reviewer and silent-failure-hunter before every commit.
No compile or lint errors Run npx tsc --noEmit and npm run lint before committing. Fix all errors from your changes.

Yum Pre-commit Coverage Gate

The yum repo enforces a coverage gate on every commit: .husky/pre-commit runs lint:check → ts.check → build → precommit-coverage-gate.js. The gate requires 100% coverage on staged source files (lines / branches / functions / statements) measured against the unit suite only. It resolves related tests via Jest's static graph plus a filename convention (api/<dir>/<name>.ts → test/unit/<dir>/<name>*.test.ts) and runs them with testcontainers disabled. See yum/docs/PRECOMMIT_COVERAGE.md.

Database

Rule Details
Never run migration commands Do not run db:push, drizzle-kit push, or drizzle-kit generate. Prompt the developer to run these manually.
JSONB for page/section properties Adding display properties never requires migrations. Update TypeScript types, Zod schemas, and DISPLAY_PROPERTY_KEYS_TYPED.
Local dev uses local PostgreSQL Use the smackz_postgres Docker container. Never connect to Neon/cloud databases locally.
Schema changes via Drizzle models Modify TypeScript models in api/db/models/, then npm run db:push. Never write manual SQL ALTER TABLE.
Never instantiate repos at module scope The db instance is initialized asynchronously. Instantiate repositories inside methods or constructors, not at the top level.

API Development

Rule Details
Use Yum API for all mutations Never use raw SQL for pages/sections. Use REST endpoints that handle validation and consistency.
Always add Swagger docs Use .describe() on all Zod schema fields when adding or updating endpoints.
Cloud URL routing Cloud: /apis/api/v1/... (API gateway prefix). Local: /api/v1/... directly.
Every display property needs admin UI No property should be API-only. Users must be able to edit everything in Smackz-Admin.
JSONB + Zod alignment For .nullable() fields in response schemas, ensure the DB layer guarantees the key exists as null (not undefined).

Feature Implementation Checklist

When adding or modifying any feature, verify all 9 layers:

  1. Database Layer -- Drizzle model updated
  2. Schema Layer -- Request + response Zod schemas
  3. Repository Layer -- CRUD methods
  4. Service Layer -- Business logic, error handling
  5. Controller Layer -- Request/response handling
  6. API Endpoints -- POST, PUT, GET, DELETE, PATCH
  7. Related Entities -- Cart, orders, search, export
  8. Build & Test -- Type check, build, manual testing, Swagger
  9. Documentation -- CLAUDE.md, README, code comments

Export/Import

When any model, API, or database change touches entities covered by export/import (restaurant, pages, menu, users, orders), flag that corresponding changes are needed in the export/import services:

  • yum/api/services/menuExportImport.ts
  • yum/api/services/restaurantExportImport.ts
  • yum/api/services/userExportImport.ts
  • yum/api/services/orderExportImport.ts
  • yum/api/services/unifiedExport.ts

Infrastructure

Rule Details
Local dev via Docker Compose Use docker compose to restart/rebuild after changes.
Shared GVC The smackz GVC is managed by Yum's deployment. Do not create duplicate GVC configs.
Never deploy to prod without asking Only work on production when explicitly requested.
Confirm destructive DB operations For DELETE/DROP on Neon, show the SELECT first and confirm project/branch.

Key Patterns

Pattern Reference
Drizzle pgEnum yum/api/db/models/restaurantFirebaseApps.ts
Zod enum yum/api/schema/restaurant.ts (deliveryProviderEnum)
SelectFormInput dropdown Smackz-Admin/.../DeliveryStep.tsx
Radio card UI Smackz-Admin/.../register-form.tsx
Drizzle config yum/drizzle.config.ts

Key Files

  • CLAUDE.md -- Source of truth for all conventions
  • yum/CLAUDE.md -- Backend-specific guidelines
  • yum/docs/FEATURE_CHECKLIST.md -- 9-point checklist with examples
  • yum/docs/OPERATIONAL_GUIDELINES.md -- Operational safety rules