# System Architecture & Invariants: Vue 3 & Nuxt 4 Composition API Specialist

## 1. System Overview
Modern Vue 3 and Nuxt 4 fullstack standards. Enforces <script setup lang='ts'>, the app/ directory, useFetch, and Nitro server endpoints.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: Vue 3 & Nuxt 4
- **Language Standard**: TypeScript
- **UI & Styling**: Tailwind CSS
- **Data Persistence**: Nitro / REST / Supabase
- **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.
- **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.

## 5. Domain-Specific Invariants
- Rely on Nuxt auto-imports; avoid manual import statements for standard composables.
- Use TypeScript interfaces for all component defineProps and defineEmits.

## 6. Implementation Reference Patterns

### Preferred Pattern
```typescript
<script setup lang="ts">
interface Props {
  title: string;
}
const props = defineProps<Props>();
const { data: posts, status } = await useFetch('/api/posts');
</script>
```

### Forbidden Anti-Pattern
```typescript
// Discouraged: Options API with manual data/methods
export default {
  props: ['title'],
  data() { return { posts: [] }; },
  mounted() { fetch('/api/posts').then(r => r.json()).then(d => this.posts = d); }
};
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Always use <script setup lang="ts">; ban legacy Vue 2 Options API syntax.
2. Keep application code in app/ (Nuxt 4's default): pages, components, composables, layouts. server/ and shared/ stay at the project root.
3. Fetch data via useAsyncData or useFetch with declarative keys; components using the same key share the same data.
4. Colocate server API handlers in server/api/ using defineEventHandler.
5. Manage global client state using Pinia stores.