Read Me First — Tax Compliance Engine

A plain-language introduction for anyone seeing this project for the first time. No programming knowledge needed. If you work in finance, operations, or tax at a business that sells to customers in more than one US state, this document is for you.

---

1. Who this is for

This software is built for businesses that sell across US state lines — online shops, subscription software (SaaS) companies, wholesalers, and anyone else who has to collect sales tax from customers in many different states and then report and pay that tax to each state on schedule.

The people who will care about it most:

• Finance and tax managers, who are responsible for charging the right tax, registering in the right states, and filing returns on time.
• Operations teams, who keep exemption certificates and filing deadlines from falling through the cracks.
• Auditors and accountants, who need to see exactly why a particular amount of tax was charged on a particular sale, months or years later.
• The developers at those businesses, because this product has no screens of its own — it is a service that other software talks to (more on that in section 4).

You do not need to be a developer to read this document or to understand what the product does. You do need one (at least briefly) to connect it to your other systems.

---

2. What it does

In a few plain sentences:

• It calculates US sales tax, precisely, for every sale. You tell it what was sold, for how much, when, and where the customer is. It answers with the exact tax to charge, broken down by every level of government that gets a share — state, county, city, and special districts — down to the penny, with an explanation of which rate and rule produced each line.
• It watches where you owe obligations. States can force you to collect their tax once your sales there pass a threshold. The engine keeps a running total per state and warns you as you approach — and cross — each state's line, so you can register before penalties start.
• It keeps track of exemption certificates. Some customers (resellers, nonprofits, government bodies) don't pay tax if they give you a valid certificate. The engine stores those certificates, watches their expiry dates, and automatically stops charging tax on sales they cover.
• It prepares your tax returns. At the end of each filing period it adds up everything for each state you're registered in — gross sales, exempt sales, taxable sales, tax collected — and drafts the return for a human to review, approve, and export.
• It remembers everything. Every calculation, every change, every approval is written to a permanent, append-only history, so an auditor can always ask "why was this number what it was?" and get a complete answer.

What it deliberately does not do (yet): it handles US sales tax only, in US dollars only. It does not file returns electronically with the states — it prepares and exports the numbers, and a person submits them. And it has no screens of its own — see section 4.

---

3. The domain: US sales tax in a nutshell

If you're new to US sales tax, here is the minimum you need to know.

There is no national sales tax. Sales tax in the US is set by states — and by counties, cities, and special districts (transit authorities, stadium districts, and the like) inside them. Forty-five states plus Washington, D.C. levy a statewide sales tax. Five states — Alaska, Delaware, Montana, New Hampshire, and Oregon — have no statewide sales tax at all (Alaska still lets its towns charge their own). All told, a seller can face thousands of overlapping local tax areas, each with its own rate.

Rates are only half the problem. States also disagree about what is taxable. Clothing is tax-free in some states and fully taxed in others. Software sold as a subscription (SaaS) is taxable in Texas, not taxed in California, and taxed at a reduced rate in Connecticut — and the rules change over time. Getting "how much" right requires getting "is this even taxable here" right first.

You only collect where you have "nexus." Nexus means a sufficient connection to a state. Having an office or warehouse there creates it. But since a 2018 Supreme Court decision (the Wayfair case), simply selling enough into a state creates it too — most states set the bar at $100,000 of sales per year. This is called economic nexus, and crossing a threshold without noticing is one of the most expensive surprises in small-business tax: the state can demand back taxes you never collected.

Some buyers are exempt. A retailer buying goods to resell, a registered nonprofit, or a government agency can give you an exemption certificate — a formal document saying "don't charge me tax." You must collect, store, and keep these current. Honor an expired one and the liability is yours.

You report and pay on a schedule. In every state where you're registered, you file a return for each filing period (monthly, quarterly, or annual, depending on the state and your volume) by a due date, listing your sales and paying the tax you collected. Miss the date and penalties apply.

This engine exists to carry that whole burden: the rate lookup, the what's-taxable rules, the nexus watching, the certificates, the calendars, the returns, and the paper trail.

---

4. Where it fits

This product is an API service, not an application with screens. API stands for Application Programming Interface — a way for other software to ask questions and get answers. There is no login page, no dashboard, nothing to click. Your webshop, billing system, or accounting software sends the engine a description of each sale as it happens, and the engine answers in a fraction of a second with the tax to charge. Your staff never "use" it directly; the systems they already use talk to it behind the scenes.

That design is deliberate: tax calculation has to happen inside your checkout or invoicing flow, at the moment of sale, so the calculation engine lives where your other software can reach it.

It works alongside:

• E-commerce platforms and webshops — tax quotes at checkout.
• Billing and subscription systems — tax on every invoice line.
• ERP and accounting systems — committed sales feed returns; nexus alerts and filing reminders can be pushed to them automatically.
• Alerting and chat tools — the engine can send automatic notifications (for example "you just crossed Illinois's threshold" or "the Texas return is due in 7 days") to any internet address you register.

One deployment serves one company (which may have several legal entities inside it). It is not a multi-company hosted service you sign up for; it's software you run — or have run for you — for your own business.

Because the product is AI-generated and API-first, it is also a foundation: any team (yours, or a specialist from the wbsp.ai community) can build a custom dashboard or admin screens on top of it, branded however you like. Everything those screens would need is already available through the API.

---

5. First run: try it in five minutes

The fastest way to see the product working is the standalone preview — a single self-contained package that runs the whole engine plus a ready-made demo company on your own computer, with nothing else to install or connect. The full, exact instructions live in preview/README.md; here is what to expect in plain terms.

1. Start the preview. It takes half a minute the first time. When it's ready, the engine is listening on a local address on your machine. It arrives pre-loaded with a fictional SaaS company — Northwind Dynamics, Inc., based in Austin, Texas — with a year of trading history already in it (see section 10 for what's inside).
2. Prove it's alive. Ask for its health status; it answers that the service is up and its data stores are connected.
3. Get a token. Access works like a machine password: the preview ships with demo credentials (client name demo-admin, secret demo-preview-secret). You exchange them for a temporary access token — think of it as a one-hour visitor pass — and attach that pass to every request. For quick experiments the preview can also accept a fixed demo pass instead; preview/README.md explains both.
4. Make your first calculation. Describe a sale — two software subscriptions and an add-on, sold to a customer in Austin — and the engine answers with the exact tax: which jurisdictions share it (Texas state, the city of Austin, the transit district, Travis County), each one's rate, and each one's cut in exact cents. Change the customer's address to Portland, Oregon, and the tax is zero — with a written explanation of why it's zero.

From there, explore: replay the same request to see duplicate protection, commit the sale, look at the nexus dashboard (Illinois is flagging red — the demo company has crossed Illinois's sales threshold without registering), and open the drafted Texas quarterly return.

Everything you do in the preview is throwaway: stop it and the demo data is gone, so you cannot break anything that matters.

---

6. Setting up for real use

Moving from the preview to a real deployment is an operator's job, and there is a dedicated guide for it: user-docs/production-initialization.md. Here is the shape of it in plain terms.

• Base data comes preloaded. A fresh deployment is initialised with the reference data the engine needs to work: the full map of US taxing jurisdictions (all 50 states plus D.C., with counties, cities, and districts), their tax rates with the dates each rate is in force, the rules about which state's address governs a sale, each state's economic-nexus threshold, the product tax-code registry, and the state-by-state taxability rules for software and digital goods. This data comes from published standard files, and — importantly — it only ever changes through a reviewed update process, never by quietly editing the database.
• Credentials are issued, not invented. Initialisation prints a one-time bootstrap admin credential. From there you create named API credentials for each system that will connect — one for the webshop, one for the ERP — each with only the permissions it needs. Secrets are shown once and stored as hashes; keep them in your company's secret store.
• Your systems point at the engine. A developer configures your webshop or billing system with the engine's address and its credential. Every request carries that credential; every answer is structured data they can program against. The complete technical contract is in user-docs/api-reference.md (plain-English summary) and user-docs/openapi.yaml (the machine-readable version developers generate client code from).
• You tell it about your company. Your legal name and tax ID, the states where you are already registered to collect (with your permit numbers), your products and what tax category each belongs to, your customers, and any exemption certificates you already hold. Recording a registration in a state makes the engine build that state's filing calendar automatically.

One honest caveat: sales tax rates and rules change constantly in the real world. The engine ships with a solid reference dataset and a careful, human-reviewed process for importing updates — but keeping that data current is an ongoing operational responsibility, not a one-time setup step (see section 8).

---

7. Day to day

Once connected, routine life with the engine looks like this:

• As orders happen, your checkout or billing system asks for a calculation and shows the tax to the customer. If the same request ever arrives twice — a network retry, a double-click — the engine recognizes it and answers with the original result instead of recording a duplicate sale.
• When an order is final, the sale is committed. Only committed sales count toward nexus tracking and tax returns; a cancelled order is voided, which cleanly reverses it while keeping the history.
• Nexus alerts arrive on their own. When your sales in a state reach three-quarters of that state's threshold, and again when they cross it, the engine sends an automatic notification to wherever you've chosen (for example your ERP or a chat channel). The nexus dashboard data — one call away — shows every state, your running total, the threshold, and whether you're registered.
• Certificates work in the background. When a sale matches a customer with a valid exemption certificate for that state, the tax simply isn't charged, and the certificate is cited in the explanation. When a certificate expires, taxing resumes automatically. Uploading a new certificate seals the document with a fingerprint so any later tampering is detectable.
• Each filing period, the engine drafts a return per registered state: gross sales, exempt sales, taxable sales, tax collected, broken down by county, city, and district. A person reviews the draft, can make documented adjustments, approves it, and exports the return package (a printable document or a spreadsheet, both stamped with an integrity fingerprint) to submit to the state. Returns whose totals swing unusually from the previous period are flagged for a second look. Filed returns are frozen forever — corrections happen through a linked amended return, never by rewriting history.
• Deadline reminders go out automatically a week and a day before each due date, and overdue filings are flagged.

---

8. Ongoing care

The engine runs quietly, but a few things need periodic human attention:

• Rate and rule updates. States and cities change their rates and taxability rules throughout the year. Updates are loaded as staged batches: the engine shows a reviewer exactly what would change, an authorized person approves, and the new figures take effect on their official dates — with the whole process recorded in the audit trail. Nobody can slip a rate change in unreviewed.
• Review the drafted returns each period. The engine drafts them; a person with the tax-manager role must review and approve before anything is treated as final.
• Keep certificates current. Watch for certificates nearing expiry and chase customers for renewals; expired certificates stop exempting automatically, which can surprise a long-standing customer if nobody told them.
• Act on nexus alerts. When the engine says you've crossed a threshold in a state where you aren't registered, that's a call to action: register with the state, then record the registration in the engine so collection and filing begin properly.
• Backups and uptime. When the engine is run on the WBSP platform, the platform handles the underlying database and backups. If you run it yourself, protecting the database is on you — it holds your financial records and is kept indefinitely by design.

---

9. Who can do what (roles)

Access is controlled by three roles, attached to each API credential:

• Admin — can do everything: company settings, issuing API credentials, and approving rate-update batches, on top of all daily operations.
• Tax manager — the day-to-day operator: products, customers, exemption certificates, registrations, reviewing and approving returns, and approving rate-update batches. Cannot manage API credentials.
• Auditor — read-only. Can look at everything, including the full history, but cannot change anything. Ideal for external accountants or a tax authority's reviewer.

If a credential tries to do something its role doesn't allow, the engine refuses with a clear "insufficient permission" answer.

---

10. The demo data, and starting fresh

The preview (and the optional demo seed for local development) loads a coherent fictional scenario, sized to show every feature:

• The company: Northwind Dynamics, Inc., a SaaS seller headquartered in Austin, Texas, selling cloud subscriptions, software, services, and one hardware appliance — 10 products across several tax categories.
• 12 customers — businesses, nonprofits, and government bodies across the country, including a city IT department and a school district.
• 122 transactions of realistic history across nine states, in a mix of calculated, committed, and voided states.
• Registrations in 5 states — Texas (physical presence) plus California, New York, Washington, and Colorado (economic nexus) — each with a permit number and filing frequency.
• The Illinois alert: enough sales into Illinois to be at roughly 137% of that state's $100,000 economic-nexus threshold while unregistered — deliberately left that way so you can see the exposure warning exactly as a real company would. Connecticut is a quieter early-stage version of the same story.
• 7 exemption certificates spanning the whole lifecycle: valid ones (resale, government, expiring soon), plus expired, pending, and revoked examples.
• 6 tax returns — recent quarterly and monthly drafts across the registered states, plus one already-filed Texas return — and a filing calendar of 36 entries with statuses from filed to upcoming.
• 3 notification subscriptions, including one that has been automatically deactivated after repeated delivery failures, so you can see delivery health tracking.

To start fresh instead, run the production-initialisation process described in user-docs/production-initialization.md. It wipes the database (with heavy-handed confirmation prompts, because it's irreversible) and loads only the reference data and a bootstrap credential — no fictional customers, no demo sales. Never load the demo data into a real deployment.

---

11. Glossary

• API (Application Programming Interface) — a way for software systems to talk to each other. This product is an API: other programs ask it questions; there are no screens for humans.
• Audit trail — the permanent, append-only record of everything that happened: every calculation, change, and approval, with timestamps and who or what did it.
• Economic nexus — the obligation to collect a state's sales tax that arises purely from selling enough into that state (commonly $100,000/year), even with no physical presence there.
• Exemption certificate — a formal document from a buyer (reseller, nonprofit, government) stating a sale to them should not be taxed. Must be valid, current, and kept on file.
• Filing period — the stretch of time a tax return covers: a month, a quarter, or a year, depending on the state and your volume.
• Idempotency — the guarantee that sending the same request twice has the same effect as sending it once. Protects against duplicate charges when networks hiccup.
• Jurisdiction — any level of government that can levy sales tax: a state, county, city, or special district (such as a transit authority).
• Nexus — a sufficient connection to a state that obliges you to collect its sales tax. Created by physical presence or by economic nexus.
• Nexus threshold — the sales level (dollar amount and/or number of transactions) at which economic nexus begins in a given state.
• Registration — formally signing up with a state's tax authority to collect and remit its sales tax, evidenced by a permit number. You may only collect where you're registered.
• Return (tax return) — the periodic report filed with a state listing your sales and the tax collected, accompanied by payment.
• SaaS — "software as a service": software sold by subscription rather than as a boxed product. States disagree sharply about whether and how to tax it, which is why the engine tracks the rules per state.
• Sourcing — the rules deciding which location's taxes apply to a sale: usually the customer's location for out-of-state sellers, sometimes the seller's location for in-state sales, varying by state.
• Tax code — a category label for a product (physical good, SaaS, digital good, professional service, and so on) that the engine uses to decide how each state treats it.
• Taxability — whether a given product is taxable, exempt, or taxed at a reduced rate in a given place.
• Webhook — an automatic message the engine sends to an internet address you choose when something happens (a nexus threshold crossed, a deadline approaching). Signed so the receiver can prove it's genuine.

---

12. The other documents in this folder

Everything under user-docs/:

• api-reference.md — the plain-English summary of everything the API can do: each operation, how access credentials work, how errors are shaped, and how duplicate-protection keys behave. The first stop for the developer connecting your systems.
• openapi.yaml — the complete, machine-readable technical contract of the API, in the industry-standard OpenAPI format. Developers use it to generate client code and validate requests automatically. Not meant for casual reading.
• production-initialization.md — the operator's guide for preparing a real stage or production environment: what gets wiped, what gets loaded, the safety confirmations, and how the one-time bootstrap credential works.
• store-thumbnail.png — a marketing image for catalog listings; not documentation.

Elsewhere in the project: preview/README.md (running the standalone preview), README.md at the project root (the product pitch and vision — note it describes the long-term ambition including international tax, while the shipped core today is US-only), and docs/walkthrough-screenshots/ (a narrated tour of the API with real captured responses — a good second thing to read after this document).

---

13. Common questions and gotchas

My calculation came back with zero tax. Is something broken? Usually not — there are four legitimate reasons, and the response always says which one: (1) the customer is in a state with no sales tax (Oregon, Delaware, Montana, New Hampshire, Alaska); (2) your company is not registered in that state, and the engine will not invent a tax you're not authorized to collect — it returns zero with a not_registered explanation and flags it if you're approaching nexus there; (3) the product is exempt in that state; or (4) a valid exemption certificate covers the sale. Zero tax is always a positive finding, never a quiet fallback.

When is an error a real error? If the engine should have a rate for a place and date but can't find one — a gap in the reference data — it refuses to guess. You get a clear rate_data_unavailable error naming the jurisdiction and date. This is deliberate: charging nothing by mistake is far worse than asking for help.

Can it file my returns with the states for me? No. It prepares, checks, and exports the return package; a person submits it to the state (electronically or on paper). Electronic submission is a possible future addition.

Does it handle international tax or other currencies? Not in this version. It is US sales tax only, in US dollars; anything else is rejected with a clear error. International VAT/GST is part of the longer-term vision, not the shipped core.

What happens if my system sends the same request twice? Every request that changes something carries a caller-chosen key. A repeat with the same key gets the original answer back, unchanged, with no duplicate record. Reusing the key for a different request is refused outright.

Can I ask about past or future dates? Yes. Every calculation carries the sale's date, and the engine applies the rates, rules, and certificate validity exactly as they stood (or will stand) on that date. Re-running a calculation from months ago reproduces the original answer to the penny, even if rates have changed since.

A loyal customer was suddenly charged tax. Why? Most likely their exemption certificate expired or was revoked — the engine stops honoring it the moment it lapses. Check the certificate's status, renew it, and tax will stop again automatically.

Is the demo company real? No — Northwind Dynamics and all its customers, permits, and certificates are fiction, crafted to exercise every feature. Use the preview to explore; use production initialisation for anything real.

---

14. Where to get help

This project is part of the WBSP community — a network of people building and customising AI-generated business software. If you get stuck, want advice on integrating the engine with your systems, or would like someone to build a branded dashboard on top of it (or tailor the engine itself to your exact requirements), visit https://wbsp.ai. Community members have built many variations of this and other applications, and someone there can help you make this one yours.