Founder signup and new workspace

Goal

Found a company workspace from identity → trial plan → country/industry packs, with a live preview of currency, locales, tax, fiscal year, and chart template before you commit. First signup and New workspace share the same setup steps.

Who it is for

• First workspace: anyone creating a BlueMatrix account at /signup. Invited members never see this wizard — they land in the tenant they were invited to.
• Additional workspace: users with tenant.manage (typically Owner) at /provision.

Preconditions

• You know the legal/trading Company name and the country you operate in.
• Public catalogues are available without signing in: GET /api/public/country-packs, /industry-packs, /plans. Authenticated in-app copies remain at GET /country-packs and /industry-packs.

Open the screen

• First workspace: https://accounts-dev.bluemtx.com/signup (or /signup on the staff app, which redirects). Google/Microsoft buttons appear only when those OAuth apps are configured.
• Another workspace: Organization → New workspace, or the workspace switcher → New workspace (/provision). Identity and plan steps are skipped.

Steps — first signup (/signup)

1. You — Continue with Google or Microsoft, or email + password + name. Terms sit under the CTA. Email verification is not required to finish the wizard (SSO emails are already verified). Password signups get a banner + resend; go-live, member invites, and billing require a verified address.
2. Plan — pick Starter / Growth / Scale from the live plan catalogue. No card. The chosen plan_code starts a trial (bos.billing.trial_days, default 14) via the manual billing provider.
3. Company — workspace name (slug preview).
4. Country — pack cards. Selecting one fills a preview: currency, locales, tax regime, chart template, fiscal year. Adjust is an accordion, not a separate step. Timezone defaults to the browser.
5. Industry — optional; skip is allowed. Cards cover retail, restaurant, wholesale, e-commerce, services, field service, manufacturing, construction, rental, education, healthcare, agriculture, logistics, and nonprofit. Extra modules from the pack are previewed as human suites (POS, storefront, CRM, …).
6. How to start — Explore with sample data (default) vs Start with clean books, plus first job: Sell / Buy / Shop / People / Just explore.
7. Create workspace — one POST /api/signup/complete. You land on the screen for the chosen intent (invoices, bills, POS, employees, or dashboard). The first-week checklist shows the admin spine plus 1–2 steps for that intent — not every module hub.

Steps — additional workspace (/provision)

Same company → country (with live preview + Adjust) → industry → sample vs clean + intent, then Create workspace. POST /tenants uses the same payload. On success the toast Workspace created. appears and the client switches into the new workspace.

Result

• POST /api/auth/register creates the user only and a Sanctum token with the signup ability (no tenant yet). Completing the wizard calls TenantProvisioner and swaps in a tenant:{uuid} token.
• Country pack writes base_currency, default_locale, timezone, fiscal_year_start_month, tax/chart defaults. Industry pack default_modules are enabled.
• Sample data enables all optional modules and rich trial data. Clean books keep core + default-granted + pack modules only, and still seed the country-pack chart so the first invoice path works.
• Chosen plan lands on tenant_subscriptions (trialing when trial days > 0). Welcome pricing reads GET /api/public/plans.
• Intent is stored as the onboarding.intent UI preference (not a tenant column).

Hard stops

• Signup token hitting tenant routes (for example /api/me) → 403.
• Missing tenant.manage on /provision → route blocked.
• Invalid currency / locale / timezone / fiscal month → validation 422.
• Unverified email on go-live, invite, or billing portal → 422.
• Without a country pack you can still create, then set localization in Settings.

Related

• Locale and currency
• Enable modules
• Tenant settings
• Sign in and invites