Synthex architecture pattern enforcer. NEVER suggest Redux, Zustand, tRPC, GraphQL, Server Actions for mutations, or any pattern absent from this codebase. NEVER allow cross-layer imports (page importing from lib/ directly). ALWAYS enforce: Pages → Components → Hooks → lib/ → Database. All mutations go through API routes. Activate on ANY request to design architecture, review patterns, plan a new system, refactor, or assess structural decisions.
Synthex architecture pattern enforcer. NEVER suggest Redux, Zustand, tRPC, GraphQL, Server Actions for mutations, or any pattern absent from this codebase. NEVER allow cross-layer imports (page importing from lib/ directly). ALWAYS enforce: Pages → Components → Hooks → lib/ → Database. All mutations go through API routes. Activate on ANY request to design architecture, review patterns, plan a new system, refactor, or assess structural decisions.
Enforces architectural patterns across the entire SYNTHEX codebase. Prevents
the pattern drift where each new coding session — human or AI — introduces
its own conventions, imports, and approaches instead of following established
patterns.
This is the difference between "vibe coding" and senior engineering:
a senior engineer knows the codebase conventions and follows them consistently.
This skill encodes those conventions as automated checks.
When to Use
Activate this skill when:
Reviewing a PR with changes across multiple files
After a bulk refactoring session
Running a periodic architecture health check
Onboarding to understand codebase conventions
Before a major release to ensure consistency
After AI-assisted coding sessions to verify pattern adherence
When NOT to Use
For individual API route security (use route-auditor)
For infrastructure security posture (use security-hardener)
For database schema patterns (use database-prisma)
For UI component design (use design)
Tech Stack Context
Framework: Next.js 15 App Router
Language: TypeScript 5.7 (strict mode)
Styling: Tailwind CSS with dark theme (bg-gray-950, cyan accents)
Icons: Barrel export from @/components/icons (lucide-react re-exports)
Rule: All icon imports must come from @/components/icons, never directly from lucide-react.
Why: The barrel export ensures consistent icon naming and allows future icon library changes.
Check:
Expected: 0 results (only components/icons.tsx imports from lucide-react).
Fix: Change import { Icon } from 'lucide-react' to import { Icon } from '@/components/icons'.
P4: Prisma Import Path
Rule: Always import Prisma from @/lib/prisma, never from @prisma/client directly.
Why: The centralised import configures logging, connection pooling, and error handling.
Check:
Expected: Only type imports (import { Prisma } from '@prisma/client' for types is acceptable).
Fix: Use import { prisma } from '@/lib/prisma' for the client instance.
P5: API Response Format
Rule: API routes return consistent JSON structure:
Success: { data: ... } or { ...data } with 200/201 status
Error: { error: 'message' } with appropriate 4xx/5xx status
Never: { message: ... }, { result: ... }, { success: true, ... }Check: Manual review — look for inconsistent response shapes in API routes.
P6: Dark Theme Tokens
Rule: Use Tailwind utility classes for theming. Avoid hardcoded hex colours.
Anti-patterns:bg-[#0f172a], text-[#06b6d4], border-[#1e293b]Preferred:bg-gray-950, text-cyan-400, border-gray-800, bg-[#0f172a]/80 (opacity variants are acceptable)
Check:
Note: Opacity variants like bg-[#0f172a]/80 are acceptable as Tailwind doesn't support opacity on arbitrary colours natively.
P7: Client Directive
Rule: Every React component that uses hooks (useState, useEffect, useRef, etc.) or browser APIs must have 'use client' as the first line.
Check:
# Find files using hooks without 'use client'
grep -rln "useState\|useEffect\|useRef\|useCallback\|useMemo\|useContext" components/ app/ --include="*.tsx" | xargs grep -L "'use client'"
Expected: 0 results.
P8: Fetch Credentials
Rule: All client-side fetch() calls must include credentials: 'include'.
Why: Without this, the httpOnly auth-token cookie is not sent, causing auth failures.
Check:
Rule: Routes that query data for the current user/organisation must use userId filtering or getEffectiveQueryFilter() from @/lib/multi-business/business-scope.
Why: Without org scoping, multi-business users could see data from wrong organisations.
Check: Manual review — look for Prisma queries in API routes that access user data without userId or organizationId in the where clause.
P10: Dead Code Detection
Rule: No unused imports, no unused variables, no large commented-out code blocks (>5 lines).
Check:
# Commented-out code blocks (crude but effective)
grep -rn "^[[:space:]]*//" app/ components/ lib/ --include="*.ts" --include="*.tsx" | head -50
Note: This check is best done by running ESLint with no-unused-vars and no-unused-imports.
Input Specification
Parameter
Type
Required
Description
target
string
no
Directory or file to check (default: entire project)
scope
string
no
Specific pattern IDs: P1,P3,P7 or all (default: all)
fix
boolean
no
Auto-fix safe patterns (P3, P4, P7) where possible
Report: "No TypeScript files found in specified directory"
Grep returns no matches
Report pattern as PASS
File permission error
Skip and report
Reference Files (Canonical Implementations)
lib/auth/jwt-utils.ts — Auth pattern (P1, P2)
components/icons.tsx — Icon barrel (P3)
lib/prisma.ts — Prisma client singleton (P4)
app/api/campaigns/route.ts — Reference API route (P5, P9)
middleware.ts — Security headers reference
Integration Points
Complements route-auditor (route-specific vs codebase-wide)
Complements security-hardener (architecture vs security)
Called by senior-reviewer agent for comprehensive reviews
Feeds into post-route-create hook for new route validation
Capability Uplift — Override Defaults
NEVER recommend architectural patterns not present in the Synthex codebase:
Redux, Zustand, tRPC, GraphQL, Server Actions for mutations, React Query.
Never allow cross-layer imports. Never suggest splitting the monorepo.
INSTEAD every architectural decision must:
Trace back to an existing pattern in the codebase (find it with Grep first)
Follow the layer rule: app/ pages → components/ → hooks/ → lib/ → Prisma → DB
Route all mutations through app/api/ routes with Zod validation
Use SWR for client-side data (never useEffect + fetch)
Keep auth in lib/auth/ — never duplicate auth logic in components
New patterns require: existing pattern was insufficient + migration path documented.
