TimeTracker/docs/competitive-analysis/PHASE_1_PRD.md

# Phase 1 PRD: Freelancer-Critical Gaps

**Version:** 1.0  
**Status:** Draft  
**Audience:** Individuals and freelancers (primary); small teams (secondary).  
**Related:** [GAP_RUBRIC.md](GAP_RUBRIC.md), Competitive Feature Gap Analysis plan.

---

## 1. Purpose and Goals

Phase 1 closes the highest-impact gaps for freelancers and small teams by:

1. **Timesheet period close** — Formal submit/approve/close workflow so time is locked by period and ready for billing/payroll.
2. **Payroll-ready exports and payroll connectors** — Structured exports and optional integrations so users can hand off data to payroll or accounting without manual rework.
3. **Mobile and desktop parity for invoicing, expenses, and reporting** — Core cash-flow actions (invoices, expenses, basic reports) available in mobile and desktop apps, not only on the web.

Success is measured by: reduced time-to-invoice, fewer support requests about “how do I get my data to payroll?”, and increased use of mobile/desktop for invoicing and expenses.

---

## 2. Scope

### In scope

- Timesheet period model and period-based submit/approve/close workflow (with locking).
- Payroll-ready export formats (e.g. CSV/Excel with required fields and optional templates).
- At least one payroll or accounting connector (e.g. export format accepted by a major payroll provider, or sync to QuickBooks/Xero for payroll-related data).
- Mobile app: list/create/edit invoices; list/add expenses; view a basic time/revenue report.
- Desktop app: same as mobile (list/create/edit invoices; list/add expenses; basic report view).
- API support for all new period and export behaviors so mobile/desktop can use them.

### Out of scope for Phase 1

- Full accounting reconciliation or double-entry.
- PTO/leave and time-off (Phase 2).
- Automated activity capture / desktop timeline (backlog).
- Geofencing or field workforce controls (backlog).

### Optional Phase 1 quick wins (from rubric)

- **Focus mode packaging:** Defaults and onboarding that emphasize timer + quick log + invoice for solo users.
- **Mileage GPS UI:** Expose existing GPS mileage backend via routes and UI (start/stop track, create expense from track).

---

## 3. User Stories and Requirements

### 3.1 Timesheet period close

| ID | Role | Story | Acceptance criteria |
|----|------|--------|---------------------|
| T1 | User | As a user, I can submit my time for a given period (e.g. week) so that it is ready for approval. | User selects a period (e.g. week); system validates entries are complete (e.g. no open timer); user submits; period moves to “submitted”. |
| T2 | Approver | As an approver, I can approve or reject a submitted timesheet with a comment. | Approver sees list of submitted periods; can approve or reject with optional comment; submitter is notified. |
| T3 | Admin | As an admin, I can close a period so that no further edits are allowed. | Once closed, time entries in that period are locked (no add/edit/delete); configurable by period type (e.g. weekly/monthly). |
| T4 | User | As a user, I see clearly which periods are draft, submitted, approved, or closed. | UI and API show period status; filters and reports can use it. |

**Requirements:**

- **Period definition:** Support at least weekly period type (e.g. Mon–Sun or configurable start day). Optional: bi-weekly or monthly.
- **Validation:** Before submit, warn or block if there is an active timer or if required fields (e.g. project) are missing on any entry in the period.
- **Locking:** When a period is closed, entries in that period are read-only. Optional: allow admin override with audit log.
- **Notifications:** Optional email/in-app when period is submitted, approved, or rejected.
- **API:** Endpoints for: list periods, get period status, submit period, approve/reject period, close period (admin). Mobile/desktop use these for period status and submit.

### 3.2 Payroll-ready exports and payroll connectors

| ID | Role | Story | Acceptance criteria |
|----|------|--------|---------------------|
| P1 | User | As a user, I can export my time (or my team’s) in a payroll-ready format. | Export includes: user, period, hours, rate (if applicable), project/cost center, and other fields required by a defined payroll template. |
| P2 | Admin | As an admin, I can choose a payroll export template (e.g. provider-specific format). | At least one template (e.g. generic CSV with standard columns); optional second template for a specific payroll product. |
| P3 | User | As a user, I can export approved time only so I don’t send unapproved data to payroll. | Filter: “approved periods only” or “closed periods only” for export. |
| P4 | User | As a user, I can push time (and optionally expenses) to QuickBooks or Xero for payroll/accounting. | Connector syncs approved/closed time (and optionally expenses) to the connected product; documented limitations and field mapping. |

**Requirements:**

- **Export formats:** CSV and Excel with configurable columns. At least one “payroll” preset: user identifier, name, period start/end, total hours, billable flag, project/code, rate, amount (if applicable).
- **Templates:** Admin can save/select export templates (column set + filters). One template marked as “payroll default”.
- **Approval gating:** Export UI and API support “only approved” or “only closed” periods.
- **Connectors:** Phase 1 delivers at least one of: (a) improved QuickBooks/Xero sync for time (and optionally expenses), or (b) a documented export format that matches a specific payroll provider’s import. Full bidirectional sync is out of scope; one-way export/sync is in scope.
- **API:** Export endpoint (or report endpoint with format=payroll) that returns payroll-ready data for given period and filters.

### 3.3 Mobile and desktop parity (invoicing, expenses, reporting)

| ID | Role | Story | Acceptance criteria |
|----|------|--------|---------------------|
| M1 | User | As a mobile/desktop user, I can list and open my invoices. | List shows key fields (number, client, amount, status); tap/click opens detail. |
| M2 | User | As a mobile/desktop user, I can create and send a new invoice from tracked time. | User selects period/project/entries; system generates draft invoice; user can edit line items and send (email). |
| M3 | User | As a mobile/desktop user, I can list and add expenses. | List with filters; add expense (amount, category, date, receipt photo optional); link to project. |
| M4 | User | As a mobile/desktop user, I can view a simple time or revenue report. | At least one report: time by project or by period, or revenue/billable summary; same date range and filter options as web where feasible. |

**Requirements:**

- **API:** Mobile and desktop consume existing or new API endpoints. Ensure:
  - Invoices: list, get, create, update, “send” (email).
  - Expenses: list, get, create, update; optional file upload for receipt.
  - Reports: time summary and/or revenue summary by period, project, user (permissions apply).
- **UI:** Mobile (Flutter) and desktop (Electron) add screens for: Invoice list and detail; Invoice create/edit; Expense list and add; Report (one summary view). Reuse existing API tokens and auth.
- **Offline:** Optional: cache invoice and expense list for offline viewing; sync when back online. Not required for Phase 1 MVP if time-consuming.
- **Consistency:** Same business rules as web (e.g. who can see which invoices/expenses, rounding, currency).

---

## 4. Non-Functional Requirements

- **Performance:** Period list and export for 1 year of data for a single user complete in < 5 s under normal load.
- **Security:** Period close and approval actions are permission-controlled; export and connector data respect role and scope.
- **Compatibility:** Existing web flows (timer, time entries, invoicing, expenses) continue to work; period close is additive (e.g. optional per workspace or per role).
- **Accessibility:** New web UI meets existing WCAG 2.1 AA expectations; mobile/desktop follow platform guidelines.

---

## 5. Dependencies and Constraints

- **Existing models:** Time entries, projects, users, approvals (per-entry). Period model is new; period status and lock logic are new.
- **Existing API:** `api_v1` time-entries, invoices, expenses, reports. Extend with period endpoints and payroll export.
- **Mobile/desktop:** Current apps use timer, time entries, projects, tasks. Add invoicing, expenses, and one report; reuse existing auth and API client patterns.
- **Integrations:** QuickBooks and Xero connectors exist; extend for time (and optionally expenses) sync if chosen for Phase 1.

---

## 6. Success Metrics (Targets)

- **Adoption:** X% of active workspaces use at least one of: period submit, payroll export, or mobile/desktop invoice or expense action within 3 months of release (target TBD).
- **Support:** Reduction in “how do I export for payroll?” and “can I invoice from the app?” type tickets.
- **Usage:** Increase in mobile/desktop share of invoice and expense creation (measure via API or analytics if available).

---

## 7. Open Questions

- Period type: weekly only for MVP or also bi-weekly/monthly?
- Payroll connector: prioritize QuickBooks/Xero time sync vs. a specific payroll vendor CSV format?
- Mobile receipt upload: use existing attachment API or new endpoint?

---

## 8. Appendix: Optional Quick Wins

- **Focus mode:** Default dashboard and onboarding path for “solo freelancer”: timer, quick log, “Create invoice from time” and “Add expense” prominent; hide or de-emphasize CRM/inventory for this mode.
- **Mileage GPS UI:** Expose `GPSTrackingService` and `MileageTrack` via REST routes and a simple web UI (start/stop track, create expense from track). Mobile can call same API later.

These can be scheduled in Phase 1 if capacity allows, or immediately after the three main pillars.