---
description: Meshkee CMS API project context and architecture essentials
alwaysApply: true
---

# Meshkee CMS API

Read `docs/PROJECT_CONTEXT.md` for full reference before large changes.

## Stack

NestJS 11 + TypeScript + Prisma 6 + PostgreSQL 16 + Redis + S3 (Parspack).

API prefix: `/api/v1`. Package name: `meshkee-cms-api`.

## Architecture

- Multi-tenant: `Business` is the tenant root; routes are `businesses/:businessId/...`
- **Content Category** (`categories`) ≠ **Business Category** (`business_categories`) — do not confuse them
- **Location Cities** (`cities`) — system reference tree (country → province → city) for address forms; not business-scoped. Distinct from **Addresses** (`addresses`) which store user/business street addresses
- Blogs + portfolios have Prisma models and CMS modules (`blogs/`, `portfolios/`)
- Branding JSON includes `defaultLocale` (`fa` \| `en`, default `fa`) for dashboard language
- Dashboard activity charts: `GET businesses/:id/orders/activity` and `.../customers/activity` (dual daily series, not website-facing)

## Schema changes

1. Add SQL file in `database/migrations/`
2. Apply via `./database/migrate.sh`
3. Run `npm run prisma:pull` then `npm run prisma:generate`

Do **not** use Prisma Migrate. SQL migrations are authoritative.

## Scope discipline

- Minimize diff scope; match existing module patterns
- Reuse existing services/guards instead of reimplementing
- No commits unless explicitly requested
- **Production deploy:** push to git first, then pull/build on the API VM — see `.cursor/rules/git-deploy.mdc` (never rsync as the normal path)
- **Website API docs:** when storefront APIs change, update `docs/website-api/` + `src/website-docs/static/` — see `.cursor/rules/website-api-docs.mdc`
- **Clients:** websites always use remote API; dashboards use local API in dev and remote after deploy — coordinate dashboard releases with backend — see `.cursor/rules/env-clients-deploy.mdc`