create-odoo-pwa

What this skill does

# Create Odoo PWA Application

Generate a production-ready Progressive Web App with Odoo Studio backend, featuring offline-first architecture, smart caching, and automatic synchronization.

## Before You Start

This skill generates a complete PWA project following proven architectural patterns:
- **Three-layer data flow**: Component → Cache Store → API Client → Server Route → Odoo
- **Offline-first**: IndexedDB/localStorage with background sync
- **Smart caching**: Incremental fetch, stale detection, optimistic updates
- **PWA-ready**: Service workers, manifest, installable

## Required User Input

Ask the user for the following information before generating:

1. **Project name** (required)
   - Format: kebab-case (e.g., "inventory-tracker", "expense-manager")
   - Used for directory name and package.json

2. **Framework** (required)
   - Options: `sveltekit` (recommended), `react`, `vue`
   - Default: sveltekit if not specified

3. **Primary Odoo model** (required)
   - The main custom model name WITHOUT the `x_` prefix
   - Example: If Odoo model is `x_inventory`, user provides: `inventory`
   - Will automatically add `x_` prefix in code

4. **Model display name** (required)
   - Human-readable singular name (e.g., "Inventory Item", "Expense")

5. **Deployment target** (optional)
   - Options: `vercel`, `github-pages`, `cloudflare`, `netlify`
   - Default: vercel if not specified

## Generation Steps

### Step 1: Project Initialization

Create the project directory and initialize the structure:

```bash
mkdir {{PROJECT_NAME}}
cd {{PROJECT_NAME}}
```

Generate the appropriate structure based on framework:
- **SvelteKit**: Use SvelteKit 2.x structure with `src/` directory
- **React**: Use Vite + React structure
- **Vue**: Use Vite + Vue structure

### Step 2: Base Configuration Files

Generate these files using templates from `skills/create-odoo-pwa/templates/{{FRAMEWORK}}/base/`:

#### For SvelteKit:
- `package.json` - Dependencies including @sveltejs/kit, @vite-pwa/sveltekit, @sveltejs/adapter-static
- `svelte.config.js` - SvelteKit configuration with adapter-static
- `vite.config.js` - Vite + PWA plugin configuration
- `jsconfig.json` or `tsconfig.json` - Path aliases and compiler options

#### For React:
- `package.json` - Dependencies including React 18, Vite, vite-plugin-pwa
- `vite.config.js` - React + PWA plugin configuration
- `tsconfig.json` - TypeScript configuration

#### For Vue:
- `package.json` - Dependencies including Vue 3, Vite, vite-plugin-pwa
- `vite.config.js` - Vue + PWA plugin configuration
- `tsconfig.json` - TypeScript configuration

### Step 3: Environment and Git Configuration

Create `.env.example`:
```env
# Odoo Instance Configuration
ODOO_URL=https://your-instance.odoo.com
ODOO_DB=your-database-name
ODOO_USERNAME=your-username
ODOO_API_KEY=your-api-key

# Primary Model (use x_ prefix)
ODOO_PRIMARY_MODEL=x_{{MODEL_NAME}}

# Optional: For static hosting (GitHub Pages, etc.)
PUBLIC_API_URL=
```

Create `.gitignore`:
```
node_modules/
.env
dist/
build/
.svelte-kit/
.vercel/
.DS_Store
*.log
```

### Step 4: Core Library Files

Generate these essential files from templates:

#### A. Odoo API Client (`src/lib/odoo.js`)
Features:
- API URL configuration (supports PUBLIC_API_URL for static hosts)
- `callApi(action, data)` - Core API communication
- `createRecord(model, fields)` - Create records
- `searchRecords(model, domain, fields)` - Search/read records
- `updateRecord(model, id, values)` - Update records
- `deleteRecord(model, id)` - Delete records
- `formatMany2one(id)` - Format single relation fields
- `formatMany2many(ids)` - Format multi-relation fields
- Model-specific convenience methods

#### B. IndexedDB Manager (`src/lib/db.js`)
Features:
- Database initialization with versioning
- Store definitions for master data (partners, categories, config)
- CRUD operations: `add()`, `get()`, `getAll()`, `update()`, `remove()`
- Transaction helpers
- Error handling

#### C. Smart Cache Store (`src/lib/stores/{{MODEL_NAME}}Cache.js`)
Features:
- Framework-specific store pattern (Svelte store/React context/Vue composable)
- Dual storage strategy (localStorage for metadata, IndexedDB for master data)
- `initialize()` - Load cache and start background sync
- `sync(forceFullRefresh)` - Incremental sync with Odoo
- `forceRefresh()` - Clear cache and full sync
- Partner name resolution with caching
- Optimistic UI updates
- Stale detection (5-minute cache validity)
- Background sync (3-minute intervals)
- Derived stores for UI states

#### D. Utility Functions (`src/lib/{{MODEL_NAME}}Utils.js`)
Features:
- Business logic calculations
- Data normalization helpers
- Field formatters

### Step 5: Server-Side API Proxy

#### For SvelteKit: `src/routes/api/odoo/+server.js`
Features:
- JSON-RPC client for Odoo
- UID caching to reduce auth calls
- `execute(model, method, args, kwargs)` helper
- POST request handler with actions:
  - `create` - Create new record
  - `search` - Search and read records
  - `search_model` - Search any Odoo model
  - `update` - Update existing record
  - `delete` - Delete record
- Error handling with descriptive messages
- Environment variable access

#### For React/Vue: `src/api/odoo.js` (server endpoint)
Similar functionality adapted to framework conventions

### Step 6: UI Components and Routes

Generate starter components and pages:

#### SvelteKit Routes:
- `src/routes/+layout.svelte` - Root layout with navigation
- `src/routes/+layout.js` - SSR/CSR configuration (ssr: false, csr: true)
- `src/routes/+page.svelte` - Main form for creating records
- `src/routes/list/+page.svelte` - List/table view with filtering
- `src/app.html` - HTML template with PWA meta tags

#### React/Vue Pages:
Equivalent component structure adapted to framework conventions

#### Shared Components:
- `OfflineBanner` - Shows online/offline status
- `SyncStatus` - Displays sync state and last sync time
- `LoadingSpinner` - Loading indicator
- Form components with offline support

### Step 7: PWA Configuration

Generate PWA files:

#### `static/manifest.json` (or `public/manifest.json`):
```json
{
  "name": "{{PROJECT_NAME}}",
  "short_name": "{{PROJECT_NAME}}",
  "description": "{{MODEL_DISPLAY_NAME}} management app",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#667eea",
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}
```

Configure service worker in `vite.config.js`:
- Auto-update strategy
- Cache all static assets
- Offline support

### Step 8: Deployment Configuration

Generate deployment files based on target:

#### Vercel (`vercel.json`):
```json
{
  "buildCommand": "npm run build",
  "outputDirectory": "build",
  "framework": "sveltekit",
  "regions": ["iad1"]
}
```

#### GitHub Pages (`.github/workflows/deploy.yml`):
```yaml
name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v2
        with:
          path: build
```

#### Cloudflare/Netlify:
Generate appropriate configuration files

### Step 9: Documentation

Generate comprehensive documentation:

#### `README.md`:
- Project overview
- Prerequisites (Node.js, Odoo account)
- Installation steps
- Odoo Studio model setup instructions
- Development commands
- Deployment guide
- Architecture overview

#### `CLAUDE.md`:
Complete architecture documentation following the expense-split-pwa pattern:
- Project overview
- Development commands
- Environment setup
- Architecture diagrams
- Key architectural patterns
- Odoo model structure
- Important development notes
- Common gotchas

#### `API.md`:
- Odoo integration patterns
- Available API methods
- Fie