# System Architecture & Invariants: Prisma ORM & PostgreSQL Schema Architecture

## 1. System Overview
Production guidelines for Prisma ORM. Enforces selective field fetching, batch transactions, explicit indexing, and singleton client patterns.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: Node.js / Next.js / TypeScript
- **Language Standard**: TypeScript
- **UI & Styling**: None
- **Data Persistence**: PostgreSQL / Prisma
- **Engineering Philosophy**: strict

## 2. Core Architectural Invariants
- **Guard Clauses & Early Returns**: Exit early from functions to eliminate deeply nested if-else pyramids.
- **Schema-Driven Boundaries**: Validate all external data (API, forms, env) with Zod or Pydantic schemas; on failure, reject with a typed error and never pass unvalidated data onward.
- **Clean Layered Architecture**: Decouple presentation, business logic, and data access layers via interfaces.

## 3. Data Flow & State Management Principles
1. **Unidirectional Data Flow**: State flows top-down; mutations flow through explicit, typed handlers.
2. **Boundary Validation**: External inputs (API payloads, query parameters, environment variables) must be parsed with strict schemas before reaching domain logic.
3. **Surgical Precision**: Diffs must remain minimal and scoped exclusively to the objective. Do not reformat unrelated code.

## 4. Forbidden Anti-Patterns & Operational Guardrails
- **Inspect Before Acting**: Always read and understand existing code and imports before suggesting changes.
- **Minimal Surgical Diffs**: Touch only lines relevant to prompt. Preserve existing comments and formatting.
- **Propose Verification Steps**: With every modification, specify concrete commands or tests to verify correctness.

## 5. Domain-Specific Invariants
- Never return raw hashed passwords or internal auth tokens from Prisma queries.
- Prefer Prisma raw queries ($queryRaw) only when complex SQL window functions are required.

## 6. Implementation Reference Patterns

### Preferred Pattern
```typescript
// Good: Targeted field selection avoiding memory bloat
const users = await db.user.findMany({
  where: { active: true },
  select: { id: true, email: true, name: true }
});
```

### Forbidden Anti-Pattern
```typescript
// Discouraged: Over-fetching entire table graph into memory
const users = await db.user.findMany({
  include: { posts: true, logs: true, auditHistory: true }
});
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Always use 'select' to fetch only necessary columns; ban broad unconstrained findMany() queries.
2. Encapsulate dependent multi-model operations inside prisma.$transaction().
3. Add @@index for columns used frequently in WHERE clauses or foreign key joins.
4. Maintain a singleton PrismaClient instance to prevent connection pool exhaustion.