​

SHARED FACTS — the canonical vocabulary for TimeTracker docs

​

1. What the product is

​

2. The object model — say it this way every time

Workspace
 └── has Members (people with a Role)
      └── Members belong to Groups
 └── has Clients (the companies you bill)
      └── Clients have Projects
           └── Projects have Sections
                └── Sections hold Tasks
                     └── Tasks have Estimates, Assignees, Tags, Subtasks
 └── People track Time Entries against a Task or Project
      └── Time Entries roll up into a weekly Timesheet
           └── A Timesheet is Submitted, then Approved
                └── Approved billable time can become an Invoice
                     └── An Invoice receives Payments
 └── Time Entries also consume a Project Budget
      └── Budget + Cost rates produce Profitability

​

3. The seven roles — EXACT names and labels

• Owner is a strict superset of Admin. The ONLY difference is workspace.delete.
• Project Manager and Finance are siblings, not ranked against each other. PM owns delivery; Finance owns money.
• Client has an empty capability set. A portal contact sees only what is explicitly shared with their client company.

​

4. Capabilities — the 66 named permissions

• Workspace: workspace.updateSettings, workspace.delete
• People: member.invite, member.create, member.changeRole, member.remove, role.manage, invite.revoke, group.manage, audit.read
• Clients: client.view, client.manage
• Projects & tasks: project.manage, tag.manage, task.create, task.edit, task.delete, task.reviseEstimate, task.bulkEdit
• Rates: rate.manage, rate.viewBilling, rate.viewCost
• Time: time.track, time.edit, time.viewCost, time.submit, time.approve, time.adjust, period.close, time.viewOthers, time.editOthers, time.submitOnBehalf, time.reopenApproval, time.remind
• Money: budget.manage, invoice.manage, payment.record
• Expenses: expense.submit, expense.approve, expenseCategory.manage
• Time off: leave.request, leave.approve, leave.viewOthers, leave.managePolicy
• Reports: report.view, report.create, report.edit, report.manage, report.share, report.schedule, report.export
• Time clock: timecard.clock, timecard.view, timecard.manage, timecard.approve, timecard.submit, timecard.submitOnBehalf, timecard.reopen
• Planner: block.manage, block.manageOthers
• Admin & integrations: webhook.manage, data.export, billing.manage, location.manage, schedule.view, schedule.manage

1. A capability is not a scope. time.viewOthers says you MAY view other people’s time. Supervision scope says WHOSE time. A manager with time.viewOthers still only sees the people in their scope. Always separate the two.
2. Owner-only actions cannot be granted to anyone else, and some actions are deny-only overridable per person. Do not promise a capability can be freely moved between roles without checking OVERRIDABLE_ACTIONS and OWNER_EXCLUSIVE_ACTIONS in src/modules/workspace/domain/permissions.ts.

​

5. Apps (modules) — the 15 togglable areas

​

6. Plans — Free and Pro

• Free = record your work. Anyone can track time, fill a timesheet, submit an expense, request leave, and clock in and out.
• Pro = resolve it. Only a paying workspace can APPROVE any of it, invoice it, or take it out of the product as a file.

​

7. Statuses — the exact sets

• draft → sent, void
• sent → viewed, partially_paid, paid, overdue, void
• viewed → partially_paid, paid, overdue, void
• partially_paid → paid, overdue, void
• overdue → partially_paid, paid, void
• paid and void are terminal.

​

8. Terms readers confuse — always disambiguate

​

9. The example cast — REUSE THESE across every page

• Sarah Lin billable rate: $100/hour**. Cost rate: **$45/hour.
• Jonas Bergman billable rate: $120/hour**. Cost rate: **$60/hour.
• Ana Ferreira (contractor) billable rate: $80/hour**. Cost rate: **$55/hour.
• Workspace currency: USD.
• A standard week is 40 hours, Monday to Friday, 9:00–17:00.

Sarah tracks 3 hours on “Homepage wireframes” for Bluebird Coffee — Website Redesign. Her billable rate is $100/hour, so the entry is worth **$300** to the project. Her cost rate is $45/hour, so it costs Northwind **$135**. The margin on those 3 hours is $165.

​

10. Voice and writing rules

• Reading level: 8th grade. Short sentences. Simple words. One idea per sentence.
• Second person. “You create a project.” Not “the user creates a project.”
• Present tense. “The timer stops.” Not “the timer will stop.”
• Say the outcome first, then the steps.
• En dash (–) only. Never an em dash. Never a hyphen used as a separator.
• Never say “simply”, “just”, “easy”, “obviously”.
• Never invent UI. If you did not see the button in the source, do not describe it.
• Every number must be arithmetically correct. Check your maths.
• Use bold for UI labels: click Save. Use code for values and keys.
• Prefer a short table over a long paragraph.
• Paragraphs are 1–3 sentences. Never a wall of text.

• Biometric attendance devices (eSSL / ZKTeco) — a private client-specific module
• convex/lib/customModules.ts and any custom module
• The v1 → v3 migration tooling
• The /dev/emails route
• Internal architecture, Convex function names, file paths, or the tech stack. These are USER docs. A reader never sees a table name.

​

11. Mintlify page format

---
title: "How to approve a timesheet"
description: "Review a submitted timesheet, approve or reject it, and understand what happens to the time once it is locked."
---

• title — matches real search intent. Sentence case. Under 60 characters.
• description — 120–160 characters, useful to a human AND a search engine. Never keyword stuffing. It is the meta description.

<Steps>
  <Step title="Open the project">Go to **Projects** and pick the project.</Step>
  <Step title="Set the budget">Click **Budget**, then enter the amount.</Step>
</Steps>

<Note>Useful aside.</Note>
<Tip>A better way to do something.</Tip>
<Warning>Something that loses data or money.</Warning>
<Info>Neutral context.</Info>

<CardGroup cols={2}>
  <Card title="Billable rates" icon="dollar-sign" href="/rates/billable-rates">
    What you charge a client per hour.
  </Card>
</CardGroup>

<AccordionGroup>
  <Accordion title="Can I approve my own timesheet?">Answer.</Accordion>
</AccordionGroup>

<Tabs>
  <Tab title="Owner">…</Tab>
  <Tab title="Member">…</Tab>
</Tabs>

1. One or two sentences answering the reader’s question immediately.
2. ## What is X? — plain definition.
3. ## When to use it — realistic situations.
4. ## How it works — the concept.
5. ## How to <do the thing> — <Steps>.
6. ## Example — use the cast from section 9.
7. ## Options and settings — every field and control.
8. ## Permissions — which roles and capabilities.
9. ## What happens next — downstream effects.
10. ## Common questions — <AccordionGroup>, real search questions.
11. ## Troubleshooting — real problems.
12. ## Related guides — internal links.

​

11a. Corrections found while writing — DO NOT regress these

• The slug cannot be renamed. No mutation writes it after creation. Renaming the workspace does not change the URL, which is why old links keep working. Never warn a reader to “change it early”.
• There is no self-service “leave workspace” control. Someone with member.remove removes you, or you delete your account.
• Editable workspace settings are exactly: name, base currency, timezone, date format, time format, week start, trash retention, timesheet period, invoice sender.

• There is no workspace default rate. The resolver has a fifth tier but nothing ever supplies it. The real chain is task → project member → person → client, then unresolved. A missing rate is unpriced, never $0.
• Cost rates have exactly one tier: the person.
• Finance holds no rate capabilities at all – no rate.manage, no rate.viewBilling, no rate.viewCost – yet holds invoice.manage and payment.record. Counter-intuitive, and true.

• ACTIONS is 66. The role editor shows ~62 checkboxes because owner-exclusive and non-assignable actions are not offered. Say 66 for capabilities, and explain the editor’s count where it appears.
• Only Owner and Client are locked. Admin, Project Manager, Finance, Member and Contractor are editable, renameable and deletable despite their System badge.
• Supervision scope has five levels: none, project, group, project_group, workspace. Only workspace widens PROJECT reach; the middle three differ only in which PEOPLE you reach.
• Per-person exceptions are subtractive only, and today the only exposed switch is Clock in and out. OVERRIDABLE_ACTIONS is a per-project grant for task.reviseEstimate – the opposite of a deny. Do not describe it as one.
• You see a client only when you can see one of their projects. There is no client scope.

• Timesheets have two layers: the entry chain (draft → submitted → approved → locked → invoiced) and the submission aggregate (submitted / approved / changes_requested / withdrawn). rejected is derived, never stored. Rejecting and reopening both land on changes_requested.
• Leave has a fourth status, withdrawn, alongside pending / approved / rejected.
• Nothing sets an invoice to viewed or overdue. Only send, void and payment re-derivation move an invoice. Document the transition table, but say so honestly.

• Trial is 14 days, granted per person on their first workspace.
• past_due has a 7-day grace period, then Free.
• Trash retention is selectable: 7 / 14 / 30 / 60 / 90 days, default 30.

• There is no full-page Inbox – the bell popover is the whole surface (50 rows, badge caps at 99+).
• /settings/notifications is the workspace defaults page. Personal settings live on the profile.
• Digests have no user-facing control. Do not invent a toggle. Quiet hours are gone.

• No bulk importer exists (no CSV, no Toggl/Clockify/Harvest).
• No project templates reachable in the UI.
• No workspace FX-rate screen – only the per-invoice exchange-rate section.
• Invoice Terms/Notes are stored but never rendered.
• Auto-create time entries on leave policies and holidays is not wired to time entries.

​

12. Accuracy contract

• Read the actual page component under src/app/[workspaceSlug]/… for what is on screen.
• Read src/modules/<domain>/ui/ for the forms, fields, filters and dialogs.
• Read src/modules/<domain>/domain/ for the rules, states and maths.
• Query the graph for a fast orientation: node .build/graph.mjs tag <tag>.