@levironexe/architect 0.1.0

package/skills/patterns/prisma.skill.yaml

@@ -0,0 +1,255 @@
+schema_version: "2.0.0"
+id: prisma
+name: "Prisma ORM"
+version: "2.0.0"
+description: "Schema-first Prisma ORM with singleton client, repository/model pattern, migration-only schema changes, error handling for known request errors, and N+1 prevention via include/select."
+category: pattern
+language: javascript
+frameworks:
+  - prisma
+dependencies:
+  none:
+    - drizzle-orm
+    - mongoose
+    - sequelize
+detection:
+  dependencies:
+    any:
+      - prisma
+      - "@prisma/client"
+  source_indicators:
+    - "PrismaClient"
+    - "prisma.$"
+    - "from '@prisma/client'"
+    - "prisma.user."
+    - "prisma.post."
+structure:
+  required_dirs:
+    - path: prisma
+      purpose: "Prisma schema file (schema.prisma) and migration history. The only place where the database schema is defined — all table structure, relations, and enums live here. Any schema change must go through `npx prisma migrate dev` to generate a migration file and update the generated Prisma Client."
+    - path: prisma/migrations
+      purpose: "Auto-generated migration SQL files created by `npx prisma migrate dev`. Never edit these files manually — Prisma tracks their checksums and will refuse to apply migrations if they are modified after generation."
+    - path: src/lib
+      purpose: "Prisma Client singleton in db.ts — the one and only place that calls `new PrismaClient()`. All repositories and services import the prisma instance from here. Prevents connection pool exhaustion in serverless environments where each cold start could otherwise create a new pool."
+  recommended_dirs:
+    - path: src/repositories
+      purpose: "Data access layer — one file per Prisma model (e.g., user.repository.ts). All prisma.user.*(), prisma.post.*() calls belong here. Services call repository functions; they never import prisma directly. This makes the data layer mockable in unit tests."
+    - path: src/services
+      purpose: "Business logic layer — orchestrates calls to one or more repositories, validates input, applies rules, and returns domain objects. Never calls prisma directly."
+separation:
+  rules:
+    - concern: singleton_client
+      belongs_in: src/lib
+      rule_text: "Create exactly one PrismaClient instance using the global singleton pattern in src/lib/db.ts. In serverless/Next.js environments, Hot Module Replacement recreates modules on every file save — without the global pattern, each save creates a new PrismaClient and a new connection pool until connections are exhausted."
+      example: |
+        // src/lib/db.ts — the only file that calls new PrismaClient()
+        import { PrismaClient } from '@prisma/client';
+
+        const globalForPrisma = globalThis as unknown as {
+          prisma: PrismaClient | undefined;
+        };
+
+        export const prisma =
+          globalForPrisma.prisma ??
+          new PrismaClient({
+            log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
+          });
+
+        if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+      anti_indicators:
+        - "new PrismaClient()"
+    - concern: migrations
+      belongs_in: prisma/migrations
+      rule_text: "All schema changes must go through the Prisma migration system. Use `npx prisma migrate dev --name description` in development and `npx prisma migrate deploy` in production CI/CD. Never run raw `ALTER TABLE` or `CREATE TABLE` SQL manually — it breaks migration history and Prisma Client type generation."
+      example: |
+        # Development: creates migration file + applies it + regenerates Prisma Client
+        npx prisma migrate dev --name add-phone-to-users
+
+        # Production CI/CD: applies pending migrations without interactive prompts
+        npx prisma migrate deploy
+
+        # After pulling schema changes: regenerate Prisma Client types locally
+        npx prisma generate
+      indicators:
+        - "prisma migrate dev"
+        - "prisma migrate deploy"
+        - "prisma generate"
+    - concern: data_access
+      belongs_in: src/repositories
+      rule_text: "Prisma queries live in src/repositories/ or src/models/. Services and API routes call repository functions — they never import prisma directly. Repository functions own the select/include shape of queries, handle errors, and return typed domain objects."
+      example: |
+        // src/repositories/user.repository.ts
+        import { prisma } from '@/lib/db';
+        import type { Prisma } from '@prisma/client';
+
+        export async function findUserById(id: string) {
+          return prisma.user.findUnique({
+            where: { id },
+            select: { id: true, email: true, name: true, createdAt: true },
+            // Exclude: password hash, internal fields
+          });
+        }
+
+        export async function createUser(data: Prisma.UserCreateInput) {
+          return prisma.user.create({ data });
+        }
+
+        export async function listUsersWithPosts(limit = 20) {
+          return prisma.user.findMany({
+            take: limit,
+            include: { posts: { take: 5, orderBy: { createdAt: 'desc' } } },
+            orderBy: { createdAt: 'desc' },
+          });
+        }
+      indicators:
+        - "prisma.user."
+        - "prisma.post."
+        - ".findMany("
+        - ".findUnique("
+        - "from '@/lib/db'"
+    - concern: transactions
+      belongs_in: src/repositories
+      rule_text: "Use prisma.$transaction() for operations that must succeed or fail together. Interactive transactions (callback form) support dependent queries where the second query uses the result of the first. Batch transactions (array form) are faster for independent mutations."
+      example: |
+        // src/repositories/order.repository.ts
+        export async function createOrderWithInventoryUpdate(
+          userId: string,
+          productId: string,
+          quantity: number
+        ) {
+          return prisma.$transaction(async (tx) => {
+            // Check and decrement inventory atomically
+            const product = await tx.product.update({
+              where: { id: productId, stock: { gte: quantity } },
+              data: { stock: { decrement: quantity } },
+            });
+
+            // Create the order using updated product data
+            return tx.order.create({
+              data: { userId, productId, quantity, total: product.price * quantity },
+            });
+          });
+        }
+      indicators:
+        - "prisma.$transaction"
+        - "$transaction("
+patterns:
+  data_flow:
+    direction: "API Route/Server Action → Service → Repository → Prisma Client → Database"
+    rules:
+      - "API routes and Server Actions call service functions only — never prisma directly."
+      - "Services contain business logic and call repository functions — never prisma directly."
+      - "Repositories are the only files that import prisma from src/lib/db.ts."
+      - "Migrations run via `prisma migrate` — never raw SQL."
+      - "Prisma Client types are regenerated after every schema change with `prisma generate`."
+      - "For N+1 prevention: use include/select in repositories rather than loading relations in loops."
+  error_handling:
+    recommended: "Catch PrismaClientKnownRequestError in repositories. P2002 = unique constraint violation (duplicate email), P2025 = record not found (delete/update of non-existent row), P2003 = foreign key constraint violation."
+  naming:
+    schema: "prisma/schema.prisma — single data model source of truth"
+    client: "src/lib/db.ts — exports the prisma singleton"
+    repositories: "src/repositories/[model].repository.ts — e.g. user.repository.ts, post.repository.ts"
+    models: "src/models/[model].model.ts — domain model classes wrapping repository calls"
+anti_patterns:
+  - id: multiple_prisma_clients
+    severity: critical
+    description: "Calling `new PrismaClient()` in multiple files instead of importing the singleton. Each PrismaClient creates its own connection pool. In serverless environments (Vercel, Lambda), each function invocation can create a new pool — leading to database 'too many connections' errors under moderate traffic."
+    bad_example: |
+      // ❌ New PrismaClient in every file — separate connection pool per module
+      // src/repositories/user.repository.ts
+      import { PrismaClient } from '@prisma/client';
+      const prisma = new PrismaClient(); // pool #1
+
+      // src/repositories/post.repository.ts
+      import { PrismaClient } from '@prisma/client';
+      const prisma = new PrismaClient(); // pool #2 — now two pools competing
+    good_example: |
+      // ✓ Import the singleton everywhere — one pool for the entire process
+      // src/lib/db.ts: export const prisma = globalThis.prisma ?? new PrismaClient();
+      import { prisma } from '@/lib/db';
+  - id: prisma_in_route_handler
+    severity: critical
+    description: "Calling prisma directly in API route handlers, Server Actions, or React components. This bypasses the service/repository layer, makes the code untestable (can't mock prisma calls in unit tests), and scatters query logic across the codebase."
+    bad_example: |
+      // ❌ Direct prisma call in API route — no service layer, untestable
+      import { prisma } from '@/lib/db';
+      export async function GET() {
+        const users = await prisma.user.findMany({
+          include: { posts: true },
+        });
+        return Response.json(users);
+      }
+    good_example: |
+      // ✓ API route calls service, service calls repository
+      import { userService } from '@/services/user.service';
+      export async function GET() {
+        const users = await userService.listUsersWithPosts();
+        return Response.json(users);
+      }
+      // src/services/user.service.ts calls userRepository.listWithPosts()
+      // src/repositories/user.repository.ts calls prisma.user.findMany(...)
+  - id: manual_sql_migration
+    severity: warning
+    description: "Modifying the database schema with raw SQL (ALTER TABLE, CREATE TABLE) instead of Prisma's migration system. The migration history becomes out of sync with the schema.prisma file — `prisma migrate deploy` in production applies migrations that have already been applied or skips needed ones."
+    bad_example: |
+      -- ❌ Manual SQL bypasses Prisma migration tracking
+      -- Run directly in DB console:
+      ALTER TABLE users ADD COLUMN phone VARCHAR(20);
+      -- schema.prisma still has no phone field — Prisma Client has no phone type
+    good_example: |
+      // ✓ 1. Add field in schema.prisma
+      // model User { phone String? }
+      // 2. Generate + apply migration:
+      // npx prisma migrate dev --name add-phone-to-users
+      // 3. Prisma Client regenerated automatically — phone field is now typed
+  - id: n_plus_one_query
+    severity: warning
+    description: "Loading a list of records and then fetching their relations in a loop — creates N+1 database queries (1 for the list + N for each record's relations). Use Prisma's include or nested select to fetch everything in a single query."
+    bad_example: |
+      // ❌ N+1: 1 query for posts + 1 query per post for the author
+      const posts = await prisma.post.findMany(); // query 1
+      for (const post of posts) {
+        post.author = await prisma.user.findUnique({ where: { id: post.userId } }); // N queries
+      }
+    good_example: |
+      // ✓ Single query: posts JOIN users via include
+      const posts = await prisma.post.findMany({
+        include: { author: { select: { id: true, name: true, email: true } } },
+      });
+  - id: unhandled_known_request_error
+    severity: warning
+    description: "Not catching PrismaClientKnownRequestError — unique constraint violations (P2002) and not-found errors (P2025) crash with an unhandled error instead of returning a user-friendly message. These errors are predictable and must be handled explicitly."
+    bad_example: |
+      // ❌ Unique constraint crash surfaces as a 500 Internal Server Error
+      export async function createUser(email: string) {
+        return prisma.user.create({ data: { email } });
+        // If email already exists: Unhandled PrismaClientKnownRequestError P2002
+      }
+    good_example: |
+      // ✓ Catch known errors and return domain-appropriate responses
+      import { Prisma } from '@prisma/client';
+      export async function createUser(email: string) {
+        try {
+          return await prisma.user.create({ data: { email } });
+        } catch (e) {
+          if (e instanceof Prisma.PrismaClientKnownRequestError) {
+            if (e.code === 'P2002') throw new Error('Email already in use');
+          }
+          throw e;
+        }
+      }
+  - id: select_star_in_production
+    severity: warning
+    description: "Using findMany() or findUnique() without a select clause — fetches all columns including password hashes, internal flags, and large text fields. Always specify exactly what fields you need, especially in API responses."
+    bad_example: |
+      // ❌ Returns all fields including passwordHash, internalFlags, etc.
+      export async function GET() {
+        const users = await prisma.user.findMany(); // returns passwordHash!
+        return Response.json(users);
+      }
+    good_example: |
+      // ✓ Explicit select — only the fields the client needs
+      const users = await prisma.user.findMany({
+        select: { id: true, email: true, name: true, createdAt: true },
+        // passwordHash, internalFlags, etc. never leave the DB layer
+      });

package/skills/patterns/s3-storage.skill.yaml

@@ -0,0 +1,235 @@
+schema_version: "2.0.0"
+id: s3-storage
+name: "AWS S3 / R2 Storage"
+version: "2.0.0"
+description: "Object storage with pre-signed URLs for direct browser uploads, key-based DB references, server-side S3 client singleton, file type validation before signing, and secure download URLs."
+category: pattern
+language: javascript
+frameworks: []
+dependencies:
+  none: []
+detection:
+  dependencies:
+    any:
+      - "@aws-sdk/client-s3"
+      - "@aws-sdk/s3-request-presigner"
+  source_indicators:
+    - "S3Client"
+    - "PutObjectCommand"
+    - "getSignedUrl"
+    - "from '@aws-sdk/client-s3'"
+    - "s3-request-presigner"
+structure:
+  required_dirs: []
+  recommended_dirs:
+    - path: src/lib
+      purpose: "S3 client singleton in s3.ts — the only file that calls `new S3Client()`. Reads credentials from environment variables (or IAM role when deployed on EC2/ECS). Imported by the upload service only — never by route handlers or components directly."
+    - path: src/services
+      purpose: "Upload and download service logic in upload.service.ts — createUploadUrl() generates a pre-signed PUT URL, createDownloadUrl() generates a pre-signed GET URL. Validates allowed MIME types before generating the URL to prevent arbitrary file uploads."
+separation:
+  rules:
+    - concern: presigned_urls
+      belongs_in: src/services
+      rule_text: "Never proxy file bytes through your server. The upload flow is: (1) client calls your API to request a pre-signed PUT URL, (2) client uploads directly to S3 using that URL, (3) client notifies your API with the S3 key after upload completes. Server memory is never touched by file bytes."
+      example: |
+        // src/services/upload.service.ts
+        import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+        import { PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
+        import { s3 } from '@/lib/s3';
+        import { randomUUID } from 'crypto';
+
+        const ALLOWED_MIME_TYPES = ['image/jpeg', 'image/png', 'image/webp', 'image/gif'];
+
+        export async function createUploadUrl(originalFilename: string, contentType: string) {
+          // Validate MIME type server-side before signing
+          if (!ALLOWED_MIME_TYPES.includes(contentType)) {
+            throw new Error(`File type ${contentType} is not allowed`);
+          }
+          // Randomize key to prevent path traversal and name collisions
+          const ext = originalFilename.split('.').pop();
+          const key = `uploads/${randomUUID()}.${ext}`;
+          const url = await getSignedUrl(
+            s3,
+            new PutObjectCommand({
+              Bucket: process.env.S3_BUCKET!,
+              Key: key,
+              ContentType: contentType, // required: browser upload rejects 403 without this
+            }),
+            { expiresIn: 300 } // 5 minutes — enough for large files, short enough to limit misuse
+          );
+          return { url, key };
+        }
+
+        export async function createDownloadUrl(key: string) {
+          return getSignedUrl(
+            s3,
+            new GetObjectCommand({ Bucket: process.env.S3_BUCKET!, Key: key }),
+            { expiresIn: 3600 } // 1 hour
+          );
+        }
+      indicators:
+        - "getSignedUrl"
+        - "PutObjectCommand"
+        - "expiresIn"
+    - concern: key_storage
+      belongs_in: src/models
+      rule_text: "Store the S3 object key (e.g. `uploads/abc123.jpg`) in your database — NOT the full S3 URL. Generate signed download URLs on-demand when serving the file to clients. This allows bucket migration, CDN changes, and URL policy changes without data migrations."
+      example: |
+        // ✓ Store key in DB — not the full URL
+        await db.user.update({
+          where: { id: userId },
+          data: { avatarKey: 'uploads/abc123-abc.jpg' }, // key only
+        });
+
+        // ✓ Generate download URL on-demand in an API response
+        const user = await db.user.findUnique({ where: { id: userId } });
+        const avatarUrl = user.avatarKey
+          ? await createDownloadUrl(user.avatarKey)
+          : null;
+        return { ...user, avatarUrl }; // URL expires — never cached in DB
+      indicators:
+        - "avatarKey"
+        - "fileKey"
+        - "imageKey"
+        - "objectKey"
+    - concern: client_singleton
+      belongs_in: src/lib
+      rule_text: "Create the S3 client as a module-level singleton in src/lib/s3.ts. Never call `new S3Client()` outside this file. Credentials must come from environment variables or an IAM instance role — never hardcoded."
+      example: |
+        // src/lib/s3.ts
+        import { S3Client } from '@aws-sdk/client-s3';
+
+        // Singleton: AWS SDK reuses HTTP connections for performance
+        export const s3 = new S3Client({
+          region: process.env.AWS_REGION ?? 'us-east-1',
+          // No credentials field: uses AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY env vars
+          // or IAM instance role automatically
+        });
+      anti_indicators:
+        - "new S3Client({"
+    - concern: upload_confirmation
+      belongs_in: src/api
+      rule_text: "After the client uploads directly to S3, it must call your API with the key to confirm the upload. Your API then validates that the key actually exists in S3 before storing it in the database. Without confirmation, an attacker can store arbitrary S3 keys pointing to non-existent or malicious objects."
+      example: |
+        // app/api/upload/confirm/route.ts
+        import { HeadObjectCommand } from '@aws-sdk/client-s3';
+        import { s3 } from '@/lib/s3';
+
+        export async function POST(req: Request) {
+          const { key } = await req.json();
+          // Validate that the object actually exists in S3 before saving key to DB
+          await s3.send(new HeadObjectCommand({ Bucket: process.env.S3_BUCKET!, Key: key }));
+          // Only now save to DB
+          await db.user.update({ where: { id: userId }, data: { avatarKey: key } });
+          return Response.json({ success: true });
+        }
+      indicators:
+        - "HeadObjectCommand"
+        - "confirm"
+patterns:
+  data_flow:
+    direction: "Client → POST /upload/presign (server validates MIME) → S3 pre-signed PUT URL → Client uploads directly to S3 → Client POST /upload/confirm → Server verifies object exists → DB stores key"
+    rules:
+      - "File bytes never touch your server — client uploads directly to S3."
+      - "Validate MIME type in createUploadUrl() before generating the signed URL."
+      - "Store S3 object keys in DB — generate signed download URLs on-demand."
+      - "Confirm uploads server-side with HeadObjectCommand before persisting the key."
+      - "Set ContentType on PutObjectCommand — browsers reject pre-signed uploads without it."
+  error_handling:
+    recommended: "Catch NoSuchKey (S3ServiceException code NoSuchKey) when generating download URLs — return null or 404 if the object was deleted. Set maxFileSize on the client and validate server-side in the presign endpoint."
+  naming:
+    client: "src/lib/s3.ts — singleton S3Client; credentials from environment variables only"
+    upload_service: "src/services/upload.service.ts — createUploadUrl() and createDownloadUrl() live here"
+    key_pattern: "[folder]/[uuid].[ext] — e.g. uploads/a1b2c3d4-ef56-7890-abcd-ef1234567890.jpg"
+anti_patterns:
+  - id: proxy_upload
+    severity: warning
+    description: "Receiving uploaded files in your server and re-uploading to S3 — doubles bandwidth cost, risks memory exhaustion on large files, and adds significant latency. A 50 MB file received by your server means 100 MB of total bandwidth usage."
+    bad_example: |
+      // ❌ File received by server, then uploaded to S3
+      app.post('/upload', upload.single('file'), async (req, res) => {
+        await s3.send(new PutObjectCommand({
+          Body: req.file.buffer, // 50 MB in server RAM
+          Bucket: process.env.S3_BUCKET,
+          Key: `uploads/${req.file.originalname}`,
+        }));
+        res.json({ key: `uploads/${req.file.originalname}` });
+      });
+    good_example: |
+      // ✓ Server generates presigned URL — client uploads directly
+      app.post('/upload/presign', async (req, res) => {
+        const { url, key } = await createUploadUrl(req.body.filename, req.body.contentType);
+        res.json({ url, key }); // file never touches server
+      });
+  - id: store_full_url
+    severity: warning
+    description: "Storing full S3 URLs in the database — breaks when bucket, region, CDN domain, or URL signing policy changes. Migrating data is expensive; migrating a key column is trivial."
+    bad_example: |
+      // ❌ Full URL stored — breaks on bucket migration or CDN change
+      await db.user.update({
+        where: { id: userId },
+        data: { avatarUrl: 'https://my-bucket.s3.us-east-1.amazonaws.com/uploads/photo.jpg' },
+      });
+    good_example: |
+      // ✓ Store key only — generate signed URL on every read
+      await db.user.update({
+        where: { id: userId },
+        data: { avatarKey: 'uploads/abc123.jpg' },
+      });
+  - id: hardcoded_credentials
+    severity: critical
+    description: "Embedding AWS access keys directly in source code or committing them in .env files. Secrets in git history are permanent — even if removed in a later commit, they remain in git log and forks."
+    bad_example: |
+      // ❌ Hardcoded credentials — leaked in git history forever
+      new S3Client({
+        region: 'us-east-1',
+        credentials: {
+          accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
+          secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+        },
+      });
+    good_example: |
+      // ✓ AWS SDK reads credentials from environment automatically
+      // Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in .env (never committed)
+      // or use IAM role on EC2/ECS — no credentials needed in code
+      new S3Client({ region: process.env.AWS_REGION });
+  - id: missing_content_type_on_presign
+    severity: warning
+    description: "Generating a pre-signed PutObjectCommand without setting ContentType. S3 pre-signed URLs are signed against specific request parameters — if ContentType is in the signature but the browser upload omits or changes it, S3 returns a 403 Forbidden."
+    bad_example: |
+      // ❌ No ContentType — browser upload fails with 403
+      const url = await getSignedUrl(s3, new PutObjectCommand({
+        Bucket: process.env.S3_BUCKET,
+        Key: key,
+        // Missing: ContentType
+      }), { expiresIn: 300 });
+    good_example: |
+      // ✓ ContentType in the command matches what the browser will send
+      const url = await getSignedUrl(s3, new PutObjectCommand({
+        Bucket: process.env.S3_BUCKET,
+        Key: key,
+        ContentType: contentType, // e.g. 'image/jpeg'
+      }), { expiresIn: 300 });
+      // Client must set 'Content-Type': contentType header when PUT-ing to this URL
+  - id: no_file_type_validation
+    severity: critical
+    description: "Generating a pre-signed upload URL without validating the file's MIME type server-side. An attacker can request a signed URL for a .exe, .html (phishing), or .svg (XSS) file and upload it to your bucket — it will be served from your domain."
+    bad_example: |
+      // ❌ No MIME type validation — attacker uploads malware.exe to your S3 bucket
+      export async function POST(req: Request) {
+        const { filename, contentType } = await req.json();
+        // contentType can be anything the client sends
+        const url = await getSignedUrl(s3, new PutObjectCommand({
+          Bucket: process.env.S3_BUCKET, Key: `uploads/${filename}`, ContentType: contentType,
+        }), { expiresIn: 300 });
+        return Response.json({ url });
+      }
+    good_example: |
+      // ✓ Validate against allowlist before signing
+      const ALLOWED = new Set(['image/jpeg', 'image/png', 'image/webp', 'image/gif']);
+      export async function POST(req: Request) {
+        const { filename, contentType } = await req.json();
+        if (!ALLOWED.has(contentType)) return Response.json({ error: 'File type not allowed' }, { status: 400 });
+        const { url, key } = await createUploadUrl(filename, contentType);
+        return Response.json({ url, key });
+      }