Setup wizard

Who can use this: Owner, or anyone with the setup.edit permission. Other roles can read the wizard but cannot save. URL / Route: /finance/orgs/{org}/setup/step-1 … step-4 (route names finance.orgs.setup.step1.form through finance.orgs.setup.step4.form, plus finance.orgs.setup.finish). Setup is also reachable from the dashboard's "Finish setup" call-to-action. Plan / feature gate: none — every plan must finish setup. Permissions: setup.view (read), setup.edit (save and finish).

Purpose

When an organization opens Solabooks for the first time, the books are empty. The setup wizard establishes four things in order: the organization profile, the country and base currency, the tax regime, and the chart of accounts. Once Finish is pressed, Solabooks unlocks the rest of the app for that organization.

A middleware called finance.setup.complete (alias org_setup_complete in app/Http/Kernel.php) checks for a finished setup on every other Solabooks route. If setup is not finished, the user is redirected back into the wizard.

Step by step

Step 1 — Organization basics

Route: finance.orgs.setup.step1.form (GET) / step1.save (POST)

Capture the legal name, registration / tax number, business email, business phone, address line, city, postal code, country, and timezone. These print on every PDF document later; you can change them in Settings afterwards but the country choice drives later steps.

Step 2 — Tax regime

Route: finance.orgs.setup.step2.form / step2.save

Pick the tax regime that matches your country: VAT (most common), GST, sales-tax, or "no tax / cash basis". The wizard shows the predefined regimes from tax_regimes for your selected country. The choice writes the organization-level VAT flag and reverse-charge flag.

If you are not in a VAT/GST country, choose "No tax". You can still create transactions; they simply won't carry tax lines.

Step 3 — Tax codes & mapping

Route: finance.orgs.setup.step3.form / step3.save. Helper endpoints: step3.preview and step3.apply.

Solavel ships per-country tax-code defaults (for example: Standard 5%, Zero-rated 0%, Exempt). On this step you can:

Click Preview taxes (finance.orgs.setup.step3.preview) to see what would be created.
Click Apply defaults (finance.orgs.setup.step3.apply) to install the predefined codes.
Edit each rate before saving.

When you save, Solabooks creates real tax_codes and tax_rates rows. You can change them later under Taxes & VAT.

Step 4 — Chart of Accounts

Route: finance.orgs.setup.step4.form / step4.save

Choose a starter chart from the country-appropriate template (Service business, Trading, Construction, etc.) or upload your own. The wizard previews each account before saving. After save you have a complete chart of accounts; you can still add, edit, or archive accounts later.

Finish

Route: finance.orgs.setup.finish (POST)

Pressing Finish writes the "setup complete" flag for the organization, runs a smoke check on the books, and redirects you to the Dashboard. From this moment on, all other finance routes work.

Diagnostics

Route: finance.orgs.setup.diagnostics (GET)

A read-only screen that shows the saved values for each step and reports any inconsistency (e.g. a tax code with no rates). Use this if you suspect setup partially saved.

Behaviour and rules

Order matters. You cannot skip a step — the wizard navigates linearly through 1, 2, 3, 4.
Idempotent. If you re-enter the wizard after partial completion, it picks up where you left off; nothing is duplicated.
finance.setup.complete middleware. Until Finish is pressed, every non-setup, non-settings route in /finance/* redirects to the wizard. The wizard pages themselves explicitly opt out of the middleware to avoid redirect loops.
Setup is per organization. If you join a second organization, you have to complete its setup separately.
Country defaults lookup. The endpoint setup/country-defaults (finance.setup.country-defaults) is used by the wizard's AJAX to fill suggested currency, tax regime, and locale based on the country you pick. It is deliberately unauthenticated of org context so the wizard can hit it.

Permissions / restrictions

An Owner can always run setup.
Any other role with setup.edit can run setup; without it, the form is read-only.
Setup cannot be undone from the UI. To "redo" setup you would have to clear the organization's books — talk to support before doing that.