Building InvoiceNext

Tech stack

Deliberately close to next2 — the team knows it, the patterns are proven, and the reusable pure-Python modules drop straight in. Six things change, and each is argued in the next section.

The six deltas, argued

1 · PostgreSQL, and therefore a fresh kernel

Native row-level security, no per-tenant licensing, and the right engine for thousands of small tenants on a free tier. The consequence is unavoidable and worth stating plainly: next2's kernel is raw T‑SQL and does not port. We take the design and the pure-Python modules; the tenancy layer is written fresh. Postgres RLS is also simply better here — SET LOCAL is transaction-scoped, so a pooled connection cannot leak tenant context the way SQL Server's session context can.

2 · SQLAlchemy Core rather than raw cursors

next2 issues raw SQL through pyodbc. That was defensible for an ERP with hand-tuned queries against a legacy schema; it is the wrong default for a greenfield product whose hardest queries are financial reports composed from filters. Core gives composable, typed SQL without the identity-map surprises of the full ORM — and the ORM earns its place only for master-data CRUD.

4 · No CSS framework

The design kit is built on CSS custom properties and logical properties, and it mirrors to Arabic by setting one attribute. Tailwind would add a build dependency and handle RTL through variants — strictly worse for a product where every rule must mirror. next2's Bootstrap is not worth carrying either.

5 · i18n from the first commit

next2 has 2,500 hard-coded English strings across 263 components and no i18n library. That is the cost of retrofitting, measured. We extract from commit one, with pseudo-locale in CI so an unextracted string fails the build rather than surfacing in an Arabic screenshot.

6 · A Playwright suite, because next2 has none

Its *_e2e/ directories hold screenshot evidence, not tests. The rule that earned its place on that programme — dogfooding finds what unit tests structurally cannot — applies doubly here: RTL layout, bilingual PDFs and the wire-action confirmations are all invisible to a unit test.

Infrastructure

A separate VM is not a preference. next2 runs one self-hosted CI runner with one job slot, and its own traffic already produces measured queue waits of 30 and 37 minutes against a 34.5-minute median. Sharing it would slow both products.

Revised 12 Aug — no new VM and no managed database. next2 is paused, so its server becomes our staging box and this development VM becomes the build machine. Both changes are already in place.

Blob storage — provisioned 12 August

Soft delete and versioning are not conveniences — they are the ISO 27001 evidence that a record cannot be quietly destroyed, and they support the fifteen-year retention obligation. An immutability policy goes on the prod/ prefix before the first live tenant, not now, because it cannot be undone.

Archive is a first-class store, not a folder

Access points hold documents in transit then delete them; retention sits on the taxpayer. For every submitted document we keep the canonical JSON, the wire payload, the raw response, the generated UBL, the tax document, the message-level status and the rendered PDF — write-once, with an integrity hash, addressable for fifteen years.

Repository

One new private repository: axb0234/invoicenext. Plus a small second one for the shared code, because vendoring it into two products invites drift.

invoicenext/
  api/
    app/
      core/        # tenancy, RLS enrolment, session, config — written fresh for Postgres
      authz/       # function-roles + scope; catalogue shape kept, keys rewritten
      ar/          # customers, items, quotes, invoices, credit + debit notes, receipts
      ap/          # suppliers, inbound inbox, bill registration, acknowledge / dispute
      einv/        # canonical model, validation, enrichment, state machine, adapters
      gl/          # tier two — vouchers, periods, trial balance, statements
      print/       # WeasyPrint doctype registry + bilingual templates
      imp/         # CSV / Excel import framework (lifted)
      jobs/        # Postgres queue + workers
      billing/     # plans, metering, self-serve signup — nothing to lift, all new
    alembic/versions/
    tests/
  web/
    src/
      shell/       # nav, ⌘K catalogue, IA budget test
      ui/          # primitives on the design-kit tokens
      locales/     # en.json · ar.json · pseudo.json
      ar/ ap/ einv/ gl/ billing/
    e2e/           # Playwright, incl. an RTL pass
  infra/           # Caddyfile · docker-compose.yml · deploy.sh
  planning/        # BUILD_JOURNAL.md · PARALLEL_PROTOCOL.md · GAP_MATRIX.md
  vendor/fontawesome-pro/   # licensed, self-hosted, not from a CDN

The shared package

axb0234/aspirtek-kernel — pure Python, no schema, no migrations. Money and currency precision, the import framework core, the approvals effects registry, grid and export. Consumed by pinned tag:

pip install "aspirtek-kernel @ git+ssh://git@github.com/axb0234/aspirtek-kernel@v1.0.0"

A conformance test in each product's CI asserts the Python and TypeScript money implementations agree — the same technique next2 already uses to keep money.py and currency.ts in step. No cross-repository migration link ever exists.

Branching

main is always deployable. Mission branches mission/<tag> in worktrees on /data/inx-wt/<TAG> — never under ~/projects, which is the session host's working directory. Every mission gets its own database inx_<tag> and its own virtualenv, because an editable install resolves to the checkout it came from and a shared venv silently tests the wrong code. Never git stash in a fleet — the stash stack is shared across worktrees.

Pipeline

Environments

next2 has none beyond production. We need one more, and it is not optional: a sandbox wired to the provider's sandbox, because the alternative is testing tax submissions against the real authority.

The staged rollout is carried straight from the OIG build, where it worked: a tenant starts OFF, moves to MANUAL where a human presses submit, and only then to AUTO — and switching to AUTO requires typing the company code to confirm.

Phases

Sixteen weeks to a sellable Oman product with a customer pilot running. The ledger tier follows; it is a commercial decision, not a compliance one, and the Oman deadline for our band is 1 October 2027.

Mission board — phases 1 and 2

Disjoint ownership, each on its own worktree and database, merged serially through one coordinator. A trap one mission pays to find is handed to the next for free.

Verification

Eleven rules from next2, each learned by something breaking. Restated for this stack, with three added for what is new here.

Week one

Ordered by whether a clock is running. The first two have external deadlines.

Cost

Infrastructure to get to a testable staging product is about $5 a month — the blob, and nothing else. Everything until launch runs on hardware already being paid for. The two numbers that matter are the ISO certification, which is a real commitment on an external clock, and the provider's wholesale rate, which decides whether the pricing model works at all and cannot be discovered without a conversation.