Skip to content

Runbook — releasing scalable invoice numbering, tax verification and recorded GST decisions

Status: prepared, not performed. This is the release of ADR 0024 (migrations 101–103, backend, Account Admin portal). It is a deploy, not an activation: after it, ACCOUNTING_INVOICE_ISSUANCE_ENABLED, the settings gate invoice_issuance_enabled and ACCOUNTING_JOURNAL_ENGINE_ENABLED are all still false, no invoice series exists, no invoice number has been taken and no order is touched. Switching invoicing on is a separate operation (invoice-issuance-activation.md) that happens only after §4 below.

Roles: owner (business owner / super admin), accounts admin (a super admin holds every accounts-admin step too), GST accountant, CA (the company's chartered accountant, outside the system), engineering.

1. Before merging

  • The applicable ci.yml checks are green on the pull request. backend reports the combined results of the isolated Go test jobs and build checks. account-admin reports the accounting portal's test jobs and production-mode build. CI does not build the documentation site: build it in strict mode before merging (docker build -f docs.Dockerfile . from the repository root), because the merge publishes it (§2).
  • The independent review's findings are fixed or consciously accepted, in writing, on the pull request.
  • The owner approves the merge explicitly. Nothing in this release is merged or deployed on its own.
  • No other production operation (a backup, an activation, another deploy) is in progress; the deploy workflows share a concurrency group and a server lock, so they queue rather than collide.

2. Deploy

Application deploys are never automatic: a merge to main changes no API, portal or database (see the header of deploy-backend.yml). The one thing a merge does publish by itself is the documentation site — deploy-docs runs on every push to main that touches docs/** or mkdocs.yml, so these pages, the ADR and the activation runbook go live at the documentation address when the change is merged. After the owner has approved the merge, the owner or engineering dispatches, in this order, from Actions → Run workflow:

  1. deploy-backend — type the confirmation phrase DEPLOY BACKEND TO PRODUCTION. It builds the image, takes its own pg_dump (and aborts if the dump fails), applies the pending migrations in order, one transaction per file: 101, 102, 103 (additive; nothing existing is changed except the back-fill of activated_at for active series, of which production has none), then recreates the API. It does not touch the issuance switches; §3 checks them after the fact.
  2. deploy-account-admin-portal — builds the portal in api mode against https://api.aimstoreorg.com and replaces the container.
  3. deploy-admin-portal — publishes the admin app's corrected wording on the Product screen (an approved GST & HSN setting is no longer called "active for invoices": it also needs the verification). Until this runs, the deployed admin app still shows the old sentence.

No other service changes. Customers see nothing new: there is no customer-facing invoice route.

3. Verify, read-only

  1. Dispatch production-accounting-verify with expected = enabled (the input is the state of the accounting module's flag, ACCOUNTING_ENABLED, which is on in production — it is not the invoicing switch) and release = scalable-numbering. Every gate must read ok — in particular migrations 101–103 tracked, the tables product_tax_verifications and gst_policy_decisions, every protection trigger present and enabled, the DB issuance gate false, no duplicate invoice number, at most one invoice per order, and both ACCOUNTING_INVOICE_ISSUANCE_ENABLED and ACCOUNTING_JOURNAL_ENGINE_ENABLED not true.
  2. Dispatch production-issuance-readiness. Expected after this release and before any owner action: invoice_series rows 0, public.invoices rows 0, migrations 101-103 tracked 3, live verification rows (not all usable) 0, gst_policy_decisions rows 0, invoice_exclusions active 0, DB issuance gate false. (Row counts of everything else are unchanged from the pre-deploy report. The probe's rows for the later verified-identity release — migration 104 tracked (of 1), configurations the engine may use (approved + verified) and verified people (bound principals) — read 0 and n/a (before migration 104) until that release is deployed.)
  3. In the portal, Sales Invoices → Readiness loads. It must say Not ready to issue, with BLOCKING for exactly: the two switches, the seller details not saved in Settings, the missing series, no verified HSN/GST rate, and the GST decisions (including e-invoicing). That is the correct state. Anything else blocking — in particular a failing record-protection line — is a deployment defect: stop and call engineering. Warnings about older paid orders, recent paid orders that switching on would invoice at once, or sales from an earlier financial year are information for §4.
  4. Settings → Invoice series opens for an Accounts Admin or Super Admin, offers the Standard format first and creates nothing by itself.
  5. The read-only owner blocks printed by the invoicedryrun and samplepreview tools of this release read the two new tables, so run them only after §2; before the deploy they stop with a "relation does not exist" error and print nothing (they are read-only and fail closed). Blocks built from the verified-identity release (ADR 0025) also read migration 104's columns and need 104 on the target.

If any of this is wrong, do not proceed to §4. The application can still be rolled back (§6) because nothing has been created yet.

4. What the owner and the CA do next (nothing here is done by engineering)

Each step is done in the portal by a named person, is audited, and is recorded with its written basis. The order matters only in that the readiness page names what is still open.

# Step Who Where
1 Check the company profile against the GST registration (legal name AIM ORIGINATORS PRIVATE LIMITED, GSTIN 33ABGCA0227M1ZV, state Tamil Nadu 33, the registered address, support phone and e-mail) and press Save company profile — it is available even if nothing needed changing. Until it is saved, the invoice engine holds every order. Optional: PAN (must match characters 3–12 of the GSTIN). accounts admin / super admin Settings → Company profile
2 For each sold product, set the HSN/SAC and GST rate as the CA confirms them (the sample "6109 at 5 %" is not an answer) and have a second person approve it. CA → GST accountant Product screen of the admin app (GST & HSN)
3 Verify each approved configuration: say who confirmed it (owner / chartered accountant / tax adviser — nothing is pre-selected) and the written basis (the letter or e-mail and its date). The list will say "not shown to be independent" for a rate approved in the admin app and verified in this portal: the two are separate login systems; accept that in writing or have a different person approve and verify. (Once the verified-identity release, ADR 0025, is deployed this no longer applies: a verification is recorded only by a verified person other than the approver, whichever login each uses, and invoice-issuance-activation.md §1–§2 give the steps.) owner or GST accountant Settings → Tax verification and GST decisions
4 Record the ten GST decisions with their basis — in particular whether e-invoicing applies (the CA's question: the company's turnover against the threshold in force; record the figure and the threshold relied on). An answer the system cannot carry out (for example "e-invoicing applies") may be recorded; it keeps invoicing stopped until the step exists. owner or GST accountant Settings → Tax verification and GST decisions
5 Create the current financial year's series in the Standard format — prefix AIM, 2026-27, automatic rollover on (it also lets the next financial year open its first series by itself). Read the preview (AIM/26A/00000001, 16 of 16 characters) and the stated capacity (99,999,999 per series — shown in the portal as 9,99,99,999 — and 26 series a year) before confirming. The screen refuses to call anything else a success. accounts admin / super admin Settings → Invoice series
6 Check, then mark, the historical test orders. Paste the order numbers into Check orders before marking them, read the findings (status, amount, whether a gateway payment is recorded, whether an invoice exists), and mark only the ones that really are test orders as never invoice: write the reason, or choose Use the suggested wording if it is accurate (the box opens empty). Then look at the recent paid orders too (Readiness says how many switching on would invoice at once): a test order placed yesterday is not historical. Do not run a backfill. owner / super admin Sales Invoices → Needs attention → Historical orders
7 Read Sales Invoices → Readiness again. The only BLOCKING lines must be the two switches. Warnings (PAN, contact, an unmarked historical order…) are fixed or accepted in writing. owner Sales Invoices → Readiness

Do not create a test order, a test invoice or a test series "to see what happens": issued numbers are permanent.

5. Activation (not part of this release)

Follow invoice-issuance-activation.md §4 exactly: the owner's written go-ahead (the CA's confirmations attached), the server marker, then production-issuance-flag with the exact phrase. The journal engine stays off and customer access stays off. Watch the first real invoice as in §5 of that runbook; additionally confirm its number reads AIM/26A/00000001 and that Settings → Invoice series shows series A with 1 issued.

6. Rolling back this release

  • Before any series exists (the state right after §2, and until step 5 above): apply rollback_101.sql (and, optionally, rollback_103.sql then rollback_102.sql first — they only stop being read), then redeploy the previous backend and portal images. rollback_101 is required: migration 101 replaced the (prefix, fy_label) uniqueness the previous backend's series creation relies on, so without it the old image cannot create any series. (Tested: the compensating scripts and the migrations applied again restore the schema exactly.)
  • After a standard series exists: do not redeploy the previous backend, and rollback_101 refuses anyway. The previous backend does not understand a standard-format series: it would format its numbers as 20 characters and refuse to issue them, holding every order. Switch issuance off (production-issuance-flag, disable) and roll forward with a fix; if the database itself must go back, restore from the deploy's pg_dump.
  • Schema: aim-backend/scripts/postgres/rollback/rollback_103.sql, rollback_102.sql, rollback_101.sql (in that order) are compensating scripts, never applied automatically. rollback_102 and rollback_103 drop the verification and decision tables — export them first once anything has been recorded, because they are the record of who confirmed what. rollback_101 refuses while any standard-format series has issued numbers.

7. What this release does not do

  • It does not enable invoicing, create a series, verify a rate, record a decision or mark an order.
  • It does not run, or prepare to run, a historical backfill, and it does not invoice the four older test orders.
  • It does not change checkout, payments, the wallet, refunds or the journal.
  • It does not change the owner-approved A4 invoice layout or the sample-invoice preview pages.
  • It does not decide any GST rate, e-invoicing obligation, signature requirement or treatment: those stay blockers until a named person records them with their basis.