OnlyTax

Inspiration

Calculating VAT is easy. Defending every number is not.

For accountants, a monthly tax close is not just arithmetic. A deductible purchase must be connected to the taxpayer’s activity, supported by valid documentation, and explainable later. When software jumps directly from documents to totals, the accountant is left reconstructing the reasoning.

This is especially relevant in Paraguay, where Law No. 6380/2019 (https://www.dnit.gov.py/en/web/portal-institucional/w/ley-n-6380-19) ties input-VAT deductions to the underlying transaction and its evidence.

We built OnlyTax around one principle: evidence before authority. The system may calculate and compile, but it must not silently guess an unknown product, invent a client fact, or hide how a number reached the final result.

What it does

OnlyTax turns an available month of sales and purchases into a VAT close an accountant can inspect, explain, and defend.

Monthly records → deterministic categorization → calculation ledger → explainable VAT fields → reconciliation → accountant package

Purchase descriptions are normalized into stable product identities before versioned activity and VAT rules are applied. Clear cases proceed automatically. Unknown or ambiguous products stop instead of being guessed.

When a tax result depends on a missing business fact, OnlyTax asks the client a factual question—not a tax question. The client can confirm the business purpose, reject it, or keep the item pending. If the configured cut-off arrives without an answer, the item is conservatively excluded with the reason preserved; the system never fabricates a client response.

The accountant can inspect:

• the original document description;
• normalized product identity;
• activity relationship;
• applied rule and condition results;
• supporting source references;
• monetary effect;
• every declaration-field dependency.

OnlyTax seals the package only after the source manifest, rule evaluations, ledger, and declaration draft reconcile. The completed package contains five accountant exports and remains explicitly marked Not filed.

The reproducible judge demo uses one synthetic month with 84 documents. It produces 83 deterministic outcomes and isolates one missing business fact. This is demonstration evidence, not a product limit.

How we built it

OnlyTax is a TypeScript and pnpm workspace with a server-rendered Express application and separate pure automation packages for normalization, categorization, VAT calculation, and declaration compilation.

We started with an existing categorization and package foundation and documented it separately from the new Build Week work. During Build Week, we added the raw-document runtime, the complete monthly workflow, client clarification states, accountant review, declaration-field provenance, reconciliation gates, exports, adversarial tests, and the runnable product UI.

GPT-5.6 Sol in Codex helped us:

• analyze two competing categorizer designs;
• separate product identity from tax treatment;
• merge them into one typed runtime engine;
• design the factual-question and configured-cut-off state machine;
• carry provenance through the ledger and declaration fields;
• implement fail-closed package sealing;
• build and iterate the five-step product experience;
• generate adversarial tests for unknown, ambiguous, stale, and altered evidence.

We used GPT-5.6 and Codex as build-time engineering collaborators. The monetary path in the finished project is deterministic and reproducible.

The human decisions defined the product boundary: clients provide facts, deterministic rules calculate tax effects, accountants retain review authority, and filing remains a separately authorized integration.

Challenges we ran into

Separating identity from tax treatment

The original designs mixed two different jobs: understanding what a messy purchase description refers to and deciding its tax treatment. Copying the old categories directly would have preserved that mistake.

We introduced a typed chain from observation to normalized identity, activity relation, rule evaluation, and final outcome. This made the logic easier to inspect and prevented a product label from silently becoming a tax decision.

Handling missing information without inventing authority

A simple yes/no flow was not enough. A client may not know the answer immediately, but the close still has a deadline.

We added a real pending state and a versioned cut-off policy. Before the cut-off, the client can still answer. At the cut-off, an unsupported deduction is excluded conservatively while preserving the pending request and recording zero invented client facts.

Keeping evidence consistent across the whole close

Traceability is useless if the document manifest, categorizer output, ledger, declaration draft, and exported package can drift apart.

OnlyTax reconciles these layers before sealing. Unknown identities, ambiguous matches, changed amounts, broken lineage, stale revisions, or altered evidence prevent package creation.

Making the demo safe without making it fake

The project needed to be fully runnable by judges without taxpayer data, credentials, external services, or access to Paraguay’s tax portal.

We created a versioned synthetic month and a deterministic local workflow. Playwright exercises only OnlyTax’s own loopback UI. The judge can inspect a complete result while the filing boundary remains honest and visible.

## Accomplishments that we're proud of

• A complete product flow from monthly records to accountant review and package—not just a categorization prototype.
• A real runtime categorizer operating on raw purchase descriptions rather than fixture-authored tax outcomes.
• A reproducible 84 documents → 83 deterministic outcomes → 1 missing fact demonstration.
• Seven reconciled declaration fields with document, rule, condition, and resolution provenance.
• Five usable accountant exports: canonical JSON, printable HTML, audit summary, document manifest, and reconciliation report.
• Fail-closed behavior for unknown products, ambiguous matches, altered evidence, broken lineage, and incomplete reconciliation.
• 25 focused product tests and 296 passing tests across the complete local suite.
• A first-party Chromium test covering clarification, accountant review, provenance, exports, responsive layouts, and the completed printable package.
• A judge build requiring no database, account, API key, credential, or external network service.

## What we learned The biggest lesson was that the valuable output is not the category or the final total. It is the reviewable chain between them.

We also learned that human-in-the-loop design works better when the human is asked for a fact within their authority. A client can confirm whether a purchase served the business; they should not be asked to choose a tax category or deduction rule.

Codex was most useful when we gave it explicit invariants to protect. It could compare competing designs, trace consequences across the codebase, implement the selected architecture, and attack it with negative tests. That was more valuable than generating isolated features.

Finally, explainability cannot be added as a report at the end. It has to exist in the intermediate contracts, state transitions, calculations, and failure behavior from the beginning.

What's next for OnlyTax

The next step is to test the workflow with independent Paraguayan accountants and expand the versioned rule coverage across more activities, document types, and monthly scenarios.

Future work includes:

• accountant-reviewed calibration of additional Paraguayan VAT rules;
• authorized document-ingestion connectors;
• richer multi-period review and amendment workflows;
• production tenant deployment and monitoring;
• a separately authorized filing integration.

The evidence package will remain the boundary: no external filing action should proceed unless the underlying close is complete, reconciled, and reviewable.

Built With

• css3
• drizzle-orm
• express.js
• gpt-5.6-sol
• html5
• node.js
• openai-codex
• playwright
• pnpm
• postgresql
• ssr
• typescript
• vitest
• zod