Floorwise — product and configuration proposal

Version 0.2 · 24 October 2026 · Planning baseline for review

Purpose and delivery status

Help flooring businesses turn measured scope and material/labour costs into traceable client proposals. This pack defines an intended product, not delivered production functionality. The existing repository contains an incomplete early estimator scaffold; these designs and stories do not imply that its features are implemented.

Native Figma tools were not exposed in this session. Nine editable SVG boards and a local gallery accompany this specification. Nothing has been published to Figma, and no live system settings or user permissions have been changed.

Confirmed requirements and assumptions

Confirmed: Administrator is a technical role. Project Manager primarily reviews assigned projects; can comment, sign off, reject/decline, and propose changes to material/labour elements. Those changes return to the user managing the original proposal. They do not silently overwrite that user's submitted proposal.

Planning assumptions: one company at launch; roles can be combined explicitly; original proposal manager owns revisions and issuance; all required reviewers must sign the exact version before issue; administrator privileges do not automatically grant pricing or approval authority. Project Manager sees selling prices and may propose rates for authorised line types, but supplier-only costs and aggregate profitability are hidden by default pending confirmation. Currency USD and imperial measurements in examples. Brand Floorwise / Oak & Co. is illustrative.

Not yet agreed: commercial authority for rates and approval thresholds; PM access to internal costs and margin; whether the same person may prepare and approve; required reviewer count and delegation; permitted client detail visibility; tax jurisdictions; eventual client portal/acceptance. These are business decisions, not implied approvals.

Users and permissions

All access is company-scoped, assignment-scoped and checked by the backend, including files, exports, comments and search results. Default deny. Assignment alone does not grant financial capabilities.

Administrator role changes are audited. Recommended governance: administrators cannot silently self-grant commercial powers; sensitive grants require a designated business authority. The identity of that authority must be confirmed before production.

Suggested capability keys: system.users.manage, system.integrations.manage, project.read, proposal.draft.edit, proposal.submit, proposal.issue, review.comment, review.propose_change, review.signoff, review.reject, financial.read_cost, financial.read_margin, catalog.manage, pricing.configure. Role bundles remain configurable; object-level scope remains mandatory.

User experience and front-end journey

Front-end states: loading, no projects, no files, draft saved/unsaved, saving failure/retry, invalid input, forbidden access, expired session, stale version/conflict, returned review, rejected review, successful sign-off, issuance failure and successful issuance. Distinguish “Return proposed revisions” from “Reject/decline submitted version.” Neither rejects the customer relationship or deletes a project.

Accessibility targets: keyboard-complete controls, visible focus, associated input labels, errors described in text, status conveyed beyond colour, sufficient contrast, screen-reader announcements for save/review outcomes, and usable narrow-screen layouts. Include confirmation of version and recipient for consequential review actions. Do not show a fake success while a request is pending. Desktop concept boards use 1440×1000; mobile board contains three 374px content-width concepts. Actual layouts must reflow, not scale screenshots.

Workflow, versioning and sign-offs

Draft → In review → Signed off → Issued. In review may become Changes requested or Rejected/declined; the owner then creates a new draft revision and resubmits. Rejected versions remain rejected in history. “Signed off” means internal approval, not client acceptance.

1. Owner submission snapshots line descriptions, quantities, rates, calculation results, configuration version and supporting file versions.
2. PM review draft stores proposed replacements and comments against that immutable snapshot. Material and labour changes are typed, validated, and assigned to the original proposal manager.
3. Returning revisions creates one owner task and one notification event. Delivery retries must not duplicate either.
4. Owner explicitly accepts or declines each requested change; declined changes require a response. Accepted changes populate a new draft, never rewrite the prior version. Departed owners require an audited reassignment.
5. Resubmission creates new reviewer tasks. Any scope, price, term or relevant file change invalidates affected approvals. Comments alone do not invalidate sign-offs.
6. Sign-off records reviewer, role/capability, timestamp, version and file references. Block when mandatory files are missing, unresolved changes remain, or reviewer scope is invalid.
7. All required current-version sign-offs are checked again server-side at issuance. Administrator corrections cannot bypass this gate implicitly.
8. Replaced files are retained by version and reviewed again. A reviewer can reject only the versions/stages they are assigned to.
9. Concurrent updates use a revision token / ETag; stale writes receive a conflict response and a compare/reload path. Review submission and issuance use idempotency keys.

Business and technical configuration

Configuration edits record old/new values, actor and effective date. No catalog update retroactively reprices issued proposals. Preview configuration changes before saving. Connection secrets stay server-side and are never returned in UI or logs.

Calculation contract

Installed area is the sum of valid room areas; purchases include waste and sale-unit rounding. Labour uses its configured measurement basis, not automatically the purchased material quantity. Use decimal-safe money calculations, named rounding rules and a versioned calculation policy shared by UI preview and server.

Illustrative baseline: installed area 400 ft²; purchase 440 ft²; material $3.85/ft² = $1,694; labour $2.75/ft² = $1,100; removal $500; prep $300; trim $250. Direct cost $3,844; 25% markup $961; subtotal $4,805; sample tax 8.25% on marked-up materials $174.69; client total $4,979.69. Estimated margin before overhead is 20%. This excludes unconfigured overhead or contingency.

Illustrative PM revision: material rate $4.10 and labour $3.00, unchanged 440 ft² purchase quantity. Direct cost $4,054; markup $1,013.50; subtotal $5,067.50; material tax $186.04; total $5,253.54, an increase of $273.85. Carton rounding is a separate capability; these examples assume sale by square foot.

Backend requirements and proposed API

Production services: relational database; identity/session service; server-side authorisation; deterministic calculation service; private versioned attachment storage; proposal/PDF service; audit records; transactional outbox for notification tasks; operational monitoring. Infrastructure/vendor selection remains open.

HTTP semantics: 400 malformed request; 401 unauthenticated; 403 unauthorised; 404 absent or concealed inaccessible record; 409 stale/conflicting transition; 422 valid syntax with invalid business data. Responses include correlation ID and structured field errors, never secrets.

Core entities: Company, User, Role/Capability, Project, ProjectAssignment, Client, RoomMeasurement, CatalogItem, RateVersion, Estimate, EstimateRevision, LineItemSnapshot, ReviewAssignment, ProposedChange, Comment, FileVersion, SignOff, ProposalSnapshot, AuditEvent, NotificationOutbox. IDs and company boundaries must be enforced across all relations.

Deployment milestones and sprint considerations

Points are relative team estimates using 1/2/3/5/8. They include implementation, relevant tests and review; they are not hours or commitments. Re-estimate after technical discovery. Stories of 8 points should be split if the team cannot complete them within one sprint. Sprint allocations below are dependency groupings, not calendar promises; no team velocity or capacity has been supplied.

M0 gates final access model; M1 gates real data. M2 precedes review of financial revisions. M3 precedes issuance. M4 precedes a live pilot. Do not treat story point totals as evidence that a fixed number of sprints is achievable.

Environment progression: local fixtures → development → staging with synthetic data → limited pilot → production. Use independent secrets, storage and databases; repeatable migrations; CI checks for calculations, workflow transitions, permissions and client output. Proposed targets for pilot: measured save/calculation p95 under 1 second under agreed load, explicit user feedback for longer PDF generation, and no lost committed revisions in restore rehearsal. Confirm actual service targets during M0.

Release procedure: record release and migration versions; verify backup and restore path; deploy additive migrations and application; smoke-test sign-in, assignment isolation, calculate, review, reconcile, issue and PDF; check logs/alerts; enable limited pilot; expand after UAT. Roll back application to the previous compatible version if access isolation, totals, sign-offs or issuance fail. Database recovery must use a rehearsed plan; do not blindly reverse destructive migrations. A named business reviewer and technical release owner must approve the pilot gate.

Definition of done and acceptance coverage

Every story meets its listed acceptance criterion, relevant backend tests, reviewed access checks, accessible error states and updated documentation. Review stories prove stale versions cannot be signed or issued. Client output tests assert absence of cost, profit, internal notes and private file links. Integration failures surface retryable states without duplicate notifications or proposals. Historical versions remain readable after catalog and workflow configuration updates.

Deferred scope: supplier/CRM/accounting sync, payments, e-signatures, client accounts, actual job-cost reconciliation, advanced reporting, multi-company SaaS billing and offline editing. These are not included in the 150-point baseline.

Decisions for the next review

1. Confirm the Project Manager's internal cost and margin visibility and which rates they may propose changing.
2. Identify the business authority who grants commercial permissions and sets tax/pricing policy.
3. Confirm reviewer routing, self-approval rules and delegated sign-off.
4. Confirm catalog sale units, measurement needs and tax locations.
5. Confirm proposal issuance channel, contract wording, retention policy and pilot team capacity.

UX reference and identity update — v0.2

The revised mockups use Jobber's quote record, actionable work list, line-item and activity patterns as UX references. Sources: Quote Basics and Quote Approvals, reviewed 24 October 2026. The internal PM review loop is Floorwise's custom workflow. Jobber's brand and screen assets are not reused.

The nine-board pack adds a consolidated project record and a niche flooring brand kit. Neon #B6FF3B, charcoal #161B18 and a staggered-plank mark replace the earlier soft-green styling. Internal review and client response are separate states. Sign-off is disabled while proposed changes or required file reviews remain open. Technical Administrator permissions remain separate from commercial authority. See brand-kit.md and tokens.json for the design specification.

The gallery is a navigable concept, not an implemented production app. The backlog remains 26 stories / 150 provisional points. Financial-visibility decisions remain open; new styling does not change access policy.

Interactive prototype — delivered scope

index.html now provides a browser-local interactive walkthrough; the earlier SVG gallery is at gallery.html. The prototype includes three personas, proposal creation and live calculations, submitted snapshots, PM material/labour proposals, comments, rejection, return to original owner, owner reconciliation, file sign-off, proposal sign-off, client preview and technical Administrator configuration. See PROTOTYPE-README.md for the walkthrough.

This implements UX behaviour only. Role switching simulates access, sample file references are generated, and all data stays in browser storage. No real authentication, multi-company isolation, uploads, notifications or backend security is delivered by this prototype. Capability changes act immediately; mandatory-file policy is snapshotted per submission. Material/labour rates are visible to the PM for the demonstration; internal profitability is hidden by default and configurable. The production permission decisions remain open.

Membership and accounting extension — October 2026

Plans apply to the workspace. Roles and explicit finance permissions apply to individual users. Prices, seat allowances and storage/usage quotas remain open commercial decisions; no charges or purchases occur in the prototype.

Default is Moderate to preserve the existing review walkthrough. Downgrading retains records but blocks premium accounting and Basic review mutations. Existing data is not deleted. The plan selector is a demo control available in every role; production subscription changes require a separate billing-owner permission and authenticated billing service. Basic produces draft estimate previews; it does not bypass PM approval or issue an approved proposal.

Accounting experience and permission model

Premium navigation adds Accounting. The designated finance operator (Jamie in the prototype) selects a signed-off project, creates an invoice, records a partial/full receipt, enters project-linked supplier bills, records bill payments, and marks cashbook entries cleared. PM and technical Administrator receive an access-restricted view even on Premium. Production finance permission must be independently granted by an authorized business owner and checked server-side; proposal-manager status alone must not grant finance access.

Invoice amounts and version are snapshotted. Duplicate project invoices and overpayments are blocked. A draft/new revision cannot be invoiced until signed off. This prototype allows one invoice per project; progress billing, adjustments and credit notes are future work. Payments never move money. Bills currently use a single total with no input-tax recovery. Summary revenue excludes output tax; recorded costs may be incomplete. Clearing is manual statement confirmation, not full bank reconciliation. Browser data is not a double-entry ledger or production accounting system.

Reference and product adaptation

CosmoLex connects billing, expense tracking, accounts payable, banking and reports. Use this information architecture with flooring jobs replacing matters, alongside the established Jobber-inspired work lists. Do not import legal trust-accounting or compliance claims into this product.

Primary references reviewed October 24, 2026: - CosmoLex general accounting: business bills, bank imports/reconciliation and reports. - CosmoLex accounts payable: bill entry and recording payment.

Production requirements and incremental sprint sizing

These estimates add to the existing 150-point proposal backlog; they are provisional relative sizing, not delivery dates. Accounting adds 68 points (218 total proposed scope). Validate with engineering and a qualified accounting reviewer before commitment.

Front end: sales-site plan comparison (outside the bidding workspace), workspace access explanations, finance workspace, invoice detail, payment allocation, vendor bill entry, statement reconciliation and report filters. Back end: tenant-scoped subscriptions/entitlements, finance grants, invoice/line/tax records, payment allocations, bills, journal entries, statement lines, reconciliation periods and immutable audit events. Use integer minor units and explicit currency; server validation and idempotency on every financial write. Financial events must post atomically with their ledger entries. Production APIs should cover invoices, payments, bills, journals, statement imports, reconciliations and reports; payment-provider callbacks require signature verification and retry-safe processing.

Release in dependency order: entitlements/security → invoices/payables and ledger → bank reconciliation/reports → controlled pilot. No live banking, payment processor, payroll or tax filing is included in the current local prototype.

Estimation scope and stakeholder agreements

The home page now provides Design & surface, Square footage, Materials & itemization, and Service agreement entry points for the selected project. Scope setup captures pattern, substrate condition, installed area, supplier/material reference, service level, inclusions, exclusions/change process, target start, expected duration and deposit percentage. Saving area recalculates square-foot line quantities with existing material waste; allowances remain fixed. Users must verify quantities and service lines agree with the narrative scope.

A draft agreement is derived from the current estimate, showing itemized selling prices, tax, total, effective price per installed square foot, service commitments and payment split. Submission freezes the scope with its proposal version. Internal PM review is separate from client, contractor representative and PM stakeholder acceptance. Moderate/Premium enable simulated signature records after internal sign-off; Basic permits draft agreement preview. Revised proposals retain earlier records but require new signatures. Admin has no signing authority. The owner can simulate client/contractor acceptance; the reviewer can simulate PM acceptance. No identity verification or actual external signature is performed.

Material file selection stores the filename only; no file bytes are uploaded or retained. Production needs secure tenant-scoped object storage, malware scanning, document version IDs and signed download URLs. The generated scope is a product prototype, not jurisdiction-specific contractual terms.

Production agreement work: server-side immutable document generation and content hash (5 points), stakeholder identity and invitation/decline flow (8), signature-provider integration with consent evidence and idempotent webhooks (8), signed PDF/audit retention and version supersession (5), secure material uploads (8). Provisional incremental 34 points beyond the prior 218-point scope, total 252. Dependencies: authenticated roles, frozen proposal versions, approved contract templates and storage. Deployment gates: verify every signer sees the exact approved document; block signing superseded versions; retain evidence and prior signed copies; test consent, decline, expiration and retry flows. Service level is project scope and is distinct from the Basic/Moderate/Premium subscription.

Membership comparison navigation is removed from the application. Plan marketing belongs on the sales website. The labelled Demo plan selector remains only for prototype testing; production bidding screens use the workspace entitlement without a plan-shopping flow.

Current demo UI: all subscription selection and membership comparison controls are removed from the bidding workspace. This walkthrough uses Premium capabilities automatically; underlying tier authorization remains for future sales-site integration.

Tenant and platform permissions — onboarding console

The separate onboarding.html console is a local prototype for platform operations. Membership entitlements appear only here, outside the bidding journey. Client metadata includes company, owner contact, entitlement and Toronto/CAD/HST settings. No invitation emails, infrastructure provisioning, tenant authentication or shared databases are implemented. The role selector simulates a selected client's owner and is not an authorization mechanism. Existing bidding data is not attached to these client records.

Production authorization rule: authenticated identity + tenant membership + entitlement + operation grant + resource assignment. Tenant identity must be derived from a verified session/membership, never trusted from a browser parameter. Tenant-owner simulation in this prototype is not a test of authentication or cross-tenant access prevention.

Support grants must bind tenant, named support identity, ticket, permitted resources/actions, owner approver, expiry and revocation. Read-only configuration diagnostics is the initial scope. Tokens must not contain cached authority that survives revocation. Suspension denies client activity and revokes grants. Server time determines expiry. Audit records are append-only and include actor, tenant, action, result and correlation ID, excluding secrets. Support sees masked contact/configuration details until authorized; financial or document access needs a separately designed consent process.

Production schema: tenants, users, memberships, role_grants, onboarding_tasks, invitations (hashed one-time token + expiry), support_requests, support_grants and audit_events. Every business row carries tenant_id; cross-tenant foreign keys must be rejected. Required tests include forged tenant IDs, removed membership, assignment bypass, expired/revoked grants and concurrent onboarding activation. Deployment environments remain development/staging/production, distinct from tenant workspaces.

Prototype journey: create a fictional company → switch to Tenant owner and accept simulated invitation → switch to Platform onboarding and complete configuration/training → activate → switch to Platform support and request diagnostics → Tenant owner approves one hour → support can view configuration → owner revokes. A second client retains a separate checklist and audit history. No email is sent and no real client is provisioned.

Incremental implementation planning (provisional): tenant authentication/membership 13 points; server-side isolation and adversarial tests 13; owner invitation flow 8; backend lifecycle/provisioning 8; time-bound support grants 8; audit/operational pilot 5. Total 55 additional points, to be re-estimated after backend design. Ticketing follows onboarding and is not included in this console.

Separate client workspaces

Active clients now open their own bidding workspace from Tenant owner mode in the onboarding console. URL parameter tenant selects a registered active client; each client has separate browser storage for proposals, reviews, agreements, accounting, configuration and UI state. The original Toronto demo remains separate. Workspace entitlements follow the client record, so Moderate has no accounting access and Premium does. Platform support/onboarding modes do not offer a business-workspace link. Unknown/inactive clients and mismatched persisted tenant IDs fail closed in the normal UI; suspension is rechecked before writes and on registry updates in other tabs.

This is prototype data partitioning, not a security boundary: the role switcher and local storage can be altered by the browser user. Records are not shared across browsers/devices; file, localhost and Cloudflare origins keep separate registries. No real accounts or cloud resources are created. Production still requires authenticated tenant membership, database row-level access enforcement, server authorization and audit logging. Old wording that client metadata is not linked to bidding records is superseded by this browser-local implementation.