agentic-team-templates 0.3.0

package/templates/fullstack/.cursorrules/api-contracts.md

@@ -0,0 +1,331 @@
+# API Contracts
+
+Defining and maintaining contracts between frontend and backend.
+
+## Why API Contracts Matter
+
+- **Type Safety**: Catch mismatches at compile time
+- **Documentation**: Self-documenting API surface
+- **Consistency**: Single source of truth
+- **Parallel Development**: Frontend and backend can work independently
+
+## Schema-Driven Development
+
+### Define Schemas First
+
+```ts
+// shared/schemas/user.ts
+import { z } from 'zod';
+
+// Request schemas
+export const CreateUserRequestSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+  role: z.enum(['user', 'admin']).default('user'),
+});
+
+export const UpdateUserRequestSchema = CreateUserRequestSchema.partial();
+
+// Response schemas
+export const UserResponseSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string(),
+  role: z.enum(['user', 'admin']),
+  createdAt: z.string().datetime(),
+});
+
+export const UsersListResponseSchema = z.object({
+  data: z.array(UserResponseSchema),
+  pagination: z.object({
+    page: z.number(),
+    limit: z.number(),
+    total: z.number(),
+  }),
+});
+
+// Infer types from schemas
+export type CreateUserRequest = z.infer<typeof CreateUserRequestSchema>;
+export type UpdateUserRequest = z.infer<typeof UpdateUserRequestSchema>;
+export type UserResponse = z.infer<typeof UserResponseSchema>;
+export type UsersListResponse = z.infer<typeof UsersListResponseSchema>;
+```
+
+### Use on Backend
+
+```ts
+// api/routes/users.ts
+import { CreateUserRequestSchema, UserResponseSchema } from '@shared/schemas/user';
+
+app.post('/users', async (req, res) => {
+  // Validate input
+  const parsed = CreateUserRequestSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(422).json({ error: parsed.error });
+  }
+
+  const user = await createUser(parsed.data);
+
+  // Validate output (optional but good for catching bugs)
+  const response = UserResponseSchema.parse(user);
+  res.status(201).json({ data: response });
+});
+```
+
+### Use on Frontend
+
+```ts
+// lib/api/users.ts
+import {
+  CreateUserRequest,
+  UserResponse,
+  UsersListResponse,
+  CreateUserRequestSchema,
+} from '@shared/schemas/user';
+
+export const usersApi = {
+  async create(data: CreateUserRequest): Promise<UserResponse> {
+    // Validate before sending (catches client-side errors early)
+    const validated = CreateUserRequestSchema.parse(data);
+
+    const response = await fetch('/api/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(validated),
+    });
+
+    if (!response.ok) {
+      throw new ApiError(response);
+    }
+
+    const json = await response.json();
+    return json.data;
+  },
+
+  async list(page = 1, limit = 20): Promise<UsersListResponse> {
+    const response = await fetch(`/api/users?page=${page}&limit=${limit}`);
+    if (!response.ok) throw new ApiError(response);
+    return response.json();
+  },
+};
+```
+
+## OpenAPI / Swagger
+
+### Generate from Code
+
+```ts
+// Using Zod to OpenAPI
+import { OpenAPIRegistry, OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi';
+
+const registry = new OpenAPIRegistry();
+
+registry.registerPath({
+  method: 'post',
+  path: '/users',
+  summary: 'Create a new user',
+  request: {
+    body: {
+      content: { 'application/json': { schema: CreateUserRequestSchema } },
+    },
+  },
+  responses: {
+    201: {
+      description: 'User created',
+      content: { 'application/json': { schema: UserResponseSchema } },
+    },
+    422: { description: 'Validation error' },
+  },
+});
+
+const generator = new OpenApiGeneratorV3(registry.definitions);
+export const openApiDoc = generator.generateDocument({
+  info: { title: 'Users API', version: '1.0.0' },
+});
+```
+
+### Manual OpenAPI Spec
+
+```yaml
+# openapi.yaml
+openapi: 3.0.0
+info:
+  title: Users API
+  version: 1.0.0
+
+paths:
+  /users:
+    post:
+      summary: Create a new user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserRequest'
+      responses:
+        '201':
+          description: User created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserResponse'
+
+components:
+  schemas:
+    CreateUserRequest:
+      type: object
+      required: [email, name]
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+```
+
+## Type-Safe API Clients
+
+### Using tRPC
+
+```ts
+// server/trpc.ts
+import { initTRPC } from '@trpc/server';
+import { z } from 'zod';
+
+const t = initTRPC.create();
+
+export const appRouter = t.router({
+  user: t.router({
+    list: t.procedure
+      .input(z.object({ page: z.number().default(1) }))
+      .query(async ({ input }) => {
+        return db.user.findMany({ skip: (input.page - 1) * 20, take: 20 });
+      }),
+
+    create: t.procedure
+      .input(CreateUserRequestSchema)
+      .mutation(async ({ input }) => {
+        return db.user.create({ data: input });
+      }),
+  }),
+});
+
+export type AppRouter = typeof appRouter;
+
+// client/trpc.ts
+import { createTRPCReact } from '@trpc/react-query';
+import type { AppRouter } from '../server/trpc';
+
+export const trpc = createTRPCReact<AppRouter>();
+
+// Usage in component
+const users = trpc.user.list.useQuery({ page: 1 });
+const createUser = trpc.user.create.useMutation();
+```
+
+### Type-Safe Fetch Wrapper
+
+```ts
+// lib/api/client.ts
+type ApiResponse<T> = { data: T } | { error: { code: string; message: string } };
+
+async function apiRequest<T>(
+  path: string,
+  options?: RequestInit
+): Promise<T> {
+  const response = await fetch(`/api${path}`, {
+    ...options,
+    headers: {
+      'Content-Type': 'application/json',
+      ...options?.headers,
+    },
+  });
+
+  const json: ApiResponse<T> = await response.json();
+
+  if ('error' in json) {
+    throw new ApiError(json.error.code, json.error.message);
+  }
+
+  return json.data;
+}
+
+// Typed endpoints
+export const api = {
+  users: {
+    list: () => apiRequest<UsersListResponse>('/users'),
+    get: (id: string) => apiRequest<UserResponse>(`/users/${id}`),
+    create: (data: CreateUserRequest) =>
+      apiRequest<UserResponse>('/users', {
+        method: 'POST',
+        body: JSON.stringify(data),
+      }),
+  },
+};
+```
+
+## Versioning
+
+### URL Versioning
+
+```
+/api/v1/users
+/api/v2/users
+```
+
+### Backwards Compatibility
+
+When evolving APIs:
+
+```ts
+// v1 response
+interface UserV1 {
+  id: string;
+  name: string;  // Full name
+}
+
+// v2 response (split name)
+interface UserV2 {
+  id: string;
+  firstName: string;
+  lastName: string;
+  name: string;  // Keep for backwards compatibility
+}
+
+// Transformer for v1 clients
+const toV1Response = (user: UserV2): UserV1 => ({
+  id: user.id,
+  name: user.name,
+});
+```
+
+## Contract Testing
+
+```ts
+// Verify backend implements contract correctly
+describe('Users API Contract', () => {
+  it('POST /users returns valid UserResponse', async () => {
+    const response = await request(app)
+      .post('/users')
+      .send({ email: 'test@example.com', name: 'Test' });
+
+    expect(response.status).toBe(201);
+
+    // Validate against schema
+    const result = UserResponseSchema.safeParse(response.body.data);
+    expect(result.success).toBe(true);
+  });
+
+  it('GET /users returns valid UsersListResponse', async () => {
+    const response = await request(app).get('/users');
+
+    expect(response.status).toBe(200);
+
+    const result = UsersListResponseSchema.safeParse(response.body);
+    expect(result.success).toBe(true);
+  });
+});
+```

package/templates/fullstack/.cursorrules/architecture.md

@@ -0,0 +1,298 @@
+# Fullstack Architecture
+
+Architectural patterns for full-stack applications.
+
+## Architectural Layers
+
+### Presentation Layer (Frontend)
+- Components and pages
+- State management
+- User interactions
+- Client-side routing
+
+### Application Layer (API)
+- Route handlers
+- Request validation
+- Authentication/authorization
+- Response formatting
+
+### Domain Layer (Business Logic)
+- Business rules
+- Domain models
+- Use cases/services
+- Pure functions
+
+### Infrastructure Layer
+- Database access
+- External API clients
+- File storage
+- Caching
+
+## Layer Boundaries
+
+### Dependency Direction
+
+Dependencies should point inward (toward domain):
+
+```
+Presentation → Application → Domain ← Infrastructure
+```
+
+### Example
+
+```ts
+// Domain layer (no dependencies on outer layers)
+// domain/user.ts
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+
+export interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  create(data: CreateUserInput): Promise<User>;
+}
+
+export const createUser = async (
+  repo: UserRepository,
+  input: CreateUserInput
+): Promise<User> => {
+  // Business logic here
+  const validated = validateUserInput(input);
+  return repo.create(validated);
+};
+
+// Infrastructure layer (implements domain interfaces)
+// infrastructure/userRepository.ts
+import { db } from './db';
+import { UserRepository } from '../domain/user';
+
+export const prismaUserRepository: UserRepository = {
+  findById: (id) => db.user.findUnique({ where: { id } }),
+  create: (data) => db.user.create({ data }),
+};
+
+// Application layer (coordinates domain and infrastructure)
+// api/users.ts
+import { createUser } from '../domain/user';
+import { prismaUserRepository } from '../infrastructure/userRepository';
+
+export const handleCreateUser = async (req, res) => {
+  const result = await createUser(prismaUserRepository, req.body);
+  res.json({ data: result });
+};
+```
+
+## Server Components vs Client Components
+
+### Server Components (Default)
+- Render on server
+- Can access database directly
+- No interactivity
+- No client-side state
+
+```tsx
+// app/users/page.tsx (Server Component)
+import { db } from '@/lib/server/db';
+
+export default async function UsersPage() {
+  const users = await db.user.findMany();  // Direct DB access
+
+  return (
+    <ul>
+      {users.map(user => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Client Components
+- Run in browser
+- Handle interactivity
+- Manage client state
+- Use hooks
+
+```tsx
+// components/UserForm.tsx
+'use client';
+
+import { useState } from 'react';
+
+export function UserForm({ onSubmit }: { onSubmit: (data: FormData) => void }) {
+  const [name, setName] = useState('');
+
+  return (
+    <form onSubmit={(e) => {
+      e.preventDefault();
+      onSubmit({ name });
+    }}>
+      <input value={name} onChange={(e) => setName(e.target.value)} />
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+### Composition Pattern
+
+```tsx
+// Server component fetches data
+// app/users/[id]/page.tsx
+import { db } from '@/lib/server/db';
+import { UserEditor } from '@/components/UserEditor';
+
+export default async function UserPage({ params }: { params: { id: string } }) {
+  const user = await db.user.findUnique({ where: { id: params.id } });
+
+  if (!user) return <NotFound />;
+
+  return (
+    <div>
+      <h1>Edit User</h1>
+      <UserEditor user={user} />  {/* Client component for interactivity */}
+    </div>
+  );
+}
+```
+
+## API Patterns
+
+### Server Actions (Full-Stack Frameworks)
+
+```tsx
+// app/actions/users.ts
+'use server';
+
+import { db } from '@/lib/server/db';
+import { revalidatePath } from 'next/cache';
+
+export async function createUser(formData: FormData) {
+  const name = formData.get('name') as string;
+  const email = formData.get('email') as string;
+
+  await db.user.create({ data: { name, email } });
+
+  revalidatePath('/users');
+}
+
+// Usage in component
+<form action={createUser}>
+  <input name="name" />
+  <input name="email" type="email" />
+  <button type="submit">Create</button>
+</form>
+```
+
+### API Routes
+
+```ts
+// app/api/users/route.ts
+import { db } from '@/lib/server/db';
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  const users = await db.user.findMany();
+  return NextResponse.json({ data: users });
+}
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  const user = await db.user.create({ data: body });
+  return NextResponse.json({ data: user }, { status: 201 });
+}
+```
+
+## State Synchronization
+
+### Optimistic Updates
+
+```tsx
+'use client';
+
+import { useOptimistic } from 'react';
+
+export function TodoList({ todos, addTodo }: TodoListProps) {
+  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
+    todos,
+    (state, newTodo: Todo) => [...state, newTodo]
+  );
+
+  async function handleAdd(formData: FormData) {
+    const title = formData.get('title') as string;
+
+    // Optimistically add to UI
+    addOptimisticTodo({ id: 'temp', title, completed: false });
+
+    // Then persist to server
+    await addTodo(formData);
+  }
+
+  return (
+    <form action={handleAdd}>
+      <input name="title" />
+      <button type="submit">Add</button>
+      <ul>
+        {optimisticTodos.map(todo => (
+          <li key={todo.id}>{todo.title}</li>
+        ))}
+      </ul>
+    </form>
+  );
+}
+```
+
+### Cache Invalidation
+
+```ts
+// After mutation, invalidate relevant caches
+import { revalidatePath, revalidateTag } from 'next/cache';
+
+export async function updateUser(id: string, data: UpdateUserInput) {
+  await db.user.update({ where: { id }, data });
+
+  // Invalidate specific path
+  revalidatePath(`/users/${id}`);
+
+  // Or invalidate by tag
+  revalidateTag('users');
+}
+```
+
+## Error Handling Across Stack
+
+```tsx
+// Server-side error
+// app/api/users/[id]/route.ts
+export async function GET(request: Request, { params }: { params: { id: string } }) {
+  const user = await db.user.findUnique({ where: { id: params.id } });
+
+  if (!user) {
+    return NextResponse.json(
+      { error: { code: 'NOT_FOUND', message: 'User not found' } },
+      { status: 404 }
+    );
+  }
+
+  return NextResponse.json({ data: user });
+}
+
+// Client-side handling
+// components/UserProfile.tsx
+'use client';
+
+export function UserProfile({ userId }: { userId: string }) {
+  const { data, error, isLoading } = useQuery(['user', userId], () =>
+    fetch(`/api/users/${userId}`).then(res => {
+      if (!res.ok) throw new Error('Failed to fetch user');
+      return res.json();
+    })
+  );
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} />;
+  return <UserCard user={data.data} />;
+}
+```