Include this file in your AI coding assistant's context (Cursor rules, Copilot instructions, Claude projects, etc.)

Project Context

You are working on TendSocial (or a related project using the same stack). Your role is to implement the intent of requirements, not blindly follow outdated implementation details.

When requirements conflict with current library versions, STOP and clarify before implementing.

---

Critical Version Requirements

Node.js:    >= 20.19
TypeScript: >= 5.4
Prisma:     7.x (ESM-only, no middleware, uses driver adapters)
Fastify:    5.x

- NO `any` or `unknown` allowed (use explicit types)
- ALL API schemas must be strict Zod objects (no `z.record(z.unknown())`)
- Helper functions `isError()` and `getErrorMessage()` MUST be used in catch blocks
- Use `@tendsocial/shared-types` for ALL common entities (BrandProfile, AppSettings, etc.)
- AVOID manual mapping code; use shared schemas to validate JSON directly from the DB

---

Known Breaking Changes (MEMORIZE THESE)

Prisma: $use() middleware DOES NOT EXIST

Removed in v6.14. The API simply does not exist in v7.

If ANY requirement mentions:

• "Prisma middleware"
• prisma.$use()
• params and next in query interceptors

STOP and respond:

The requirement references Prisma middleware (`$use`), which was removed 
in Prisma v6.14. This project uses Prisma v7.

The modern equivalent is Client Extensions using `$extends()`.

Should I implement using Client Extensions instead?

Correct pattern:

const prisma = new PrismaClient().$extends({
  query: {
    $allModels: {
      async $allOperations({ args, query }) {
        // Your logic here
        return query(args)
      }
    }
  }
})

Prisma v7: ESM & Driver Adapters Required

• "type": "module" in package.json (mandatory)
• Import syntax only, no require()
• Driver adapter required:

import { PrismaClient } from './generated/prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
export const prisma = new PrismaClient({ adapter })

Fastify v5

• Object syntax for listen(): fastify.listen({ port: 3000, host: '0.0.0.0' })
• Check docs for any v4 patterns you might recognize

---

Multi-Tenant Data Isolation (If Applicable)

If the app serves multiple organizations/companies, all tenant-specific data MUST be isolated.

Implementation: Prisma Client Extensions (NOT middleware)

// Create tenant-scoped client
export const createTenantClient = (tenantId: string) => {
  return new PrismaClient().$extends({
    query: {
      // Apply to tenant-scoped models
      someModel: {
        async findMany({ args, query }) {
          args.where = { ...args.where, tenantId }
          return query(args)
        },
        // ... other operations
      }
    }
  })
}

The tenant identifier comes from the authenticated user's JWT payload.

---

Pre-Code Checklist

Before implementing ANY feature:

1. [ ] What library versions does this touch?
2. [ ] Are the patterns in the requirements current for those versions?
3. [ ] If unsure, check official documentation
4. [ ] If conflict found, STOP and ask

---

Response Protocol When Conflicts Detected

Use this format:

🚨 REQUIREMENT USES DEPRECATED PATTERN

The requirement asks for: [quoted requirement]

This uses [deprecated feature] which was removed/changed in [library] v[X].

Current approach in v[Y]:
[Brief explanation + code snippet]

Options:
1. Implement using current pattern (recommended)
2. Discuss alternative approaches

Which would you prefer?

---

Environment & Connections

Service	Purpose	Env Var
Neon	PostgreSQL	DATABASE_URL
Cloud Run	Backend	PORT (auto-set)
Supabase	Auth	SUPABASE_URL, SUPABASE_ANON_KEY
Cloudflare R2	Storage	R2_ENDPOINT, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY
AI APIs	LLM	Encrypted keys, master key in Secret Manager
Sentry	Monitoring	SENTRY_DSN

---

You Have Permission To Push Back

If a human (or their requirements doc) asks you to:

• Use deprecated APIs
• Implement patterns that don't exist in current versions
• Skip proper tenant isolation
• Use CommonJS in this ESM project

You are expected to challenge this. The team wants correct implementations, not blind compliance with outdated specs.

---

Testing Conventions

For test organization, file naming, and what tests may/may not do, see:

• Testing Conventions - Master testing guide

Key rules:

• Unit tests: Co-located with source (src/components/Button.test.tsx)
• Integration tests: Centralized in test/integration/
• E2E tests: Centralized in test/e2e/

---

Context version: 2026-01 (Shared Types Update)