Running the platform

Three roles share the platform and the boundaries between them are enforced, not advisory. Businesses record their own trade. Tax lawyers review and file. You run the platform underneath both.

What belongs to you alone:

• Creating a business and its single login.
• Storing and rotating FBR tokens, which nobody else can read.
• Assigning tax lawyers to businesses.
• Moving a business from sandbox to production.
• Syncing FBR reference data for the whole platform.
• Reading the audit log and the raw request and response of every FBR call.
• Suspending or reactivating a business.

Go to /admin.

There are three panels in the application and they are separate front doors: /admin for you, /lawyer for reviewers, /app for businesses. An account signs in to exactly one of them.

Below the figures: submissions over time, acceptance rate by business, the most frequent error codes, and the businesses with the largest review backlogs.

Platform → Businesses → New business.

What gets created for them: thirty-four ledger accounts covering assets, liabilities, equity, income and expenses, including the sales tax payable and input tax accounts the FBR flow needs; eleven expense categories; and the sandbox scenario checklist for their activity and sector.

Each business holds two tokens, sandbox and production, issued from the FBR IRIS portal by the business itself. They are encrypted at rest with the application key and decrypted only inside the service that makes the call.

Rules the system enforces

• A token is never rendered in any screen, in either panel, including yours. You can replace one; you cannot read one back.
• Tokens are never logged. Request payloads are stored for the audit trail with the authorisation header stripped.
• The environment on the business decides which token is used. There is no per-submission override.

Rotating a token

Open the business, paste the new token, save. The change is recorded in the audit log as an event without its value. Rotate whenever a token expires, when someone with access leaves, or on any suspicion of exposure.

FBR → Sandbox scenarios. FBR requires a business to submit successfully against each scenario that matches its activity and sector before it may go live. The platform holds all twenty-eight scenarios, SN001 through SN028, and selects the applicable subset automatically. IRIS issues fewer than the published table (it has dropped SN015, SN021 and SN022); if the list on this page differs from the "Eligible Scenarios" tile in IRIS, correct the business nature or sector and use Refresh applicable scenarios. IRIS treats a business ticked as Importer, Exporter and Distributor as a Distributor.

Each row shows its status — pending, passed or failed — with the FBR number that last exercised it and, under Last result, FBR's own words where it failed. The Runner column says Automatic when the platform knows how to file that scenario itself and Manual when it does not; hover a Manual badge for the reason. A steel manufacturer gets the steel-sector scenarios; a services business gets the service ones. You do not pick the list.

Running them

You pass the scenarios yourself from this page; the business does not need to be involved. Before the first run the business needs its NTN or CNIC, its province and its sandbox token. Then:

1. Run on a row files one test invoice for that scenario: the platform creates a sandbox test buyer (registered or unregistered as the scenario needs) and a sandbox test product with the right HS code, rate, SRO reference, unit and retail price, raises a ten-unit invoice, checks it with FBR's validation service, approves it in your name and posts it. Accepted means passed; the FBR number is shown on the row.
2. Run all pending does the same for every pending or failed automatic scenario, in code order, and stops at the first one FBR rejects so you can read the reason.
3. A rejection cancels the test invoice and records FBR's message on the row. Fix the cause and run it again; a failed scenario can be re-run any number of times.

Test invoices are real documents: they post to the business's ledger and appear in its lists marked Sandbox test, as do the test buyer and products. That is deliberate — FBR must see a genuine filing — and it is why the next step exists.

Purging the test data

Purge sandbox test data removes every sandbox test invoice with its journal entries, stock movements, reviews and FBR records, then the test products and customers. The scenario results are kept. It refuses while a test invoice is still in flight to FBR or has a credit note or receipt against it. Run it once every scenario has passed and before the business trades for real; Promote to production will not proceed while test invoices remain.

Scenarios marked Manual have no recipe yet because they have not been verified against FBR's sandbox. They still have to be passed: create the invoice by hand in the business's panel, have the lawyer approve and file it, and the row updates on acceptance.

Confirm all five before you switch:

1. Every applicable scenario shows as passed.
2. The sandbox test data has been purged (see the previous section).
3. The business has obtained its production token from IRIS — it appears there automatically once the last scenario passes — and you have entered it with Set FBR tokens.
4. Identity details — NTN, STRN, province — match the registration exactly, and the IP whitelisted in IRIS is the server's outbound address.
5. A tax lawyer is assigned and actively reviewing.

Then use Promote to production on the Sandbox scenarios page. It is disabled until the scenarios are complete and a production token exists, and it refuses while sandbox test invoices remain. From that moment every approved document is filed live. The date of the change is recorded on the business and in the audit log.

Platform → Tax Lawyers. Create the account with a name, email and password, then assign businesses to it. A lawyer sees exactly the businesses assigned to them and nothing else.

The list shows each lawyer's assigned client count, pending review count and oldest waiting document, which is how you spot an overloaded reviewer before clients start complaining.

Reassigning

Assignment can be changed at any time and takes effect immediately. Work already reviewed keeps the name of the lawyer who reviewed it, permanently. When a lawyer leaves, reassign their clients first, then deactivate the account; deactivating leaves their historical decisions intact and attributed.

FBR → Reference data holds FBR's own lists, cached locally so forms and validation never guess: provinces, document types, HS codes, SRO items, transaction types and units of measure.

Nothing in the interface hardcodes these values. A province dropdown, a unit of measure, an HS code lookup — all read from this cache.

Syncing

A scheduled sync runs daily at 02:30 and pulls every list using the first available business token. Sync now on this screen runs it immediately, which is what you want after FBR publishes changes. Each type reports how many rows it wrote, or the error if it failed; one list failing does not stop the others.

The data is considered stale after twenty-four hours and the dashboard says so. Stale reference data is not an outage — the lists change rarely — but it is worth clearing before a busy filing period.

FBR → Submissions is the record of every filing attempt the platform has made, for every business. Filter by business, environment, status, date range or error code.

Each submission holds the document it belongs to, the environment, the idempotency key, the attempt count, the FBR invoice number and filing date where accepted, the error code and message where rejected, the full request and response payloads, and the timestamps of the last attempt and completion.

Statuses

Every attempt also writes a call log holding the endpoint, HTTP status, duration in milliseconds, payloads and any exception. When someone disputes what was sent, this is the answer.

An idempotency key is built from the document and environment, so a retried submission can never produce a second filing of the same invoice.

FBR → FBR monitoring is the health view of the integration as a whole: submission volume over time, acceptance rate, average response time, the most frequent error codes across all businesses, unresolved unknowns, and the reference data age.

Reading it

• Acceptance rate falling across every business points at FBR or at stale reference data, not at one client.
• Acceptance rate falling for one business points at their product tax profiles. Tell their lawyer.
• Response times climbing usually means FBR is under load. The retry policy absorbs it.
• Unknowns accumulating means reconciliation is not running. Check the scheduler.

Reconciliation runs hourly, asking FBR about every submission left unknown and settling each one against FBR's own record.

Monitoring → Audit Log records every meaningful change made anywhere on the platform: who, what, when, and the before and after values.

What is logged: document creation and every state change, review decisions with their comments, all FBR submissions and their outcomes, period locks and unlocks with reasons, master record changes, credential changes as events without values, business and lawyer administration, and logins.

Filter by business, user, action, model or date range. Each entry links to the record it changed.

Open the business and clear Active. The login stops working immediately. All data, filings and audit history remain untouched, and reactivating restores access exactly as it was.

Suspension is the right tool for non-payment or a dispute. There is no delete, deliberately: filed invoices are legal records and the audit trail has to survive the commercial relationship.

A single Laravel application, organised as a modular monolith. Business logic lives in domain services; the Filament resources that draw the screens stay thin and call into them.

Invariants worth knowing

• One writer for the journal. Every entry goes through the posting service, which validates the lines, proves debits equal credits, asserts the period is open and numbers the entry sequentially. Nothing else writes journal entries.
• Money is never a float. Amounts are decimal strings handled with arbitrary-precision arithmetic, two places for money and four for unit costs, rounded half away from zero.
• Tenancy is a global scope. Every business-owned model carries a trait that scopes reads and fills the business on write. A missing filter yields no rows rather than someone else's rows.
• Document numbering is gapless. Numbers are issued under a row lock, so two concurrent invoices cannot take the same one.
• Lifecycle transitions are guarded. A document can only move along its defined path, and the check is in the service, not the interface.

Roughly five hundred automated tests cover the accounting engine, inventory costing, the FBR flow, the review workflow, imports and tenant isolation.

Both need the scheduler running. On a server that means one cron entry calling the scheduler every minute:

* * * * * cd /path/to/app && php artisan schedule:run >> /dev/null 2>&1

A queue worker is also required, because spreadsheet checking, PDF rendering and notifications are queued. If imports sit at pending forever, the worker is not running.

Requirements: PHP 8.4 or newer with the bcmath, gd and intl extensions, Composer, Node and npm, and MySQL 8 or newer.

composer install
npm install
cp .env.example .env
php artisan key:generate

Set the database connection in .env, then:

php artisan migrate --seed
composer dev

The seeders create an administrator, two tax lawyers and five demo businesses with about ninety days of trade, several hundred invoices and a filled FBR submission history, so every screen has something real on it.

Useful commands:

Work through this list. The first item is not optional.

1. Delete the development login route. A local-only sign-in shortcut exists at /dev-login/{email} in the web routes. It is double-guarded by the local environment and an off-by-default flag, and it must be removed from the codebase before the application is deployed anywhere.
2. Set APP_ENV=production and APP_DEBUG=false.
3. Generate a fresh application key and keep it safe. Losing it makes every stored FBR token unreadable.
4. Give the database its own user, not root, with only the privileges it needs.
5. Serve over HTTPS only.
6. Install the scheduler cron entry and a supervised queue worker.
7. Cache configuration, routes and views.
8. Arrange database backups and test a restore before you need one.
9. Confirm every business starts in sandbox.

Who can do what

FBR terms