vertical-professional-services

name	vertical-professional-services
description	Domain-knowledge primer for the professional-services vertical (agencies, consulting firms, creative studios) so architect/pm don't spec naively against PSA incumbents (Scoro, Productive, Accelo, Ruddr, BigTime). Supplies the vocabulary, the non-obvious billing/margin rules, the entities a real proposal/portal/time/profitability product must model, and the per-product wedge. Applied by architect/pm during spec authoring for any of the four products in this vertical — proposals, client-portal, time-invoicing, profitability.
when_to_use	Apply when: - architect is writing ARCH-*.md for a professional-services product (proposals, client-portal, time-invoicing, profitability) - pm is decomposing one of these into tasks and needs to model the domain entities (SOW, retainer, time entry, change order) correctly - any spec touches agency/consulting/studio billing, margin, or scope Do NOT apply for other verticals (home services, restaurants, etc.) — the billing economics here (utilization × realization) are specific.
effort	low
allowed-tools	Read, Write, Grep, Glob
paths	["docs/architecture/**","docs/plans/**","docs/design/**"]

Vertical: professional services — bill time, defend margin, sell the scope

Agencies, consulting firms, and creative studios sell hours and deliverables, not units. Their economics are unintuitive: revenue can rise while margin collapses, and the document that wins the work (the proposal/SOW) is also where margin leaks. Incumbents (Scoro, Productive, Accelo, Ruddr, BigTime — collectively "PSA", professional-services automation) model this correctly; a naive build does not. Spec against the real domain.

1. Domain vocabulary

• SOW (statement of work) — the binding scope: deliverables, timeline, price, terms. It IS the contract and the upsell surface.
• Engagement types: project (fixed scope/price), retainer (recurring fee for a capacity/hours bucket), T&M (time & materials — bill actuals).
• Utilization rate — billable hours ÷ available hours. The first lever of margin.
• Realization rate — billed amount ÷ standard value of hours worked (i.e. how much of what you could bill you actually invoiced and collected). The second lever.
• Billable vs non-billable — every time entry carries this flag; non-billable (admin, sales, rework) is pure cost.
• WIP (work in progress) — unbilled-but-delivered work; revenue earned, not yet invoiced. Agencies carry it for weeks.
• Blended rate — single effective $/hour across a mixed-seniority team on an engagement (vs per-person rate cards).
• Change order — a formal amendment when scope grows; the antidote to scope creep.
• Milestone billing — invoice tied to deliverable acceptance, not the calendar.
• Scope creep — uncompensated work beyond the SOW; the silent margin killer.
• Gross margin per project — (revenue − cost of delivered hours) ÷ revenue, per engagement — not company-wide, not revenue.
• e-signature — legally binding accept on the proposal (ESIGN/UETA, see §6).
• Net-30 terms — payment due 30 days after invoice; drives cash flow and reminders.

2. Non-obvious domain rules

• The proposal/SOW is the contract AND the upsell. It's not a marketing PDF — it's where price, scope, and acceptance live. Optional line items and tiers turn a quote into expansion revenue. Treat it as a revenue surface, not a document export.
• Margin is utilization × realization, not revenue. A firm can grow billings and lose money if people are busy on non-billable work or hours never get invoiced. Profitability must compute margin per engagement, never top-line revenue.
• Retainers need burn-down tracking. A retainer is a bucket of hours/fees that depletes through the month. Without burn-down you over-deliver (margin loss) or under-deliver (churn). Show consumed vs remaining, continuously.
• Agencies live and die on scope creep + change orders. The default human behavior is to "just do it" rather than raise a change order — which silently converts billable work into non-billable. The product must make raising a change order frictionless.
• Time tracking is hated but is the source of truth for billing. No time entry → no defensible invoice → realization drops. The constraint is adoption, not features.

3. What a naive build gets wrong

• Proposal as a static PDF instead of accept-to-pay — losing the e-sign + deposit/first-invoice moment where the deal actually closes and cash starts.
• No change-order flow — scope creep eats margin invisibly because over-delivery is never captured as a billable amendment.
• Time entry so tedious nobody uses it — a 12-field modal per entry kills adoption; with no entries, billing and profitability are both fiction. Timers + one-tap + defaults beat a perfect schema.
• Profitability that shows revenue, not margin — a dashboard of billings is vanity; the firm needs margin per project/retainer with cost-of-hours subtracted.
• Ignoring retainer burn-down — treating a retainer like a flat subscription instead of a depleting bucket misses the entire reason retainers are risky.

4. Must-model entities

Spec these explicitly; they recur across all four products. Build them [[migration-ready-schema]] (stable external IDs, soft-delete, audit timestamps) because agencies switch from incumbents mid-engagement and import open work.

• SOW / Proposal — header (client, engagement type, terms, net-N) + line items (description, qty, rate, optional/tiered flags) + e-signature state (sent → viewed → signed) + accept-to-pay link (deposit or first invoice on acceptance). Status machine: draft → sent → signed → active → closed.
• Retainer — period, committed hours/fee, burn-down (consumed vs remaining), rollover policy, renewal date.
• TimeEntry — who, project/task, duration, billable flag, rate (snapshot at entry time, not a live lookup), billed/unbilled (WIP) status.
• Project — budget (hours and/or fee), engagement type, rate card, computed margin (revenue − cost-of-delivered-hours), milestones.
• ChangeOrder — links to a Project/SOW, delta scope + delta price, its own e-sign/acceptance, and a reason — so scope growth becomes captured revenue.

5. Per-product notes (wedge vs incumbent + the one thing to nail)

• proposals (marketplace-lite) — the wedge. Revenue-adjacent and low switching cost: a firm can adopt it for the next proposal without migrating anything, and it touches money immediately. Incumbents bury proposals inside a heavy PSA suite. Must nail: accept-to-pay — e-sign that flows straight into a deposit/first invoice. See [[vertical-onboarding]]: first activation = first signed, paid proposal.
• client-portal (crud) — wedge: one clean client-facing surface for deliverables, approvals, status, and billing, vs incumbents' internal-ops focus. Must nail: approvals as billing triggers — an approved deliverable should be invoiceable (milestone billing), not just a checkbox.
• time-invoicing (crud) — wedge: timers → invoices → reminders with no spreadsheet in between; incumbents make time entry a chore. Must nail: frictionless capture + rate snapshot — adoption is the product; a wrong/stale rate corrupts every downstream invoice and the realization number.
• profitability (dashboard) — wedge: real-time margin, not month-end revenue reporting. Must nail: margin = utilization × realization per engagement, with cost-of-hours subtracted and retainer burn-down surfaced — not a billings chart.

6. Compliance (light)

Keep this proportionate — defer anything money-movement-shaped to the subscription-billing-engineer.

• e-signature validity — ESIGN Act + UETA (US): capture intent-to-sign, consent to electronic records, an audit trail (timestamp, IP, signer identity), and a tamper- evident copy. For EU clients, eIDAS levels apply. This is what makes accept-to-pay legally binding.
• Invoice / tax basics — sequential invoice numbers, required fields, sales-tax/VAT where applicable. Defer the engine (tax calc, payment rails, dunning) to the subscription-billing-engineer; the architecture doc only needs the contract with it.
• 1099 for contractors — agencies pay sub-contractors/freelancers; if the product touches contractor payouts, track payee tax info for 1099-NEC reporting (US). Note it; don't build a payroll system into a proposals tool.

Output

When applied, contribute a Domain model note to the architecture doc capturing: the engagement types in scope (project/retainer/T&M), the must-model entities above that this product owns, the margin definition (utilization × realization, per engagement) if profitability is in scope, and the e-sign/accept-to-pay contract if proposals is in scope.