This is the engineering documentation for the TaxChad platform. It sets out what has actually been built, how it is put together, where the hard guarantees live, and what is still missing. Every number on this page was read from the live database and the repository, not estimated.
Everything below is either code in one repository or a managed service with a data processing agreement behind it. There is no second system, no offshore team's codebase, and no undocumented service in the path between a customer's bank line and a filed return.
Nothing here is exotic. Every choice in the stack is a mainstream, well-supported technology with a large hiring pool, because the interesting part of this business is the accounting logic, not the framework.
This is the path every pound takes through the system. It is worth reading slowly, because the design decisions that matter are all visible in it.
A bank line arrives by open banking feed, CSV, OFX or PDF statement. PDF and photo documents are text-extracted by AWS Textract or a language model, and the extracted rows are always shown to a human before anything is posted.
The rules engine walks the client's rules in a total, reproducible order and takes the first one whose conditions all hold. Nothing is scored, guessed or learned. If no rule matches, the line stays uncoded and visible rather than being assigned a plausible answer.
Where VAT applies, the tax is rounded once and the net is derived as the remainder, so net plus VAT always equals gross to the penny. A property test asserts this across thousands of random amounts and every VAT code.
The posting core writes balanced double-entry journal lines. The application pre-checks them for a readable error message, and then the database refuses anything that does not balance, in the transaction currency and in the home currency, at commit time.
A nightly job replays the invariant suite across the whole ledger. Every guard rejection, in the app or in the database, is written to an insert-only guard log the accountant can read.
Trial balance, profit and loss, balance sheet, VAT return and the tax computations are all derived from the ledger on read. There is no second set of numbers to fall out of step with the first.
The accountant starts at the trial balance, not the shoebox. Accounts and Corporation Tax are prepared and filed by a regulated person at PowerStone, under their practising certificate and their insurance.
VAT and Self Assessment submissions leave through the MTD APIs with the fraud prevention headers HMRC requires, routed through a fixed-address relay so the vendor headers are truthful. Every call and its response is written to an audit log with credentials masked.
Categorisation is a rules engine, not a model. Five match types, conditions combined with AND, a total ordering that falls through to the rule's own identifier so the answer is always the same. Run it twice on the same books and you get the same ledger.
If a rule is a per-row truth, it becomes a database constraint, not a warning on a dashboard. Journals cannot be saved unbalanced. A journal line cannot point at another client's nominal. The trial balance is re-totalled at commit.
Company, sole trader, landlord, VAT registered or not, all share one chart. Crossing the VAT threshold flips a boolean rather than migrating a chart. Every income and expense code carries its tax box, so a quarterly update is a grouping, not a rebuild.
There is no separately deployed API service and no public write endpoint. The application talks to itself through typed server functions, the assistant integration runs read-only as the calling user with row-level security applied, and webhooks are individually secret-checked.
TaxChad Ltd is a software company. Regulated accountancy is delivered by PowerStone Accountants Ltd under its own licence, insurance and engagement letters. That separation is what makes the promise honest: software is software, and when you want a regulated opinion there is a named professional, a practising certificate and professional indemnity insurance standing behind it.
The standing rule in this codebase is that nobody accepts "done" or "secure" as an answer. Every security finding this year was surfaced by demanding the actual code or the actual value. That discipline is the reason the honest gaps below are written down at all.
TaxChad is not HMRC recognised today and does not claim to be. There has been no third-party penetration test. Bank feeds are integrated but not yet carrying live customer volume. The restore path from an off-site backup has been proven to the point of decryption and row counts, but not yet by a full load into a scratch database. Each of these has an owner and a date, and each is described plainly in the pages that follow.
TaxChad was built by its founder working with AI coding agents under a strict operating contract, inside a working accountancy practice, against real client books. That is unusual, so it is worth being precise about what makes it safe rather than reckless.
The honest answer on scale is a list of what breaks first. Nothing in this architecture has to be rebuilt to serve a few thousand companies, and the parts that will need attention are known and written down.
| Layer | Where it goes under load | What we would do |
|---|---|---|
| Front end and server functions | Stateless, rendered at the edge, scales horizontally with traffic | Nothing structural. Cost scales close to linearly with usage. |
| Database | A single Postgres instance is comfortable well past that for a ledger workload of this shape | Vertical scale first, then read replicas for reporting. Tenant data is already firm-scoped, so sharding by firm is available and does not need a rewrite. |
| Document storage and OCR | Per-document cost, the most usage-sensitive line | Already metered per client. Extraction is cached and never repeated for an unchanged document. |
| Scheduled work | Nightly sweeps grow with the number of clients | Jobs are already chunked and idempotent, with a queue extension in place for fan-out. |
| The regulated review layer | This is the real constraint, not the software | Accountant capacity per client is the number that decides margin. It is a hiring and workflow question, which is exactly why the practice management side was built into the product rather than bolted on. |
Each page below stands on its own and is written for a technical reader. If you want to send an engineer at this, send them here.
Double entry, the integrity guards that live in the database, multi-currency, the chart of accounts, and how 555 migrations were kept safe.
How one firm is kept out of another firm's books, what the two CI isolation gates actually assert, the audit trails, and the gaps we have not closed.
Exactly how a transaction is coded, why it is deterministic, where extraction models are allowed to touch the data, and the tax engines on top.
HMRC, the fraud prevention header problem and how it was solved, open banking, payments, Companies House, FX, and every scheduled job.
The CI pipeline gate by gate, golden fixtures, the change ledger, backups and disaster recovery, monitoring, and what we do when something breaks.
The plain-English summary of how we handle your data, what has been audited, what has not, and how to report a vulnerability.