# Hourly — 1099 Contractor Time Tracker

## Product vision
A mobile-first progressive web app for hourly 1099 contractors to log billable time, manage clients, watch earnings in real time, and generate pretty PDF invoices in seconds. Everything should feel fast enough to use while walking off a job site or between meetings.

## Target user
- Solo 1099 / independent contractor paid by the hour.
- Needs to start/stop a timer quickly, pick a client with one tap, and invoice without bookkeeping overhead.
- Wants to see "how much have I earned so far" at a glance.

## Design language
- **Mobile-first**, desktop as a wider layout of the same app.
- iOS-native aesthetic inspired by the reference images: soft gray background, rounded cards, pill-shaped buttons, lime-green accent, large serif-style numbers.
- Color palette:
  - Background: `#F8FAFC`
  - Surface: `#FFFFFF`
  - Text primary: `#0F2A1D`
  - Text secondary: `#64748B`
  - Accent lime: `#D9F99D` / `#ECFCCB`
  - Accent forest: `#14532D`
  - Accent mint: `#86EFAC`
  - Success/earned: `#14532D`
  - Danger/negative: `#FCA5A5` / `#7F1D1D`
- Typography: Inter for UI, Playfair Display for large dollar balances.
- Iconography: Lucide icons, thin strokes.
- Bottom navigation on mobile, collapsible sidebar on desktop.

## Authentication — 2026 standard
- **Passkey-first** sign up and sign in using WebAuthn (discoverable credentials, platform authenticator preferred).
- **Email + password fallback** for browsers/devices without passkey support.
- Sessions via signed JWT in HTTP-only cookies.
- Graceful degradation: detect `PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()` and show the right primary CTA.
- For local development the RP ID is `localhost`; production should use a real domain with HTTPS.

## Data model
### User
- id, email, fullName, businessName, businessAddress, defaultHourlyRate, taxId (optional), currency, createdAt.

### Client
- id, userId, name, email, address, defaultHourlyRate, accentColor, archived, createdAt.

### TimeEntry
- id, userId, clientId, description, startTime, endTime, durationMinutes, hourlyRate, billable (boolean), status (`logged` | `invoiced` | `paid`), invoiceId, createdAt.

### Invoice
- id, userId, clientId, invoiceNumber, issueDate, dueDate, status (`draft` | `sent` | `paid`), lineItems[], subtotal, taxRate, taxAmount, discount, total, paidAmount, notes, createdAt.

### Session / credential storage (for auth)
- user credentials for passkeys, challenges, refresh tokens.

## Core features

### 1. Sign up / Sign in
- Passkey-first registration (name, email, then create passkey).
- Sign in with passkey; fallback to email/password.
- Option to add/remove passkeys from account settings.

### 2. Dashboard (Home)
- Greeting row: "Hello 👤 [Name]".
- Earnings hero: "You have earned `$XXX.XX` for a balance of `$XXX,XXX.XX`" with a soft wavy earnings chart behind it.
- Running totals: **To be invoiced** vs **Billed in total**.
- Recent time entries list grouped by date.
- Floating action button / quick-action menu: `Start Timer`, `Add Entry`, `Create Invoice`, `Add Client`.

### 3. Timer & fast logging
- One-tap timer: pick client first, optionally add task note, tap Start/Stop.
- Running earnings counter updates live while timer is on.
- Manual entry form for past sessions (client, date, start/end, description, rate).
- Default hourly rate pulled from user or client; editable per entry.
- After stopping a timer, one-tap "Add to invoice" or "Log only".

### 4. Client picker & management
- Searchable client list with color dots.
- Recent clients surfaced first.
- Add client on the fly from timer or invoice screens.
- Client detail: total billed, open invoices, hourly rate.

### 5. Time entries
- List grouped by day; swipe or button to delete.
- Filter by client and status (`unbilled`, `invoiced`, `paid`).
- Select multiple entries to bulk-create an invoice.

### 6. Analytics
- Cards: total earnings, total hours, active clients, average effective hourly rate.
- Bar/area charts:
  - Earnings by day (last 7 days)
  - Earnings by month (last 12 months)
  - Hours by client
- Date range picker (`This week`, `This month`, `This year`, `Custom`).

### 7. Invoices
- Create invoice from selected unbilled time entries; line items auto-generated (`Description | Hours | Rate | Amount`).
- Manual line item support for flat fees / expenses.
- Invoice number auto-incremented (`INV-001`).
- Issue date, due date (default Net 30), notes, tax rate.
- Status toggles: draft → sent → paid.

### 8. Pretty PDF invoice
- Export a clean, brandable PDF with:
  - Your business name, address, email.
  - Client name and address.
  - Invoice number, issue date, due date.
  - Itemized table: date, description, hours, rate, amount.
  - Subtotal, tax, discount, total, balance due.
  - Payment instructions.
  - Soft accent color header band matching brand.

## Tech stack
- **Framework:** Next.js 15 App Router + TypeScript
- **Styling:** Tailwind CSS
- **UI components:** shadcn/ui (Button, Card, Dialog, Input, Select, Tabs, Sheet, Dropdown Menu, Avatar)
- **Charts:** Recharts
- **PDF:** jspdf + jspdf-autotable
- **Auth:** @simplewebauthn/server + @simplewebauthn/browser; bcryptjs fallback
- **Database:** JSON file store via a lightweight `lib/db.ts` helper (for portability; replace with PostgreSQL/SQLite later)
- **Date math:** date-fns
- **Icons:** lucide-react

## Project structure
```
my-app/
  app/
    (auth)/
      login/
      signup/
    (app)/
      layout.tsx       # app shell with bottom nav / sidebar
      page.tsx         # dashboard
      clients/
      entries/
      analytics/
      invoices/
      invoices/new/
      settings/
    api/
      auth/...
      clients/...
      entries/...
      invoices/...
  components/
    ui/                # shadcn components
    dashboard/...
    timer/...
    analytics/...
    invoices/...
  lib/
    db.ts              # file-based JSON store
    auth.ts            # session helpers
    pdf.ts             # invoice PDF generator
    utils.ts
  public/
    logo.svg
  next.config.js
  tailwind.config.ts
```

## Build phases
1. **Scaffold** Next.js + Tailwind + shadcn/ui + dependencies.
2. **Auth** passkey + email/password endpoints and login/signup UI.
3. **Core data** client, time entry, invoice API + UI.
4. **Dashboard** hero, totals, recent entries, quick actions.
5. **Timer + client picker** fast on-the-go logging.
6. **Analytics** stats and charts.
7. **Invoices + PDF** create and download.
8. **Polish** mobile viewport, PWA manifest, splash, animations.

## UX principles
- Every common action should be reachable in ≤ 2 taps from dashboard.
- Default values everywhere (default client, default rate, default due date) so the user can move fast.
- Large tappable targets (≥ 44 × 44 pt), bottom controls for one-handed use.
- Clear status: timer running = active state; unbilled hours = money waiting.
- No dead ends: empty states explain next action.

## Non-goals for MVP
- Bank sync / payment processing.
- Multi-user / teams.
- Native iOS/Android packaging (PWA is the target).
- Tax form generation (earnings data is available for future Schedule C export).