@levironexe/architect 0.1.0

package/skills/patterns/vitest-testing.skill.yaml

@@ -0,0 +1,262 @@
+schema_version: "2.0.0"
+id: vitest-testing
+name: "Vitest"
+version: "2.0.0"
+description: "Unit and integration testing with Vitest — native ESM, vi.mock() module replacement, coverage thresholds, async assertion patterns, and test behavior verification over implementation details."
+category: pattern
+language: javascript
+frameworks:
+  - vitest
+dependencies:
+  none:
+    - jest
+    - "@jest/globals"
+detection:
+  dependencies:
+    any:
+      - vitest
+  source_indicators:
+    - "from 'vitest'"
+    - "vi.fn("
+    - "vi.mock("
+    - "describe("
+    - "vi.spyOn("
+structure:
+  required_dirs:
+    - path: src/__tests__
+      purpose: "Unit tests co-located near source — mirrors the src/ structure. Test files are named [filename].test.ts where [filename] matches the source file they cover. E.g., src/services/user.service.ts → src/__tests__/services/user.service.test.ts. This makes it immediately obvious which tests cover which source file."
+  recommended_dirs:
+    - path: tests/integration
+      purpose: "Integration tests that span multiple modules or require a real database connection. Use a test database (test schema or separate DB) isolated from development data. Do not mock the database in integration tests — the point is to test the full stack together."
+    - path: tests/fixtures
+      purpose: "Shared test factories, mock data objects, and test utilities imported by multiple test files. Examples: createTestUser() factory for Prisma, mockHttpServer using MSW for API mocking, shared vitest setup files that configure global mocks."
+separation:
+  rules:
+    - concern: unit_test_location
+      belongs_in: src/__tests__
+      rule_text: "Unit tests live in src/__tests__/ and mirror the source structure. Test files are named [source-filename].test.ts. Each test file imports exactly the module it tests — not its entire dependency tree. The goal is to test the public API of each module in isolation."
+      example: |
+        // src/__tests__/services/user.service.test.ts
+        import { describe, it, expect, vi, beforeEach } from 'vitest';
+        import { UserService } from '@/services/user.service';
+
+        // Mock the repository — unit tests don't hit the database
+        vi.mock('@/repositories/user.repository', () => ({
+          findUserByEmail: vi.fn(),
+          createUser: vi.fn(),
+        }));
+
+        describe('UserService', () => {
+          beforeEach(() => vi.clearAllMocks());
+
+          it('should throw if email already exists', async () => {
+            const { findUserByEmail } = await import('@/repositories/user.repository');
+            vi.mocked(findUserByEmail).mockResolvedValue({ id: '1', email: 'a@b.com' } as any);
+            await expect(UserService.register('a@b.com', 'password')).rejects.toThrow('Email already in use');
+          });
+        });
+      indicators:
+        - ".test.ts"
+        - ".spec.ts"
+        - "vi.mock("
+    - concern: mocking
+      belongs_in: src/__tests__
+      rule_text: "Use vi.mock() to mock modules at module load time — call it at the top level (hoisted). Use vi.fn() for function mocks with mockReturnValue/mockResolvedValue to control behavior. Reset all mocks in beforeEach with vi.clearAllMocks() to prevent state leaking between tests."
+      example: |
+        import { describe, it, expect, vi, beforeEach } from 'vitest';
+        import { sendEmail } from '@/lib/email';
+        import { notifyUser } from '@/services/notification.service';
+
+        // vi.mock() is hoisted — runs before imports
+        vi.mock('@/lib/email', () => ({
+          sendEmail: vi.fn().mockResolvedValue({ messageId: 'test-123' }),
+        }));
+
+        describe('notifyUser', () => {
+          beforeEach(() => vi.clearAllMocks()); // reset call counts and return values
+
+          it('sends an email to the user', async () => {
+            await notifyUser('user@example.com', 'Welcome!');
+            expect(sendEmail).toHaveBeenCalledOnce();
+            expect(sendEmail).toHaveBeenCalledWith('user@example.com', expect.objectContaining({ subject: 'Welcome!' }));
+          });
+
+          it('does not send if user has opted out', async () => {
+            await notifyUser('optout@example.com', 'Welcome!', { optedOut: true });
+            expect(sendEmail).not.toHaveBeenCalled();
+          });
+        });
+      indicators:
+        - "vi.mock("
+        - "vi.fn("
+        - "vi.spyOn("
+    - concern: coverage
+      belongs_in: vitest.config.ts
+      rule_text: "Set coverage thresholds in vitest.config.ts to enforce minimum coverage. Use @vitest/coverage-v8 as the provider (faster, native). Include/exclude patterns control which files are measured. CI fails if thresholds are not met — protecting against coverage regression."
+      example: |
+        // vitest.config.ts
+        import { defineConfig } from 'vitest/config';
+        import path from 'path';
+
+        export default defineConfig({
+          test: {
+            globals: true,
+            environment: 'node',
+            setupFiles: ['./tests/setup.ts'],
+            coverage: {
+              provider: 'v8',
+              reporter: ['text', 'json', 'html'],
+              include: ['src/**/*.ts'],
+              exclude: ['src/**/*.d.ts', 'src/**/index.ts', 'src/types/**'],
+              thresholds: {
+                lines: 80,
+                functions: 80,
+                branches: 70,
+                statements: 80,
+              },
+            },
+          },
+          resolve: {
+            alias: { '@': path.resolve(__dirname, './src') },
+          },
+        });
+      indicators:
+        - "vitest.config.ts"
+        - "coverage:"
+        - "thresholds:"
+    - concern: async_testing
+      belongs_in: src/__tests__
+      rule_text: "Always await async assertions and use the correct Vitest assertion for async operations. Use expect(...).rejects.toThrow() for expected errors. Always return or await the assertion chain — unawaited assertions pass even when they should fail."
+      example: |
+        import { it, expect, vi } from 'vitest';
+        import { getUser } from '@/services/user.service';
+
+        it('returns null for unknown user', async () => {
+          const user = await getUser('nonexistent-id');
+          expect(user).toBeNull();
+        });
+
+        it('throws for invalid ID format', async () => {
+          // ✓ Must await rejects assertions
+          await expect(getUser('not-a-uuid')).rejects.toThrow('Invalid user ID');
+        });
+
+        it('resolves with user data', async () => {
+          const user = await getUser('valid-uuid-123');
+          expect(user).toMatchObject({ id: 'valid-uuid-123', email: expect.any(String) });
+        });
+      indicators:
+        - "await expect("
+        - ".rejects."
+        - ".resolves."
+patterns:
+  data_flow:
+    direction: "Test → vi.mock() (module replacement) → Module Under Test → Assertion"
+    rules:
+      - "vi.mock() replaces modules at load time — mock the dependencies, not the module under test."
+      - "vi.clearAllMocks() in beforeEach ensures each test starts with clean mock state."
+      - "Test observable behavior (return values, thrown errors, side effects) not internal state."
+      - "Integration tests in tests/integration/ use real dependencies — no mocking."
+      - "Coverage thresholds in vitest.config.ts — CI fails if coverage drops below threshold."
+  error_handling:
+    recommended: "For expected errors, use await expect(fn()).rejects.toThrow(). Always await the assertion — an unawaited .rejects check never runs the assertion and passes silently."
+  naming:
+    unit_tests: "src/__tests__/[path]/[module].test.ts — mirrors source path"
+    integration_tests: "tests/integration/[feature].integration.test.ts"
+    fixtures: "tests/fixtures/[resource].factory.ts — factory functions returning test data"
+    setup: "tests/setup.ts — global beforeAll/afterAll hooks (DB connection, etc.)"
+anti_patterns:
+  - id: jest_api_in_vitest
+    severity: warning
+    description: "Using Jest APIs (jest.fn(), jest.mock(), @jest/globals) in a Vitest project. Jest and Vitest have similar but distinct APIs — jest.mock() does not work in Vitest, and jest.fn() creates an incompatible mock object."
+    bad_example: |
+      // ❌ Jest API in a Vitest project — jest is undefined at runtime
+      import { jest } from '@jest/globals';
+      const fn = jest.fn();
+      jest.mock('../lib/db');
+      jest.spyOn(console, 'error');
+    good_example: |
+      // ✓ Vitest API — same patterns, correct module
+      import { vi } from 'vitest';
+      const fn = vi.fn();
+      vi.mock('../lib/db');
+      vi.spyOn(console, 'error');
+  - id: no_coverage_threshold
+    severity: warning
+    description: "Configuring coverage reporting without thresholds. Coverage numbers are displayed but no CI failure is triggered when they drop. Coverage silently regresses to 0% over time without developer awareness."
+    bad_example: |
+      // vitest.config.ts — coverage runs but thresholds not enforced
+      coverage: {
+        provider: 'v8',
+        reporter: ['text'],
+        // Missing: thresholds
+      }
+    good_example: |
+      coverage: {
+        provider: 'v8',
+        reporter: ['text', 'html'],
+        thresholds: { lines: 80, functions: 80, branches: 70 },
+      }
+  - id: shared_mock_state
+    severity: warning
+    description: "Not calling vi.clearAllMocks() between tests — mock call counts and return values from one test persist into the next test. A mock that returns a value in test 1 will return the same value in test 2 even if the test doesn't configure it, causing false passes."
+    bad_example: |
+      // ❌ Mock state leaks between tests — no clearAllMocks
+      it('test 1', () => { mockFn.mockReturnValue('hello'); mockFn(); });
+      it('test 2', () => {
+        // mockFn still has call count = 1 and return value 'hello' from test 1
+        expect(mockFn).not.toHaveBeenCalled(); // FALSE POSITIVE — passes incorrectly
+      });
+    good_example: |
+      // ✓ Clean mock state for every test
+      beforeEach(() => vi.clearAllMocks()); // resets all mock state before each test
+  - id: testing_implementation_details
+    severity: warning
+    description: "Testing internal state, private methods, or how a function does its work instead of what it returns. Tests tied to implementation break on every refactor even when behavior is correct — they add maintenance burden without adding safety."
+    bad_example: |
+      // ❌ Testing internal implementation — breaks on refactor
+      it('should call _formatEmail before sending', () => {
+        const spy = vi.spyOn(service, '_formatEmail' as any);
+        service.sendWelcomeEmail('user@example.com');
+        expect(spy).toHaveBeenCalled(); // testing HOW, not WHAT
+      });
+    good_example: |
+      // ✓ Test observable behavior — what the function produces
+      it('sends a welcome email with the correct subject', async () => {
+        await service.sendWelcomeEmail('user@example.com');
+        expect(sendEmail).toHaveBeenCalledWith('user@example.com', expect.objectContaining({
+          subject: 'Welcome to the platform',
+        }));
+      });
+  - id: async_test_without_await
+    severity: critical
+    description: "Not awaiting async assertions in tests. Without await, expect(...).rejects.toThrow() returns a Promise that is ignored — the test passes even if the function throws synchronously or doesn't throw at all."
+    bad_example: |
+      // ❌ Unawaited assertion — always passes regardless of behavior
+      it('should throw for invalid input', () => {
+        // No await — this Promise is created and immediately discarded
+        expect(getUser('invalid')).rejects.toThrow(); // always passes!
+      });
+    good_example: |
+      // ✓ Await the assertion — test fails if the function doesn't throw
+      it('should throw for invalid input', async () => {
+        await expect(getUser('invalid')).rejects.toThrow('Invalid user ID');
+      });
+  - id: snapshot_overuse
+    severity: warning
+    description: "Using toMatchSnapshot() for business logic assertions — snapshot tests hide intent (the snapshot is not readable), break on irrelevant UI/format changes, and make it impossible to understand what a test is verifying without looking up the snapshot file."
+    bad_example: |
+      // ❌ Snapshot for business logic — what does this test?
+      it('should calculate order total', () => {
+        const order = calculateOrder([{ price: 10, qty: 2 }, { price: 5, qty: 1 }]);
+        expect(order).toMatchSnapshot(); // snapshot: { total: 25, items: [...] }
+        // When the snapshot fails, is it a bug or an intentional change?
+      });
+    good_example: |
+      // ✓ Explicit assertions — intent is immediately clear
+      it('should calculate order total with correct subtotals', () => {
+        const order = calculateOrder([{ price: 10, qty: 2 }, { price: 5, qty: 1 }]);
+        expect(order.total).toBe(25);
+        expect(order.items).toHaveLength(2);
+        expect(order.items[0].subtotal).toBe(20);
+      });

package/skills/stacks/express-api.skill.yaml

@@ -0,0 +1,155 @@
+schema_version: "2.0.0"
+id: express-api
+name: "Express.js REST API"
+version: "1.1.0"
+description: "Layered Express REST API with routing, request handling, business logic, data access, middleware, configuration, and utilities separated."
+category: stack
+language: javascript
+frameworks:
+  - express
+detection:
+  dependencies:
+    any:
+      - express
+    none:
+      - next
+  source_indicators:
+    - "express()"
+    - "app.listen"
+    - "router.get"
+    - "router.post"
+structure:
+  required_dirs:
+    - path: src/routes
+      purpose: "Route definitions organized by resource."
+    - path: src/controllers
+      purpose: "Request handlers that receive HTTP input, call services, and return responses."
+    - path: src/services
+      purpose: "Business logic with no HTTP request or response awareness."
+    - path: src/models
+      purpose: "Data models and database interactions."
+    - path: src/middleware
+      purpose: "Cross-cutting request behavior such as auth, validation, and error handling."
+  recommended_dirs:
+    - path: src/config
+      purpose: "Environment and application configuration."
+    - path: src/utils
+      purpose: "Small shared helpers with no framework coupling."
+    - path: src/validators
+      purpose: "Request and domain validation schemas."
+separation:
+  rules:
+    - concern: routing
+      belongs_in: src/routes
+      rule_text: "Route files define HTTP endpoints and delegate request flow to controllers. They should not contain persistence or business rules."
+      example: |
+        router.get('/users', UserController.list);
+        router.post('/users', UserController.create);
+      indicators:
+        - "router.get"
+        - "router.post"
+        - "app.get"
+    - concern: request_handling
+      belongs_in: src/controllers
+      rule_text: "Controllers translate req/res objects into plain inputs for services and shape the HTTP response from service results."
+      example: |
+        export async function create(req, res) {
+          const user = await userService.create(req.body);
+          res.status(201).json(user);
+        }
+      indicators:
+        - "req.body"
+        - "res.json"
+        - "res.status"
+    - concern: business_logic
+      belongs_in: src/services
+      rule_text: "Services contain business rules and orchestration. They accept plain data and return plain data without touching HTTP objects."
+      example: |
+        export async function createUser(input) {
+          await validateUser(input);
+          return userModel.create(input);
+        }
+      anti_indicators:
+        - "req."
+        - "res."
+        - "next("
+    - concern: data_access
+      belongs_in: src/models
+      rule_text: "Models and repositories own database queries and persistence details so higher layers stay storage-agnostic."
+      example: |
+        export async function createUserRecord(data) {
+          return prisma.user.create({ data });
+        }
+      indicators:
+        - "prisma."
+        - ".findOne"
+        - ".create("
+        - "SELECT"
+patterns:
+  error_handling:
+    recommended: "Use centralized error-handling middleware."
+  data_flow:
+    direction: "Route -> Controller -> Service -> Model"
+    rules:
+      - "Routes call controllers."
+      - "Controllers call services."
+      - "Services do not import request or response objects."
+  naming:
+    files: "Use kebab-case for all file names. Suffix by layer: users.route.ts, users.controller.ts, users.service.ts, users.model.ts, auth.middleware.ts."
+    controllers: "[resource].controller.ts"
+    services: "[resource].service.ts"
+anti_patterns:
+  - id: god_file
+    severity: critical
+    description: "Single file mixes routes, data access, validation, and business logic."
+    bad_example: |
+      app.post('/users', async (req, res) => {
+        const hash = await bcrypt.hash(req.body.password, 10);
+        const user = await db.query('INSERT INTO users ...');
+        res.status(201).json(user);
+      });
+    good_example: |
+      // src/routes/users.ts — route only delegates
+      router.post('/users', UserController.create);
+
+      // src/controllers/users.controller.ts — translates HTTP to plain data
+      export async function create(req: Request, res: Response) {
+        const user = await userService.createUser(req.body);
+        res.status(201).json(user);
+      }
+
+      // src/services/users.service.ts — business rules, no HTTP awareness
+      export async function createUser(input: CreateUserDTO) {
+        const hash = await bcrypt.hash(input.password, 10);
+        return userModel.create({ ...input, password: hash });
+      }
+  - id: raw_sql_in_routes
+    severity: warning
+    description: "SQL queries appear directly in route handlers."
+    bad_example: |
+      router.get('/users', async (req, res) => {
+        const rows = await db.query('SELECT * FROM users');
+        res.json(rows);
+      });
+    good_example: |
+      router.get('/users', UserController.list);
+  - id: hardcoded_secrets
+    severity: critical
+    description: "Secrets or credentials are hardcoded in source files."
+    bad_example: |
+      const jwtSecret = 'super-secret-key';
+    good_example: |
+      // src/config/index.ts — validated at startup, never scattered across the app
+      import { z } from 'zod';
+      const env = z.object({
+        JWT_SECRET: z.string().min(32),
+        DATABASE_URL: z.string().url(),
+      }).parse(process.env);
+      export const config = {
+        auth: { jwtSecret: env.JWT_SECRET },
+        db: { url: env.DATABASE_URL },
+      };
+
+      // In middleware — reads from config, not from process.env
+      import { config } from '@/config';
+      const jwtSecret = config.auth.jwtSecret;

package/skills/stacks/fastify-api.skill.yaml

@@ -0,0 +1,119 @@
+schema_version: "2.0.0"
+id: fastify-api
+name: "Fastify API"
+version: "1.1.0"
+description: "High-performance Fastify API with plugin architecture, TypeBox schema validation, and decorator patterns."
+category: stack
+language: javascript
+frameworks:
+  - fastify
+detection:
+  dependencies:
+    any:
+      - fastify
+    none:
+      - express
+      - next
+      - hono
+  source_indicators:
+    - "fastify()"
+    - "Fastify()"
+    - "fastify.register"
+structure:
+  required_dirs:
+    - path: src/routes
+      purpose: "Route definitions registered as Fastify plugins — one file per resource."
+    - path: src/services
+      purpose: "Business logic with no Fastify imports — receives plain data, returns plain data."
+    - path: src/schemas
+      purpose: "TypeBox JSON schemas for request/response validation shared between routes and types."
+    - path: src/plugins
+      purpose: "Fastify plugins — auth, DB connections, decorators, and shared utilities."
+  recommended_dirs:
+    - path: src/types
+      purpose: "Shared TypeScript interfaces and custom error types."
+    - path: src/lib
+      purpose: "Client singletons such as database connections."
+separation:
+  rules:
+    - concern: schema_validation
+      belongs_in: src/schemas
+      rule_text: "Define all request/response schemas using TypeBox in src/schemas/. Register them on routes using the schema option. Never skip schema validation on public endpoints."
+      example: |
+        // src/schemas/user.schema.ts
+        import { Type } from '@sinclair/typebox';
+        export const CreateUserBody = Type.Object({
+          email: Type.String({ format: 'email' }),
+          password: Type.String({ minLength: 8 }),
+        });
+      indicators:
+        - "Type.Object"
+        - "@sinclair/typebox"
+    - concern: plugins
+      belongs_in: src/plugins
+      rule_text: "Encapsulate cross-cutting concerns as Fastify plugins. Register DB clients, auth decorators, and shared utilities as plugins — not inline in route handlers. Use fastify-plugin (fp) to avoid scope encapsulation so decorators are visible across the entire app."
+      example: |
+        // src/plugins/db.ts
+        import fp from 'fastify-plugin';
+        export default fp(async (fastify) => {
+          fastify.decorate('db', drizzle(connection));
+        });
+      indicators:
+        - "fastify-plugin"
+        - "fp("
+        - "fastify.decorate"
+        - "fastify.register"
+    - concern: services
+      belongs_in: src/services
+      rule_text: "Services must not import Fastify types (FastifyRequest, FastifyReply). They receive plain objects and return plain data."
+      example: |
+        // src/services/users.service.ts
+        export async function createUser(data: CreateUserDTO) {
+          return db.insert(users).values(data).returning();
+        }
+      anti_indicators:
+        - "FastifyRequest"
+        - "FastifyReply"
+patterns:
+  data_flow:
+    direction: "Route Plugin → Service → Data Access"
+    rules:
+      - "Route plugins define schemas and delegate to services."
+      - "Services contain business logic with no Fastify imports."
+      - "Plugins manage cross-cutting concerns like auth and DB connections."
+  error_handling:
+    recommended: "Use Fastify's setErrorHandler for centralized error handling."
+  naming:
+    routes: "[resource].route.ts"
+    services: "[resource].service.ts"
+    schemas: "[resource].schema.ts"
+anti_patterns:
+  - id: no_schema
+    severity: critical
+    description: "Defining Fastify routes without a schema object loses type safety, automatic serialization, and OpenAPI doc generation."
+    bad_example: |
+      // ❌ No schema — no type safety or serialization
+      fastify.post('/users', async (req, reply) => { ... });
+    good_example: |
+      // ✓ Schema-validated route
+      fastify.post('/users', { schema: { body: CreateUserBody } }, handler);
+  - id: business_logic_in_handler
+    severity: critical
+    description: "Putting business rules and DB queries directly in route handlers instead of services."
+    bad_example: |
+      fastify.post('/users', async (req) => {
+        const hash = await bcrypt.hash(req.body.password, 10);
+        return fastify.db.users.create({ ...req.body, password: hash });
+      });
+    good_example: |
+      fastify.post('/users', { schema: { body: CreateUserBody } }, async (req) => {
+        return userService.createUser(req.body);
+      });
+  - id: fastify_type_in_service
+    severity: warning
+    description: "Importing FastifyRequest or FastifyReply in service files couples business logic to the HTTP framework."
+    bad_example: |
+      import type { FastifyRequest } from 'fastify';
+      export function handleUser(req: FastifyRequest) { ... }
+    good_example: |
+      export function handleUser(data: CreateUserDTO) { ... }

package/skills/stacks/hono-api.skill.yaml

@@ -0,0 +1,130 @@
+schema_version: "2.0.0"
+id: hono-api
+name: "Hono API"
+version: "1.1.0"
+description: "Lightweight, edge-first Hono API with Zod validation, platform-agnostic handlers, and middleware chaining."
+category: stack
+language: javascript
+frameworks:
+  - hono
+detection:
+  dependencies:
+    any:
+      - hono
+    none:
+      - express
+      - fastify
+      - "@nestjs/core"
+  source_indicators:
+    - "new Hono()"
+    - "from 'hono'"
+    - "from \"hono\""
+structure:
+  required_dirs:
+    - path: src/routes
+      purpose: "Route definitions grouped by resource — registered on the Hono app instance."
+    - path: src/services
+      purpose: "Business logic with no Hono or platform-specific imports."
+    - path: src/middleware
+      purpose: "Reusable Hono middleware — auth, logging, CORS, error handling."
+  recommended_dirs:
+    - path: src/schemas
+      purpose: "Zod schemas for request/response validation."
+    - path: src/types
+      purpose: "Shared TypeScript interfaces and error types."
+    - path: src/lib
+      purpose: "Singleton instances (database connections, KV clients) initialized once and reused across the app. Environment parsing and config validation live here. No route definitions or business logic."
+separation:
+  rules:
+    - concern: routing
+      belongs_in: src/routes
+      rule_text: "Route files define HTTP endpoints and call services. Use Hono's zValidator middleware for input validation. No business logic or DB queries in route handlers."
+      indicators:
+        - "new Hono()"
+        - ".get("
+        - ".post("
+        - "zValidator"
+      example: |
+        // src/routes/users.ts
+        import { Hono } from 'hono';
+        import { zValidator } from '@hono/zod-validator';
+        import { createUserSchema } from '../schemas/user.schema';
+        import { userService } from '../services/users.service';
+        const users = new Hono();
+        users.post('/', zValidator('json', createUserSchema), async (c) => {
+          const data = c.req.valid('json');
+          return c.json(await userService.create(data), 201);
+        });
+    - concern: platform_agnostic_handlers
+      belongs_in: src/services
+      rule_text: "Services must not import Hono context types (Context, HonoRequest). They receive plain data and return plain data — this keeps them portable across Cloudflare Workers, Node.js, and Bun."
+      example: |
+        // src/services/users.service.ts
+        export async function createUser(data: CreateUserDTO) {
+          return db.insert(users).values(data);
+        }
+      anti_indicators:
+        - "Context"
+        - "HonoRequest"
+        - "c.req"
+    - concern: validation
+      belongs_in: src/schemas
+      rule_text: "Define Zod schemas in src/schemas/ and use @hono/zod-validator to validate request bodies. Never manually parse and validate req.json() in handlers."
+      example: |
+        // src/schemas/user.schema.ts
+        import { z } from 'zod';
+        export const createUserSchema = z.object({
+          email: z.string().email(),
+          password: z.string().min(8),
+        });
+patterns:
+  data_flow:
+    direction: "Route → Service → Data Access"
+    rules:
+      - "Routes validate input with Zod and delegate to services."
+      - "Services are platform-agnostic — no Hono or env-specific imports."
+      - "Middleware handles cross-cutting concerns like auth and CORS."
+  error_handling:
+    recommended: "Use app.onError() for centralized error handling."
+  naming:
+    routes: "[resource].ts"
+    services: "[resource].service.ts"
+    schemas: "[resource].schema.ts"
+anti_patterns:
+  - id: node_api_in_handler
+    severity: critical
+    description: "Using Node.js-specific APIs (fs, process, Buffer) in route handlers breaks Cloudflare Workers and Bun compatibility."
+    bad_example: |
+      // ❌ Node.js API breaks edge compatibility
+      app.get('/file', (c) => {
+        const data = require('fs').readFileSync('./data.json');
+        return c.json(JSON.parse(data));
+      });
+    good_example: |
+      // ✓ Use env bindings or fetch — platform-agnostic
+      app.get('/file', async (c) => {
+        const data = await c.env.KV.get('data');
+        return c.json(JSON.parse(data));
+      });
+  - id: business_logic_in_handler
+    severity: critical
+    description: "Placing business rules and DB queries directly in route handlers instead of services."
+    bad_example: |
+      app.post('/users', async (c) => {
+        const body = await c.req.json();
+        const hash = await bcrypt.hash(body.password, 10);
+        const user = await db.insert(users).values({ ...body, password: hash });
+        return c.json(user);
+      });
+    good_example: |
+      app.post('/users', zValidator('json', createUserSchema), async (c) => {
+        return c.json(await userService.create(c.req.valid('json')), 201);
+      });
+  - id: no_zod_validation
+    severity: warning
+    description: "Parsing request body with c.req.json() without schema validation — trusts unvalidated user input."
+    bad_example: |
+      const body = await c.req.json(); // unvalidated
+    good_example: |
+      // Use zValidator middleware — body is typed and validated
+      zValidator('json', createUserSchema)