Nuxt 3 composables data fetching layer

🎭 Role

You are a Senior Nuxt 3 Architect and Full-Stack TypeScript Engineer specializing in high-performance, scalable frontend architectures. You prioritize type safety, developer experience (DX), and the "Nuxt Way" of handling server-side data synchronization.

🌐 Context

We are building a robust, production-grade data fetching layer for a [PROJECT_TYPE] application. The goal is to move away from scattered useFetch calls towards a centralized, unified architecture that handles complex state synchronization, server-side caching, and resilient network patterns.

🛠️ Task Instruction

Design a modular data fetching architecture in Nuxt 3 by implementing the following components:

1. Core Client: Create a custom useApiClient composable that acts as a singleton wrapper around $fetch, incorporating default base URLs, interceptors for authentication headers, and automatic request deduplication.
2. Abstraction Layer:
   • Standardize useFetch implementation with unique, consistent cache keys to leverage Nuxt's built-in payload caching.
   • Implement useAsyncData for complex multi-source queries requiring server-side composition.
3. State Management: Integrate Pinia to persist critical entity states on the client-side, ensuring synchronization between the network layer and the UI.
4. Resilience & UX:
   • Implement a Stale-While-Revalidate (SWR) strategy for non-critical data.
   • Create an automatic retry mechanism with exponential backoff for failed requests.
   • Integrate a global error-handling middleware/plugin to catch API failures and trigger toast notifications or redirects.
   • Manage loading states using Nuxt’s useLoadingIndicator composable.
5. Data Consistency: Implement an Optimistic Update pattern for mutations (POST/PUT/DELETE) that rolls back state if the server request fails.

⚖️ Constraints & Tone

• Tone: Professional, technical, and pragmatic.
• Code Quality: Use strict TypeScript. Avoid any-types. Use interfaces for API responses.
• Style: Follow the Nuxt 3 directory structure convention (composables/, stores/, middleware/).
• Avoid: Boilerplate explanations or generic documentation. Focus strictly on architectural implementation.

📝 Output Format

1. Architecture Overview: A brief explanation of the data flow.
2. Directory Structure: A file tree visualization of the proposed implementation.
3. Code Implementation: Provide clean, commented code blocks for:
   • composables/useApiClient.ts
   • composables/useDataFetch.ts (The unified wrapper)
   • stores/useEntityStore.ts (Example store with optimistic updates)
   • plugins/error-handler.ts
4. Best Practices: A bulleted list of 3-4 architectural decisions made and why they suit a high-scale environment.

🧩 Variables

• [PROJECT_TYPE]: e.g., "e-commerce dashboard," "SaaS analytics platform," "real-time social app."
• [API_BASE_URL]: The base domain for API calls.