Kiro IDE: Building a Production API With Spec-Driven AI (Hands-On Tutorial)

curl -fsSL https://cli.kiro.dev/install | bash

.kiro/
└── steering/
    ├── product.md
    ├── tech.md
    └── structure.md

---
inclusion: always
---
 
# Technology Stack
 
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: Vanilla CSS with CSS Modules
- Database: Supabase (PostgreSQL)

---
inclusion: fileMatch
fileMatchPattern: "src/app/api/**/*"
---
 
# API Standards
 
## Validation
- All API routes MUST validate input using Zod schemas
- Error responses MUST follow this shape:
  { success: false, error: string }
- Success responses MUST follow this shape:
  { success: true, data?: any }
 
## HTTP Status Codes
- 400 for validation errors
- 401 for authentication failures
- 404 for missing resources
- 500 only for unhandled exceptions
 
## Logging
- Log validation failures at WARN level
- Log server errors at ERROR level with stack trace
- Never log request bodies containing PII
 
## Patterns
Follow the existing pattern in:
#[[file:src/app/api/polls/route.ts]]

# Reading Progress — Requirements
 
## User Story 1: Scroll Progress Indicator
As a blog reader, I want to see how far I have scrolled
through an article so I can gauge remaining content.
 
### Acceptance Criteria
- WHEN a visitor loads a blog post THE SYSTEM SHALL render
  a horizontal progress bar fixed to the top of the viewport.
- WHILE the visitor scrolls THE SYSTEM SHALL update the
  progress bar width proportionally (0% to 100%).
- The system shall not render the progress bar on non-article
  pages.
 
## User Story 2: Anonymous Scroll Analytics
As a site owner, I want anonymized scroll depth data to
identify which articles hold reader attention.
 
### Acceptance Criteria
- WHEN a visitor scrolls past 25%, 50%, 75%, or 100% THE
  SYSTEM SHALL send a POST to /api/analytics/reading.
- The system shall never store IP addresses, cookies, or
  personally identifiable information.
- IF a depth milestone has already been recorded for this
  session THE SYSTEM SHALL not record a duplicate event.

# Reading Progress — Design
 
## Component Architecture
- ReadingProgress (Client Component): renders fixed progress bar,
  subscribes to scroll events via useScrollDepth hook.
- useScrollDepth (Custom Hook): uses IntersectionObserver with
  sentinel elements at 25/50/75/100% of article body.
 
## API Contract
### POST /api/analytics/reading
Request (validated with Zod):
  - articleSlug: string (required, max 255 chars)
  - depth: z.enum(["25", "50", "75", "100"])
  - sessionId: string (UUID, generated client-side, no PII)
 
Response: { success: true } | { success: false, error: string }
 
## Database Schema
Table: reading_events
  - id: UUID (primary key, auto-generated)
  - article_slug: VARCHAR(255), indexed
  - depth: INTEGER
  - session_id: VARCHAR(36)
  - created_at: TIMESTAMPTZ (default: now())
 
## Testing Strategy
- Unit: useScrollDepth threshold detection
- Integration: POST /api/analytics/reading validation + insert
- E2E: progress bar renders and updates on scroll

# Implementation Tasks
 
- [ ] Task 1: Create reading_events table migration
      (Design: Database Schema)
- [ ] Task 2: Implement useScrollDepth hook with
      IntersectionObserver (Design: Component Architecture)
- [ ] Task 3: Build ReadingProgress client component
      (Requirement: User Story 1, AC 1-3)
- [ ] Task 4: Create POST /api/analytics/reading with Zod
      validation (Design: API Contract)
- [ ] Task 5: Wire component → hook → API integration
      (Requirement: User Story 2)
- [ ] Task 6: Write unit + integration tests
      (Design: Testing Strategy)
- [ ] Task 7: Add conditional rendering — blog pages only
      (Requirement: User Story 1, AC 3)

- [x] Task 1: Create reading_events table migration ✓
- [x] Task 2: Implement useScrollDepth hook ✓
- [x] Task 3: Build ReadingProgress component ✓
- [/] Task 4: Create POST /api/analytics/reading...

CREATE TABLE reading_events (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  article_slug VARCHAR(255) NOT NULL,
  depth INTEGER NOT NULL CHECK (depth IN (25, 50, 75, 100)),
  session_id VARCHAR(36) NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
 
CREATE INDEX idx_reading_events_slug ON reading_events(article_slug);
CREATE INDEX idx_reading_events_session ON reading_events(session_id, article_slug, depth);
 
-- Prevent duplicate depth events per session per article
CREATE UNIQUE INDEX idx_reading_events_unique
  ON reading_events(session_id, article_slug, depth);

"use client";
 
import { useEffect, useRef, useCallback } from "react";
 
type DepthMilestone = 25 | 50 | 75 | 100;
 
interface UseScrollDepthOptions {
  articleSlug: string;
  onMilestone: (depth: DepthMilestone) => void;
}
 
export function useScrollDepth({
  articleSlug,
  onMilestone,
}: UseScrollDepthOptions) {
  const reachedRef = useRef<Set<DepthMilestone>>(new Set());
  const sentinelsRef = useRef<HTMLDivElement[]>([]);
 
  const handleIntersection = useCallback(
    (entries: IntersectionObserverEntry[]) => {
      entries.forEach((entry) => {
        if (!entry.isIntersecting) return;
 
        const depth = Number(
          entry.target.getAttribute("data-depth")
        ) as DepthMilestone;
 
        if (reachedRef.current.has(depth)) return;
 
        reachedRef.current.add(depth);
        onMilestone(depth);
      });
    },
    [onMilestone]
  );
 
  useEffect(() => {
    const article = document.querySelector("article");
    if (!article) return;
 
    const observer = new IntersectionObserver(handleIntersection, {
      threshold: 0,
    });
 
    const milestones: DepthMilestone[] = [25, 50, 75, 100];
 
    milestones.forEach((depth) => {
      const sentinel = document.createElement("div");
      sentinel.setAttribute("data-depth", String(depth));
      sentinel.style.position = "absolute";
      sentinel.style.height = "1px";
      sentinel.style.width = "1px";
      sentinel.style.top = `${depth}%`;
      sentinel.style.pointerEvents = "none";
      article.style.position = "relative";
      article.appendChild(sentinel);
      sentinelsRef.current.push(sentinel);
      observer.observe(sentinel);
    });
 
    return () => {
      observer.disconnect();
      sentinelsRef.current.forEach((s) => s.remove());
      sentinelsRef.current = [];
    };
  }, [articleSlug, handleIntersection]);
 
  return {
    progress: reachedRef.current,
  };
}

"use client";
 
import { useState, useCallback } from "react";
import { useScrollDepth } from "@/hooks/useScrollDepth";
import styles from "./ReadingProgress.module.css";
 
interface ReadingProgressProps {
  articleSlug: string;
}
 
export function ReadingProgress({ articleSlug }: ReadingProgressProps) {
  const [scrollPercent, setScrollPercent] = useState(0);
  const sessionId = useSessionId();
 
  const handleMilestone = useCallback(
    async (depth: 25 | 50 | 75 | 100) => {
      setScrollPercent(depth);
 
      try {
        await fetch("/api/analytics/reading", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            articleSlug,
            depth: String(depth),
            sessionId,
          }),
        });
      } catch {
        // Silent fail — analytics should never break UX
      }
    },
    [articleSlug, sessionId]
  );
 
  useScrollDepth({ articleSlug, onMilestone: handleMilestone });
 
  return (
    <div className={styles.container}>
      <div
        className={styles.bar}
        style={{ width: `${scrollPercent}%` }}
        role="progressbar"
        aria-valuenow={scrollPercent}
        aria-valuemin={0}
        aria-valuemax={100}
        aria-label="Reading progress"
      />
    </div>
  );
}
 
function useSessionId(): string {
  if (typeof window === "undefined") return "";
 
  let id = sessionStorage.getItem("reading-session-id");
  if (!id) {
    id = crypto.randomUUID();
    sessionStorage.setItem("reading-session-id", id);
  }
  return id;
}

import { NextRequest, NextResponse } from "next/server";
import { z } from "zod";
import { supabase } from "@/lib/db/client";
 
const ReadingEventSchema = z.object({
  articleSlug: z.string().min(1).max(255),
  depth: z.enum(["25", "50", "75", "100"]),
  sessionId: z.string().uuid(),
});
 
export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const result = ReadingEventSchema.safeParse(body);
 
    if (!result.success) {
      console.warn(
        "[analytics/reading] Validation failed:",
        result.error.flatten().fieldErrors
      );
      return NextResponse.json(
        { success: false, error: result.error.issues[0].message },
        { status: 400 }
      );
    }
 
    const { articleSlug, depth, sessionId } = result.data;
 
    const { error } = await supabase.from("reading_events").upsert(
      {
        article_slug: articleSlug,
        depth: parseInt(depth, 10),
        session_id: sessionId,
      },
      {
        onConflict: "session_id,article_slug,depth",
        ignoreDuplicates: true,
      }
    );
 
    if (error) {
      console.error("[analytics/reading] Database error:", error);
      return NextResponse.json(
        { success: false, error: "Internal server error" },
        { status: 500 }
      );
    }
 
    return NextResponse.json({ success: true });
  } catch (err) {
    console.error("[analytics/reading] Unhandled error:", err);
    return NextResponse.json(
      { success: false, error: "Internal server error" },
      { status: 500 }
    );
  }
}

import { POST } from "@/app/api/analytics/reading/route";
import { NextRequest } from "next/server";
 
function makeRequest(body: Record<string, unknown>) {
  return new NextRequest("http://localhost/api/analytics/reading", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
}
 
describe("POST /api/analytics/reading", () => {
  it("returns 400 when articleSlug is missing", async () => {
    const res = await POST(makeRequest({ depth: "50", sessionId: crypto.randomUUID() }));
    expect(res.status).toBe(400);
    const data = await res.json();
    expect(data.success).toBe(false);
  });
 
  it("returns 400 when depth is invalid", async () => {
    const res = await POST(
      makeRequest({
        articleSlug: "test-post",
        depth: "30",
        sessionId: crypto.randomUUID(),
      })
    );
    expect(res.status).toBe(400);
  });
 
  it("returns 400 when sessionId is not a UUID", async () => {
    const res = await POST(
      makeRequest({
        articleSlug: "test-post",
        depth: "50",
        sessionId: "not-a-uuid",
      })
    );
    expect(res.status).toBe(400);
  });
 
  it("accepts valid depth values (25, 50, 75, 100)", async () => {
    for (const depth of ["25", "50", "75", "100"]) {
      const res = await POST(
        makeRequest({
          articleSlug: "test-post",
          depth,
          sessionId: crypto.randomUUID(),
        })
      );
      expect(res.status).toBe(200);
      const data = await res.json();
      expect(data.success).toBe(true);
    }
  });
});

When a source file is modified:
1. Identify new or modified functions and methods
2. Check if corresponding tests exist and cover the changes
3. If coverage is missing, generate test cases for the new code
4. Run the tests to verify they pass
5. Update coverage reports

Review changed files for potential security issues:
1. Look for API keys, tokens, or credentials in source code
2. Check for private keys or sensitive credentials
3. Scan for encryption keys or certificates
4. Flag passwords or secrets in configuration files
5. Detect hardcoded internal URLs
6. Spot database connection credentials
 
For each issue found:
1. Highlight the specific security risk
2. Suggest a secure alternative approach

When an English locale file is updated:
1. Identify which string keys were added or modified
2. Check all other language files for these keys
3. For missing keys, add them with a "NEEDS_TRANSLATION" marker
4. For modified keys, mark them as "NEEDS_REVIEW"
5. Generate a summary of changes needed across all languages

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      },
      "autoApprove": ["list_issues", "search_repositories"]
    },
    "aws-docs": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-server-aws-docs"
      ]
    }
  }
}

# Bugfix: /api/analytics/reading 500 on integer depth
 
## Current Behavior
POST /api/analytics/reading returns 500 when the depth field
is an integer. The Zod schema uses z.enum(["25", "50", "75",
"100"]) which only accepts strings. Integer values fail
validation but the error is not caught gracefully, resulting
in an unhandled exception.
 
## Expected Behavior
- WHEN depth is sent as an integer (25, 50, 75, 100) THE
  SYSTEM SHALL coerce it to a string and process normally.
- WHEN depth is sent as a string ("25", "50", "75", "100")
  THE SYSTEM SHALL process normally (unchanged).
- WHEN depth is any other value THE SYSTEM SHALL return 400
  with error: "depth must be 25, 50, 75, or 100".
 
## Unchanged Behavior
- Valid requests must continue to return { success: true }.
- The reading_events table schema must not change.
- Existing records must not be affected.
 
## Root Cause
Zod schema in src/app/api/analytics/reading/route.ts uses
z.enum() for strings only. Needs z.preprocess() or z.coerce
to handle integer input.

- [ ] Task 1: Update Zod schema to accept both string and
      integer depth values using z.preprocess()
- [ ] Task 2: Add regression tests for integer depth input
      (25, 50, 75, 100 as integers)
- [ ] Task 3: Add regression test for invalid depth values
      (e.g., 30, -1, "abc")

- const ReadingEventSchema = z.object({
-   articleSlug: z.string().min(1).max(255),
-   depth: z.enum(["25", "50", "75", "100"]),
-   sessionId: z.string().uuid(),
- });
+ const DepthSchema = z.preprocess(
+   (val) => String(val),
+   z.enum(["25", "50", "75", "100"], {
+     errorMap: () => ({
+       message: "depth must be 25, 50, 75, or 100",
+     }),
+   })
+ );
+
+ const ReadingEventSchema = z.object({
+   articleSlug: z.string().min(1).max(255),
+   depth: DepthSchema,
+   sessionId: z.string().uuid(),
+ });

describe("POST /api/analytics/reading — integer depth regression", () => {
  it("accepts depth as integer 50", async () => {
    const res = await POST(
      makeRequest({
        articleSlug: "test-post",
        depth: 50, // integer, not string
        sessionId: crypto.randomUUID(),
      })
    );
    expect(res.status).toBe(200);
    const data = await res.json();
    expect(data.success).toBe(true);
  });
 
  it("accepts all integer depth values", async () => {
    for (const depth of [25, 50, 75, 100]) {
      const res = await POST(
        makeRequest({
          articleSlug: "test-post",
          depth, // integers
          sessionId: crypto.randomUUID(),
        })
      );
      expect(res.status).toBe(200);
    }
  });
 
  it("rejects invalid integer depth", async () => {
    const res = await POST(
      makeRequest({
        articleSlug: "test-post",
        depth: 30,
        sessionId: crypto.randomUUID(),
      })
    );
    expect(res.status).toBe(400);
    const data = await res.json();
    expect(data.error).toBe("depth must be 25, 50, 75, or 100");
  });
 
  it("rejects negative depth", async () => {
    const res = await POST(
      makeRequest({
        articleSlug: "test-post",
        depth: -1,
        sessionId: crypto.randomUUID(),
      })
    );
    expect(res.status).toBe(400);
  });
});

your-project/
├── .kiro/
│   ├── settings/
│   │   └── mcp.json
│   ├── steering/
│   │   ├── product.md          ← auto-generated, always loaded
│   │   ├── tech.md             ← auto-generated, always loaded
│   │   ├── structure.md        ← auto-generated, always loaded
│   │   └── api-standards.md    ← custom, loaded on API file edits
│   ├── specs/
│   │   ├── reading-progress/
│   │   │   ├── requirements.md
│   │   │   ├── design.md
│   │   │   └── tasks.md
│   │   └── fix-integer-depth/
│   │       ├── bugfix.md
│   │       ├── design.md
│   │       └── tasks.md
│   └── hooks/
│       ├── test-coverage.md
│       ├── security-scanner.md
│       └── i18n-sync.md
├── src/
│   ├── app/
│   │   └── api/
│   │       └── analytics/
│   │           └── reading/
│   │               └── route.ts
│   ├── hooks/
│   │   └── useScrollDepth.ts
│   └── components/
│       └── ReadingProgress.tsx
└── package.json

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { createClient } from "@supabase/supabase-js";
 
const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_KEY!
);
 
const server = new McpServer({
  name: "supabase-analytics",
  version: "1.0.0",
});
 
// Tool 1: Query reading analytics by article
server.tool(
  "get_reading_stats",
  "Get scroll depth analytics for a specific article",
  {
    articleSlug: z.string().describe("The blog post slug"),
  },
  async ({ articleSlug }) => {
    const { data, error } = await supabase
      .from("reading_events")
      .select("depth, session_id")
      .eq("article_slug", articleSlug);
 
    if (error) {
      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
    }
 
    const uniqueSessions = new Set(data.map((e) => e.session_id)).size;
    const depthCounts = data.reduce(
      (acc, e) => {
        acc[e.depth] = (acc[e.depth] || 0) + 1;
        return acc;
      },
      {} as Record<number, number>
    );
 
    const completionRate =
      uniqueSessions > 0
        ? ((depthCounts[100] || 0) / uniqueSessions * 100).toFixed(1)
        : "0";
 
    return {
      content: [
        {
          type: "text",
          text: [
            `## Reading Stats for "${articleSlug}"`,
            `- Unique readers: ${uniqueSessions}`,
            `- Reached 25%: ${depthCounts[25] || 0}`,
            `- Reached 50%: ${depthCounts[50] || 0}`,
            `- Reached 75%: ${depthCounts[75] || 0}`,
            `- Completed (100%): ${depthCounts[100] || 0}`,
            `- Completion rate: ${completionRate}%`,
          ].join("\n"),
        },
      ],
    };
  }
);
 
// Tool 2: List top articles by completion rate
server.tool(
  "top_articles",
  "List articles ranked by reader completion rate",
  {
    limit: z.number().optional().default(10),
  },
  async ({ limit }) => {
    const { data, error } = await supabase
      .from("reading_events")
      .select("article_slug, depth, session_id");
 
    if (error) {
      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
    }
 
    const articles = new Map<
      string,
      { sessions: Set<string>; completions: number }
    >();
 
    data.forEach((event) => {
      if (!articles.has(event.article_slug)) {
        articles.set(event.article_slug, {
          sessions: new Set(),
          completions: 0
        });
      }
      const article = articles.get(event.article_slug)!;
      article.sessions.add(event.session_id);
      if (event.depth === 100) article.completions++;
    });
 
    const ranked = Array.from(articles.entries())
      .map(([slug, stats]) => ({
        slug,
        readers: stats.sessions.size,
        completions: stats.completions,
        rate: (stats.completions / stats.sessions.size * 100).toFixed(1),
      }))
      .sort((a, b) => parseFloat(b.rate) - parseFloat(a.rate))
      .slice(0, limit);
 
    const table = ranked
      .map(
        (a, i) =>
          `${i + 1}. **${a.slug}** — ${a.rate}% completion (${a.readers} readers)`
      )
      .join("\n");
 
    return {
      content: [{ type: "text", text: `## Top Articles\n${table}` }],
    };
  }
);
 
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}
 
main().catch(console.error);

{
  "name": "mcp-supabase-analytics",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "tsx index.ts"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "@supabase/supabase-js": "^2.39.0",
    "zod": "^3.22.0"
  },
  "devDependencies": {
    "tsx": "^4.7.0"
  }
}

{
  "mcpServers": {
    "supabase-analytics": {
      "command": "npx",
      "args": ["tsx", "./mcp-supabase/index.ts"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_SERVICE_KEY": "${SUPABASE_SERVICE_KEY}"
      },
      "autoApprove": ["get_reading_stats", "top_articles"]
    }
  }
}

File Save (src/**/*.ts)
  ↓
Hook 1: Auto-format (Run Command)
  → npx prettier --write ${FILE}
  ↓
Hook 2: Test Coverage (Ask Kiro, File Save)
  → Generate missing tests, run them
  ↓
Hook 3: Security Scan (Ask Kiro, Agent Stop)
  → Scan for hardcoded secrets
  ↓
Hook 4: Doc Sync (Ask Kiro, Agent Stop)
  → Update README if exports changed
  ↓
Hook 5: Commit Prep (Manual Trigger)
  → Generate conventional commit message from spec

feat(analytics): add reading progress tracking API
 
Implements reading-progress spec (requirements.md, tasks 1-7).
- Added POST /api/analytics/reading with Zod validation
- Added useScrollDepth hook with IntersectionObserver
- Added ReadingProgress client component
- Added reading_events table migration
 
Closes #42

You are a senior TypeScript developer working on a Next.js 14
App Router project.
 
Rules:
- Use TypeScript strict mode
- Use Zod for all API validation
- Use Vanilla CSS with CSS Modules, never Tailwind
- Server components by default, client components need "use client"
- Never use `any` type
- All API routes return { success: boolean, error?: string }
- Database access through lib/db/ only
- Never modify migration files
- Run prettier before suggesting code
- Generate tests for all new functions

---
inclusion: always
---
 
# Technology Stack
- Next.js 14 (App Router), TypeScript strict mode
- Vanilla CSS with CSS Modules (never Tailwind)
- Supabase (PostgreSQL), NextAuth.js
- Server components by default
 
# Universal Rules
- Never use `any` type
- Never modify files in migrations/
- Never install dependencies without asking

---
inclusion: fileMatch
fileMatchPattern: "src/app/api/**/*"
---
 
# API Conventions
- Validate all input with Zod schemas
- Return { success: boolean, error?: string }
- 400 for validation, 401 for auth, 500 for server errors
- Database access through lib/db/ only
- Log validation failures at WARN, server errors at ERROR
 
Follow patterns in: #[[file:src/app/api/polls/route.ts]]

---
inclusion: fileMatch
fileMatchPattern: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
---
 
# Component Rules
- Client components require "use client" directive
- Add a comment explaining WHY it needs to be a client component
- Use CSS Modules for all styling (import styles from "./X.module.css")
- Wrap page-level components in error boundaries
 
Follow patterns in: #[[file:src/components/ui/Button.tsx]]

---
inclusion: fileMatch
fileMatchPattern: "src/__tests__/**/*"
---
 
# Testing Conventions
- Use Jest + React Testing Library
- Test file naming: [filename].test.ts
- Use makeRequest() helper for API route tests
- Mock Supabase client, never use real database
 
Follow patterns in: #[[file:src/__tests__/polls.test.ts]]

---
inclusion: manual
---
 
# Common Issues
 
## Hydration Errors
If you see "Text content does not match server-rendered HTML":
- Check for `Date.now()` or `Math.random()` in server components
- Check for browser-only APIs (window, document) without guards
- Solution: wrap in useEffect or move to client component
 
## Database Connection Errors
- Check SUPABASE_URL and SUPABASE_SERVICE_KEY in .env.local
- Run `npx supabase status` to verify local instance
- Check RLS policies if queries return empty results

monorepo/
├── .kiro/
│   └── steering/
│       ├── product.md              ← inclusion: always
│       ├── frontend-react.md       ← inclusion: fileMatch → apps/web/**/*
│       ├── backend-express.md      ← inclusion: fileMatch → apps/api/**/*
│       ├── shared-lib.md           ← inclusion: fileMatch → packages/shared/**/*
│       └── deployment.md           ← inclusion: manual
├── apps/
│   ├── web/                        ← React + Next.js
│   └── api/                        ← Express + Prisma
├── packages/
│   └── shared/                     ← Pure TypeScript utilities
└── turbo.json

---
inclusion: fileMatch
fileMatchPattern: "apps/web/**/*"
---
 
# Frontend (apps/web)
- Framework: Next.js 14 App Router
- Styling: Tailwind CSS (this package uses Tailwind, not Vanilla CSS)
- State: Zustand for client state, React Query for server state
- Components: use Radix UI primitives, never build custom from scratch
- Images: always use next/image with explicit width/height

---
inclusion: fileMatch
fileMatchPattern: "apps/api/**/*"
---
 
# Backend (apps/api)
- Framework: Express.js with TypeScript
- ORM: Prisma (never write raw SQL)
- Validation: Zod middleware on every route
- Auth: JWT with refresh tokens, stored in httpOnly cookies
- Error handling: use AppError class from packages/shared
- NEVER import React or any frontend dependency in this package

---
inclusion: fileMatch
fileMatchPattern: "packages/shared/**/*"
---
 
# Shared Library (packages/shared)
- Pure TypeScript only (no React, no Express, no framework deps)
- Must be tree-shakeable (named exports only, no default exports)
- Every exported function needs JSDoc with @example
- Zero runtime dependencies (utils only)
- All types go in types/ subdirectory

---
inclusion: fileMatch
fileMatchPattern: ["apps/web/**/*.test.*", "apps/api/**/*.test.*", "packages/shared/**/*.test.*"]
---
 
# Testing Standards (All Packages)
- Framework: Vitest
- Coverage threshold: 80% for new files
- Mock external services, never hit real APIs in tests
- Use factories for test data, never hardcode