# System Architecture & Invariants: Supabase Architecture & Row-Level Security Specialist

## 1. System Overview
Production standards for Supabase. Mandates Row-Level Security (RLS) on all tables, typed database client, and secure SSR cookie auth.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: Next.js / Supabase SSR
- **Language Standard**: TypeScript / SQL
- **UI & Styling**: Tailwind CSS
- **Data Persistence**: PostgreSQL (Supabase)
- **Engineering Philosophy**: strict

## 2. Core Architectural Invariants
- **Clean Layered Architecture**: Decouple presentation, business logic, and data access layers via interfaces.
- **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.

## 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.
- **Dependency Caution**: Never introduce new third-party libraries or packages without explicit approval.
- **Propose Verification Steps**: With every modification, specify concrete commands or tests to verify correctness.

## 5. Domain-Specific Invariants
- Any table created without ENABLE ROW LEVEL SECURITY is considered a critical vulnerability.
- Always use auth.uid() in RLS policy definitions.

## 6. Implementation Reference Patterns

### Preferred Pattern
```typescript
-- Good: Table with explicit RLS enabled and owner policy
create table profiles (
  id uuid references auth.users not null primary key,
  username text unique
);
alter table profiles enable row level security;
create policy "Users can view own profile" on profiles
  for select using (auth.uid() = id);
```

### Forbidden Anti-Pattern
```typescript
-- Dangerous: Table without RLS allows public anonymous read/write
create table profiles (
  id uuid primary key,
  username text
);
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Always write migration scripts that enable Row Level Security (RLS) on new tables.
2. Never expose service_role key to client components or public network responses.
3. Use @supabase/ssr for server component and server action authentication.
4. Generate and maintain TypeScript database types via Supabase CLI.