# Project Instructions

> Auto-generated from detected stack. Update as your project evolves.
> This file takes precedence over skill defaults for project-specific patterns.

---

## Tech Stack

<!-- Auto-filled from detection. Update versions as needed. -->

- **Framework:** {{framework}}
- **Database:** {{database}}
- **Auth:** {{auth}}
- **Styling:** {{styling}}
- **Language:** TypeScript (strict mode)

---

## Active Skills

<!-- Skills installed based on detected stack -->

{{#each skills}}

- `{{this}}` - See `.claude/skills/{{this}}/SKILL.md`
  {{/each}}

---

## Project-Specific Patterns

### Established Conventions

<!-- Add patterns discovered during development -->

```typescript
// Example: API response format
type ApiResponse<T> = {
  data: T;
  error?: string;
  meta?: { page: number; total: number };
};
```

### File Organization

<!-- Document your project's structure conventions -->

```
src/
├── app/              # Next.js App Router pages
├── components/       # Shared UI components
│   ├── ui/          # Primitives (Button, Input, etc.)
│   └── features/    # Feature-specific components
├── lib/             # Utilities and helpers
├── hooks/           # Custom React hooks
└── types/           # TypeScript type definitions
```

### Naming Conventions

<!-- Project-specific naming rules -->

- Components: PascalCase (`UserProfile.tsx`)
- Hooks: camelCase with `use` prefix (`useAuth.ts`)
- Utilities: camelCase (`formatDate.ts`)
- Types: PascalCase with descriptive suffix (`UserResponse`, `CreateUserInput`)

---

## Decisions & Rationale

<!-- Link to ADRs or explain key architectural choices -->

| Decision                         | Rationale                                | Date     |
| -------------------------------- | ---------------------------------------- | -------- |
| Use Server Components by default | Better performance, simpler mental model | {{date}} |
| Convex for real-time             | Built-in subscriptions, type safety      | {{date}} |

---

## Anti-Patterns for This Project

<!-- Things that don't work well in YOUR specific codebase -->

### Don't Do This

```typescript
// ❌ Don't use client-side data fetching for initial data
'use client';
useEffect(() => { fetch('/api/data')... }, []);

// ✓ Fetch in Server Component instead
async function Page() {
  const data = await getData();
  return <ClientComponent initialData={data} />;
}
```

### Avoid These Patterns

- Don't create new API routes when direct DB access works
- Don't use Context for data that should come from Server Components
- Don't add `'use client'` unless interactivity is needed

---

## Skill Overrides

<!-- Override specific skill recommendations for this project -->

### nextjs

<!-- Example: Override default caching strategy -->

```typescript
// This project uses shorter cache times due to real-time requirements
cacheLife("seconds"); // Instead of skill default 'hours'
```

### convex

<!-- Example: Project-specific schema conventions -->

```typescript
// All tables must include audit fields
defineTable({
  // ... fields
  createdAt: v.number(),
  updatedAt: v.number(),
  createdBy: v.optional(v.id("users")),
});
```

---

## Environment Variables

<!-- Document required env vars for this project -->

| Variable              | Purpose                 | Required |
| --------------------- | ----------------------- | -------- |
| `DATABASE_URL`        | Database connection     | Yes      |
| `NEXT_PUBLIC_API_URL` | Public API endpoint     | Yes      |
| `AUTH_SECRET`         | Auth session encryption | Yes      |

---

## Testing Patterns

<!-- Project-specific testing conventions -->

```typescript
// Test file naming: *.test.ts or *.spec.ts
// Test location: Co-located with source files

// Example test structure
describe("UserService", () => {
  it("creates a user with valid data", async () => {
    // Arrange
    const input = { name: "Test", email: "test@example.com" };

    // Act
    const result = await createUser(input);

    // Assert
    expect(result.id).toBeDefined();
  });
});
```

---

_Last updated: {{date}}_
_FlyDocs version: 6.3.0_