# System Architecture & Invariants: React 19 + TypeScript SPA Specialist

## 1. System Overview
Modern React 19 SPA standards. Prioritizes custom hooks, TanStack Query for server state caching, Vite bundling, and avoiding redundant useEffect cycles.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: React 19 (Vite)
- **Language Standard**: TypeScript
- **UI & Styling**: Tailwind CSS
- **Data Persistence**: REST / GraphQL API
- **Engineering Philosophy**: modern

## 2. Core Architectural Invariants
- **Feature-Colocated Structure**: Group components, hooks, tests, and utils inside domain feature folders.
- **Guard Clauses & Early Returns**: Exit early from functions to eliminate deeply nested if-else pyramids.
- **Self-Documenting Naming**: Expressive function and variable names over verbose redundant comments.
- **Accessible UI by Default**: Enforce semantic HTML, keyboard navigability, and proper ARIA roles.

## 3. Data Flow & State Management Principles
1. **Unidirectional Data Flow**: State flows top-down; mutations flow through explicit, typed handlers.
2. **Boundary Validation**: External inputs (API payloads, query parameters, environment variables) must be parsed with strict schemas before reaching domain logic.
3. **Surgical Precision**: Diffs must remain minimal and scoped exclusively to the objective. Do not reformat unrelated code.

## 4. Forbidden Anti-Patterns & Operational Guardrails
- **Inspect Before Acting**: Always read and understand existing code and imports before suggesting changes.
- **Minimal Surgical Diffs**: Touch only lines relevant to prompt. Preserve existing comments and formatting.
- **Concise & Direct Tone**: Skip conversational pleasantries. Deliver focused diffs and a short rationale.
- **Preserve Codebase Idioms**: Match existing naming conventions, indentation, and directory patterns.

## 5. Domain-Specific Invariants
- Prefer functional components with named exports.
- Do not use React.FC typing; declare props interface explicitly.
- Extract complex component logic into dedicated custom hooks.

## 6. Implementation Reference Patterns

### Preferred Pattern
```typescript
// Good: Derived state computed directly during render
export function FilteredList({ items, query }: { items: Item[]; query: string }) {
  const filtered = useMemo(
    () => items.filter((item) => item.name.toLowerCase().includes(query.toLowerCase())),
    [items, query]
  );
  return <ul>{filtered.map(item => <li key={item.id}>{item.name}</li>)}</ul>;
}
```

### Forbidden Anti-Pattern
```typescript
// Discouraged: Redundant useEffect triggering cascading re-renders
export function BadFilteredList({ items, query }: any) {
  const [filtered, setFiltered] = useState([]);
  useEffect(() => {
    setFiltered(items.filter((i: any) => i.name.includes(query)));
  }, [items, query]);
  return <ul>{filtered.map((item: any) => <li key={item.id}>{item.name}</li>)}</ul>;
}
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Separate server state (handled via TanStack Query/SWR) from local ephemeral UI state (useState).
2. Avoid redundant useEffect calls; calculate derived state synchronously during render or with useMemo where heavy.
3. Colocate component files: MyComponent.tsx, useMyComponent.ts, MyComponent.test.tsx in the same folder.
4. Use standard semantic HTML tags and test keyboard accessibility for all custom interactive controls.