# Clients View & NavRail Reorganization Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add a Clients management view with billing details and reorder the NavRail into a logical workflow.

**Architecture:** Backend-first approach — migrate the database schema, update Rust structs/queries, expand the TypeScript store, then build the frontend view and update navigation. The Clients.vue view follows the same card-grid + dialog pattern established by Projects.vue.

**Tech Stack:** Tauri v2 (Rust + SQLite), Vue 3 Composition API, Tailwind CSS v4 with @theme tokens, Lucide icons, Pinia stores, vue-router

---

### Task 1: Database migration — add new columns to clients table

**Files:**
- Modify: `src-tauri/src/database.rs:1-118`

**Step 1: Add ALTER TABLE statements after the existing table creation**

After the `CREATE TABLE IF NOT EXISTS clients` block (line 13), add 5 `ALTER TABLE ADD COLUMN` statements. These use `ALTER TABLE ... ADD COLUMN` which is safe to re-run because SQLite will error on duplicate columns — wrap each in a closure that ignores "duplicate column" errors.

Add this code after line 13 (after the `?;` that closes the clients CREATE TABLE):

```rust
// Migrate clients table — add new columns (safe to re-run)
let migration_columns = [
    "ALTER TABLE clients ADD COLUMN company TEXT",
    "ALTER TABLE clients ADD COLUMN phone TEXT",
    "ALTER TABLE clients ADD COLUMN tax_id TEXT",
    "ALTER TABLE clients ADD COLUMN payment_terms TEXT",
    "ALTER TABLE clients ADD COLUMN notes TEXT",
];
for sql in &migration_columns {
    match conn.execute(sql, []) {
        Ok(_) => {}
        Err(e) => {
            let msg = e.to_string();
            if !msg.contains("duplicate column") {
                return Err(e);
            }
        }
    }
}
```

**Step 2: Build to verify migration compiles**

Run: `cd src-tauri && cargo check`
Expected: compiles with no errors

**Step 3: Commit**

```bash
git add src-tauri/src/database.rs
git commit -m "feat: add migration for new client billing columns"
```

---

### Task 2: Expand Rust Client struct and update all CRUD queries

**Files:**
- Modify: `src-tauri/src/commands.rs:6-99` (Client struct + 4 commands)
- Modify: `src-tauri/src/commands.rs:382-457` (export_data)

**Step 1: Expand the Client struct**

Replace the existing `Client` struct (lines 7-12) with:

```rust
#[derive(Debug, Serialize, Deserialize)]
pub struct Client {
    pub id: Option<i64>,
    pub name: String,
    pub email: Option<String>,
    pub address: Option<String>,
    pub company: Option<String>,
    pub phone: Option<String>,
    pub tax_id: Option<String>,
    pub payment_terms: Option<String>,
    pub notes: Option<String>,
}
```

**Step 2: Update `get_clients` query (line 62)**

Replace the SELECT and row mapping:

```rust
let mut stmt = conn.prepare(
    "SELECT id, name, email, address, company, phone, tax_id, payment_terms, notes FROM clients ORDER BY name"
).map_err(|e| e.to_string())?;
let clients = stmt.query_map([], |row| {
    Ok(Client {
        id: Some(row.get(0)?),
        name: row.get(1)?,
        email: row.get(2)?,
        address: row.get(3)?,
        company: row.get(4)?,
        phone: row.get(5)?,
        tax_id: row.get(6)?,
        payment_terms: row.get(7)?,
        notes: row.get(8)?,
    })
}).map_err(|e| e.to_string())?;
```

**Step 3: Update `create_client` INSERT (line 77-80)**

```rust
conn.execute(
    "INSERT INTO clients (name, email, address, company, phone, tax_id, payment_terms, notes) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
    params![client.name, client.email, client.address, client.company, client.phone, client.tax_id, client.payment_terms, client.notes],
).map_err(|e| e.to_string())?;
```

**Step 4: Update `update_client` UPDATE (line 87-89)**

```rust
conn.execute(
    "UPDATE clients SET name = ?1, email = ?2, address = ?3, company = ?4, phone = ?5, tax_id = ?6, payment_terms = ?7, notes = ?8 WHERE id = ?9",
    params![client.name, client.email, client.address, client.company, client.phone, client.tax_id, client.payment_terms, client.notes, client.id],
).map_err(|e| e.to_string())?;
```

**Step 5: Update `export_data` clients query (lines 386-397)**

Replace the clients block inside `export_data`:

```rust
let clients = {
    let mut stmt = conn.prepare("SELECT id, name, email, address, company, phone, tax_id, payment_terms, notes FROM clients").map_err(|e| e.to_string())?;
    let rows: Vec<serde_json::Value> = stmt.query_map([], |row| {
        Ok(serde_json::json!({
            "id": row.get::<_, i64>(0)?,
            "name": row.get::<_, String>(1)?,
            "email": row.get::<_, Option<String>>(2)?,
            "address": row.get::<_, Option<String>>(3)?,
            "company": row.get::<_, Option<String>>(4)?,
            "phone": row.get::<_, Option<String>>(5)?,
            "tax_id": row.get::<_, Option<String>>(6)?,
            "payment_terms": row.get::<_, Option<String>>(7)?,
            "notes": row.get::<_, Option<String>>(8)?
        }))
    }).map_err(|e| e.to_string())?.collect::<Result<Vec<_>, _>>().map_err(|e| e.to_string())?;
    rows
};
```

**Step 6: Build to verify everything compiles**

Run: `cd src-tauri && cargo check`
Expected: compiles with no errors

**Step 7: Commit**

```bash
git add src-tauri/src/commands.rs
git commit -m "feat: expand Client struct with billing fields and update all queries"
```

---

### Task 3: Expand TypeScript Client interface in the Pinia store

**Files:**
- Modify: `src/stores/clients.ts:5-10`

**Step 1: Add new optional fields to the Client interface**

Replace the existing `Client` interface (lines 5-10) with:

```typescript
export interface Client {
  id?: number
  name: string
  email?: string
  address?: string
  company?: string
  phone?: string
  tax_id?: string
  payment_terms?: string
  notes?: string
}
```

No other changes needed — the store's `createClient`, `updateClient`, `fetchClients` all pass/receive `Client` objects, so the new fields flow through automatically.

**Step 2: Verify the frontend builds**

Run: `npm run build`
Expected: builds with no errors

**Step 3: Commit**

```bash
git add src/stores/clients.ts
git commit -m "feat: expand Client interface with billing fields"
```

---

### Task 4: Add /clients route to the router

**Files:**
- Modify: `src/router/index.ts`

**Step 1: Add the clients route**

Insert the clients route between the `/timer` and `/projects` routes (between lines 16 and 17):

```typescript
{
  path: '/clients',
  name: 'Clients',
  component: () => import('../views/Clients.vue')
},
```

The full routes array will now be: `/` (Dashboard), `/timer` (Timer), `/clients` (Clients), `/projects` (Projects), `/entries` (Entries), `/reports` (Reports), `/invoices` (Invoices), `/settings` (Settings).

**Step 2: Commit**

```bash
git add src/router/index.ts
git commit -m "feat: add /clients route"
```

---

### Task 5: Reorder NavRail and add Clients entry

**Files:**
- Modify: `src/components/NavRail.vue`

**Step 1: Add `Users` to the Lucide import**

Replace the import block (lines 6-13) with:

```typescript
import {
  LayoutDashboard,
  Clock,
  Users,
  FolderKanban,
  List,
  BarChart3,
  FileText,
  Settings
} from 'lucide-vue-next'
```

**Step 2: Reorder the navItems array**

Replace the `navItems` array (lines 19-27) with the new workflow order:

```typescript
const navItems = [
  { name: 'Dashboard', path: '/', icon: LayoutDashboard },
  { name: 'Timer', path: '/timer', icon: Clock },
  { name: 'Clients', path: '/clients', icon: Users },
  { name: 'Projects', path: '/projects', icon: FolderKanban },
  { name: 'Entries', path: '/entries', icon: List },
  { name: 'Invoices', path: '/invoices', icon: FileText },
  { name: 'Reports', path: '/reports', icon: BarChart3 },
  { name: 'Settings', path: '/settings', icon: Settings }
]
```

Note: Invoices moved before Reports (bill clients, then analyze).

**Step 3: Verify the frontend builds**

Run: `npm run build`
Expected: builds with no errors (will warn about missing Clients.vue — that's fine, it's lazy-loaded)

**Step 4: Commit**

```bash
git add src/components/NavRail.vue
git commit -m "feat: reorder NavRail and add Clients entry"
```

---

### Task 6: Create Clients.vue — card grid, empty state, and base layout

**Files:**
- Create: `src/views/Clients.vue`

**Step 1: Create the Clients view**

Create `src/views/Clients.vue` following the Projects.vue pattern exactly. The view has:

- Header with "Clients" title and "+ Add" button
- Card grid (1-3 columns responsive) showing: name (bold), company subtitle (if set), email (tertiary)
- Hover reveals edit/delete icons (same SVG icons as Projects.vue)
- Empty state with `Users` icon, "No clients yet" message, and "Create Client" CTA
- Create/Edit dialog with two sections:
  - **Contact Info**: Name (required), Email, Phone, Address (textarea)
  - **Billing Details** (collapsible): Company, Tax ID, Payment Terms, Notes (textarea)
- Delete confirmation dialog (same pattern as Projects)

```vue
<template>
  <div class="p-6">
    <!-- Header -->
    <div class="flex items-center justify-between mb-6">
      <h1 class="text-[1.75rem] font-bold font-[family-name:var(--font-heading)] tracking-tight text-text-primary">Clients</h1>
      <button
        @click="openCreateDialog"
        class="px-3 py-1.5 bg-accent text-bg-base text-xs font-medium rounded-lg hover:bg-accent-hover transition-colors duration-150"
      >
        + Add
      </button>
    </div>

    <!-- Clients Grid -->
    <div v-if="clientsStore.clients.length > 0" class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
      <div
        v-for="client in clientsStore.clients"
        :key="client.id"
        class="group bg-bg-surface border border-border-subtle rounded-lg shadow-[0_1px_3px_rgba(0,0,0,0.3)] hover:bg-bg-elevated transition-all duration-150 cursor-pointer"
        @click="openEditDialog(client)"
      >
        <div class="p-4">
          <div class="flex items-start justify-between">
            <div class="min-w-0 flex-1">
              <h3 class="text-[0.8125rem] font-semibold text-text-primary truncate">{{ client.name }}</h3>
              <p v-if="client.company" class="text-xs text-text-secondary mt-0.5 truncate">{{ client.company }}</p>
              <p v-if="client.email" class="text-xs text-text-tertiary mt-0.5 truncate">{{ client.email }}</p>
            </div>
            <div class="flex items-center gap-1 opacity-0 group-hover:opacity-100 transition-opacity duration-100 shrink-0 ml-2">
              <button
                @click.stop="openEditDialog(client)"
                class="p-1.5 text-text-tertiary hover:text-text-secondary transition-colors duration-150"
                title="Edit"
              >
                <svg xmlns="http://www.w3.org/2000/svg" class="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
                  <path stroke-linecap="round" stroke-linejoin="round" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z" />
                </svg>
              </button>
              <button
                @click.stop="confirmDelete(client)"
                class="p-1.5 text-text-tertiary hover:text-status-error transition-colors duration-150"
                title="Delete"
              >
                <svg xmlns="http://www.w3.org/2000/svg" class="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
                  <path stroke-linecap="round" stroke-linejoin="round" d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" />
                </svg>
              </button>
            </div>
          </div>
        </div>
      </div>
    </div>

    <!-- Empty State -->
    <div v-else class="flex flex-col items-center justify-center py-16">
      <Users class="w-12 h-12 text-text-tertiary" :stroke-width="1.5" />
      <p class="text-sm text-text-secondary mt-4">No clients yet</p>
      <p class="text-xs text-text-tertiary mt-2 max-w-xs text-center">Clients let you organize projects and generate invoices with billing details.</p>
      <button
        @click="openCreateDialog"
        class="mt-4 px-4 py-2 bg-accent text-bg-base text-xs font-medium rounded-lg hover:bg-accent-hover transition-colors"
      >
        Create Client
      </button>
    </div>

    <!-- Create/Edit Dialog -->
    <div
      v-if="showDialog"
      class="fixed inset-0 bg-black/70 backdrop-blur-[4px] flex items-center justify-center z-50"
      @click.self="closeDialog"
    >
      <div class="bg-bg-surface border border-border-subtle rounded-lg shadow-[0_1px_3px_rgba(0,0,0,0.3)] w-full max-w-md mx-4 p-6 animate-modal-enter max-h-[85vh] overflow-y-auto">
        <h2 class="text-[1.125rem] font-semibold font-[family-name:var(--font-heading)] text-text-primary mb-4">
          {{ editingClient ? 'Edit Client' : 'Create Client' }}
        </h2>

        <form @submit.prevent="handleSubmit" class="space-y-4">
          <!-- Contact Info -->
          <div>
            <label class="block text-[0.6875rem] text-text-tertiary uppercase tracking-[0.08em] mb-1.5">Name *</label>
            <input
              v-model="formData.name"
              type="text"
              required
              class="w-full px-3 py-2 bg-bg-inset border border-border-subtle rounded-lg text-[0.8125rem] text-text-primary focus:outline-none focus:border-border-visible"
              placeholder="Client name"
            />
          </div>

          <div>
            <label class="block text-[0.6875rem] text-text-tertiary uppercase tracking-[0.08em] mb-1.5">Email</label>
            <input
              v-model="formData.email"
              type="email"
              class="w-full px-3 py-2 bg-bg-inset border border-border-subtle rounded-lg text-[0.8125rem] text-text-primary focus:outline-none focus:border-border-visible"
              placeholder="client@example.com"
            />
          </div>

          <div>
            <label class="block text-[0.6875rem] text-text-tertiary uppercase tracking-[0.08em] mb-1.5">Phone</label>
            <input
              v-model="formData.phone"
              type="tel"
              class="w-full px-3 py-2 bg-bg-inset border border-border-subtle rounded-lg text-[0.8125rem] text-text-primary focus:outline-none focus:border-border-visible"
              placeholder="+1 (555) 000-0000"
            />
          </div>

          <div>
            <label class="block text-[0.6875rem] text-text-tertiary uppercase tracking-[0.08em] mb-1.5">Address</label>
            <textarea
              v-model="formData.address"
              rows="2"
              class="w-full px-3 py-2 bg-bg-inset border border-border-subtle rounded-lg text-[0.8125rem] text-text-primary focus:outline-none focus:border-border-visible resize-none"
              placeholder="Street, City, State, ZIP"
            />
          </div>

          <!-- Billing Details (collapsible) -->
          <div class="border-t border-border-subtle pt-4">
            <button
              type="button"
              @click="billingOpen = !billingOpen"
              class="flex items-center gap-2 text-[0.6875rem] text-text-tertiary uppercase tracking-[0.08em] cursor-pointer hover:text-text-secondary transition-colors"
            >
              <svg
                xmlns="http://www.w3.org/2000/svg"
                class="h-3 w-3 transition-transform duration-150"
                :class="{ 'rotate-90': billingOpen }"
                fill="none"
                viewBox="0 0 24 24"
                stroke="currentColor"
                stroke-width="2"
              >
                <path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7" />
              </svg>
              Billing Details
            </button>

            <div v-if="billingOpen" class="mt-3 space-y-4">
              <div>
                <label class="block text-[0.6875rem] text-text-tertiary uppercase tracking-[0.08em] mb-1.5">Company</label>
                <input
                  v-model="formData.company"
                  type="text"
                  class="w-full px-3 py-2 bg-bg-inset border border-border-subtle rounded-lg text-[0.8125rem] text-text-primary focus:outline-none focus:border-border-visible"
                  placeholder="Business name for invoices"
                />
              </div>

              <div>
                <label class="block text-[0.6875rem] text-text-tertiary uppercase tracking-[0.08em] mb-1.5">Tax ID</label>
                <input
                  v-model="formData.tax_id"
                  type="text"
                  class="w-full px-3 py-2 bg-bg-inset border border-border-subtle rounded-lg text-[0.8125rem] text-text-primary focus:outline-none focus:border-border-visible"
                  placeholder="VAT / Tax number"
                />
              </div>

              <div>
                <label class="block text-[0.6875rem] text-text-tertiary uppercase tracking-[0.08em] mb-1.5">Payment Terms</label>
                <input
                  v-model="formData.payment_terms"
                  type="text"
                  class="w-full px-3 py-2 bg-bg-inset border border-border-subtle rounded-lg text-[0.8125rem] text-text-primary focus:outline-none focus:border-border-visible"
                  placeholder="e.g. Net 30, Due on receipt"
                />
              </div>

              <div>
                <label class="block text-[0.6875rem] text-text-tertiary uppercase tracking-[0.08em] mb-1.5">Notes</label>
                <textarea
                  v-model="formData.notes"
                  rows="2"
                  class="w-full px-3 py-2 bg-bg-inset border border-border-subtle rounded-lg text-[0.8125rem] text-text-primary focus:outline-none focus:border-border-visible resize-none"
                  placeholder="Internal notes about this client"
                />
              </div>
            </div>
          </div>

          <!-- Buttons -->
          <div class="flex justify-end gap-3 pt-4">
            <button
              type="button"
              @click="closeDialog"
              class="px-4 py-2 border border-border-subtle text-text-secondary rounded-lg hover:bg-bg-elevated transition-colors duration-150"
            >
              Cancel
            </button>
            <button
              type="submit"
              class="px-4 py-2 bg-accent text-bg-base font-medium rounded-lg hover:bg-accent-hover transition-colors duration-150"
            >
              {{ editingClient ? 'Update' : 'Create' }}
            </button>
          </div>
        </form>
      </div>
    </div>

    <!-- Delete Confirmation Dialog -->
    <div
      v-if="showDeleteDialog"
      class="fixed inset-0 bg-black/70 backdrop-blur-[4px] flex items-center justify-center z-50"
      @click.self="cancelDelete"
    >
      <div class="bg-bg-surface border border-border-subtle rounded-lg shadow-[0_1px_3px_rgba(0,0,0,0.3)] w-full max-w-sm mx-4 p-6 animate-modal-enter">
        <h2 class="text-[1.125rem] font-semibold font-[family-name:var(--font-heading)] text-text-primary mb-2">Delete Client</h2>
        <p class="text-[0.75rem] text-text-secondary mb-6">
          Are you sure you want to delete "{{ clientToDelete?.name }}"? This action cannot be undone.
        </p>
        <div class="flex justify-end gap-3">
          <button
            @click="cancelDelete"
            class="px-4 py-2 border border-border-subtle text-text-secondary rounded-lg hover:bg-bg-elevated transition-colors duration-150"
          >
            Cancel
          </button>
          <button
            @click="handleDelete"
            class="px-4 py-2 border border-status-error text-status-error font-medium rounded-lg hover:bg-status-error/10 transition-colors duration-150"
          >
            Delete
          </button>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, reactive, onMounted, computed } from 'vue'
import { Users } from 'lucide-vue-next'
import { useClientsStore, type Client } from '../stores/clients'

const clientsStore = useClientsStore()

// Dialog state
const showDialog = ref(false)
const showDeleteDialog = ref(false)
const editingClient = ref<Client | null>(null)
const clientToDelete = ref<Client | null>(null)
const billingOpen = ref(false)

// Form data
const formData = reactive<Client>({
  name: '',
  email: undefined,
  phone: undefined,
  address: undefined,
  company: undefined,
  tax_id: undefined,
  payment_terms: undefined,
  notes: undefined,
})

// Check if any billing field has data
function hasBillingData(client: Client): boolean {
  return !!(client.company || client.tax_id || client.payment_terms || client.notes)
}

// Open create dialog
function openCreateDialog() {
  editingClient.value = null
  formData.name = ''
  formData.email = undefined
  formData.phone = undefined
  formData.address = undefined
  formData.company = undefined
  formData.tax_id = undefined
  formData.payment_terms = undefined
  formData.notes = undefined
  billingOpen.value = false
  showDialog.value = true
}

// Open edit dialog
function openEditDialog(client: Client) {
  editingClient.value = client
  formData.id = client.id
  formData.name = client.name
  formData.email = client.email
  formData.phone = client.phone
  formData.address = client.address
  formData.company = client.company
  formData.tax_id = client.tax_id
  formData.payment_terms = client.payment_terms
  formData.notes = client.notes
  billingOpen.value = hasBillingData(client)
  showDialog.value = true
}

// Close dialog
function closeDialog() {
  showDialog.value = false
  editingClient.value = null
}

// Handle form submit
async function handleSubmit() {
  if (editingClient.value) {
    await clientsStore.updateClient({ ...formData })
  } else {
    await clientsStore.createClient({ ...formData })
  }
  closeDialog()
}

// Confirm delete
function confirmDelete(client: Client) {
  clientToDelete.value = client
  showDeleteDialog.value = true
}

// Cancel delete
function cancelDelete() {
  showDeleteDialog.value = false
  clientToDelete.value = null
}

// Handle delete
async function handleDelete() {
  if (clientToDelete.value?.id) {
    await clientsStore.deleteClient(clientToDelete.value.id)
  }
  cancelDelete()
}

// Load data on mount
onMounted(async () => {
  await clientsStore.fetchClients()
})
</script>
```

**Step 2: Verify the full app builds**

Run: `npm run build`
Expected: builds with no errors

**Step 3: Commit**

```bash
git add src/views/Clients.vue
git commit -m "feat: add Clients view with card grid, create/edit dialog, and billing details"
```

---

### Task 7: Build and verify end-to-end

**Step 1: Full Tauri build check**

Run: `cd src-tauri && cargo check`
Expected: compiles with no errors

Run: `cd .. && npm run build`
Expected: builds with no errors

**Step 2: Verify no regressions**

Grep for any remaining references to the old nav order or missing imports:

Run: `grep -r "Users" src/components/NavRail.vue` — should find the Lucide import
Run: `grep -r "clients" src/router/index.ts` — should find the route

**Step 3: Commit all together (if any fixups needed)**

```bash
git add -A
git commit -m "feat: complete Clients view and NavRail reorganization"
```