zeroclock/docs/plans/2026-02-17-clients-view-navrail-reorg-implementation.md

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):

// 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

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:

#[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:

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)

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)

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:

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

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:

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

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):

{
  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

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:

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:

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

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)

<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

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)

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