GST Helper：本地優先的 GSTR-1 準備助理

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

I built GST Helper, a local-first AI workspace that helps a small business prepare selected GSTR-1 values from sales invoice PDFs.

The demo company is BharatBiz, a fictional small business based in Bengaluru. The user starts by loading outward-sales invoice PDFs. GST Helper reads the invoices, extracts values, shows page evidence, and turns the documents into a guided GSTR-1 review flow.

The current app prepares these GSTR-1 sections:

• Table 4A regular domestic B2B invoices
• Table 12 B2B HSN/SAC summary
• Table 13 document numbers issued

It shows the invoice value including tax, taxable value, IGST, CGST, SGST or UTGST, cess, total tax, and invoice count for the supported B2B scope. It also creates a reference PDF tied to the saved review revision, so the user can inspect the same values before downloading the file.

The problem is simple: small business owners and bookkeepers often do this first pass manually. They read invoice PDFs, copy values into spreadsheets, check invoice numbers, and then use those figures while working in the GST Portal. That work is slow, error-prone, and full of accounting language that is not friendly to a non-expert.

GST Helper is meant for a small business owner, bookkeeper, or accountant who wants a faster way to prepare and review the numbers before portal entry. The paid version could charge for private local workflows, more GST sections, accountant review packs, and better import and export support.

The app does not file a return, connect to the GST Portal, or claim that the whole GSTR-1 return is complete. Other GSTR-1 sections must be handled separately. That boundary is visible in the product because tax software needs trust more than magic.

Demo

Video demo: https://youtu.be/RFq9whXetRg

The demo shows the full BharatBiz flow:

1. Load sample sales invoice PDFs.
2. Confirm the seller GSTIN, tax period, and turnover band.
3. Review invoice fields with page evidence.
4. Save the reviewed values.
5. Inspect the Table 4A totals.
6. Generate a verified reference PDF.
7. Use the review chat beside the final PDF.

Code

Repository: https://github.com/sonu0702/pgst

GST Helper

GST Helper is a local-first GSTR-1 preparation app for BharatBiz, a fictional small business based in Bengaluru. It turns outward-sales invoice PDFs into reviewed values, a clear summary for the supported GSTR-1 sections, and a reference PDF the user can inspect before downloading.

This release prepares only regular B2B invoices in Table 4A, the B2B HSN/SAC summary in Table 12, and documents issued in Table 13. It does not prepare a complete GSTR-1 return, connect to the GST Portal, submit or file a return, or decide GST treatment. Other applicable GSTR-1 sections must be prepared separately. The GST Portal accepts a JSON workflow through its offline tool, but the portal still validates the account and return when the user uses that file.

What the app does

• Starts with outward-sales PDFs, then suggests seller GSTIN and tax period with page evidence before asking for return details.
• Shows observed invoice-number…

How I Built It

The app is a single repository with a React frontend and a FastAPI backend.

Tech stack:

• Frontend: React, TypeScript, Vite
• Backend: Python, FastAPI
• Local AI: Ollama with Gemma 4
• PDF processing: Python PDF extraction with optional local OCR support
• Export artifacts: reference PDF and supported-section JSON
• Storage: no database in this prototype. Reviews live in temporary process memory.

The user flow starts with source documents, not a chatbot. That choice matters. Invoices are the source of truth, so the app first reads the PDFs and creates a review workspace from them.

The backend extracts invoice fields and line items, keeps compact evidence snippets, and builds a temporary GSTR-1 review case. The frontend lets the user inspect and edit each value. When the user saves, the backend runs local checks for the supported sections and returns readiness results.

Gemma 4 is used through Ollama for a narrow review task. It can answer questions about values already in the review or prepare a proposed edit from invoice evidence or from a value the user states. It cannot decide tax treatment, calculate GST, approve filing, or submit anything.

The user stays in control:

• The model proposes changes.
• The user applies the proposal.
• The user reviews the form.
• The user saves the revision.
• The user regenerates the PDF if anything changed.

The reference PDF is tied to the saved revision. The app renders the PDF back in the browser and verifies the expected content before the user downloads it.

Why Does Open Innovation Matter?

Open innovation matters here because tax preparation needs transparency, local control, and the ability to inspect the workflow.

A closed hosted API can produce a polished answer, but that is not enough for this use case. A small business owner needs to know where a number came from and what the app did with the source document. GST Helper keeps the review path visible: invoice evidence, editable fields, saved revision, local checks, and a reference PDF.

Open-weight local AI also changes the privacy story. In this prototype, Gemma 4 runs locally through Ollama. The app does not need to send invoice details to a hosted model API. That made it possible to build an AI-assisted review flow that still respects sensitive business documents.

Open-source tools also made the project practical for a hackathon:

• FastAPI made the backend small and inspectable.
• React and Vite made the review UI fast to iterate.
• Ollama made local Gemma 4 setup approachable.
• Python PDF tooling made extraction and reference PDF generation possible without building a document pipeline from scratch.

The project is not trying to replace a tax professional or the GST Portal. It is trying to make the preparation step clearer, safer, and more reviewable.

My Agent Session

I used Codex as an AI coding agent throughout the build. The agent helped with product scoping, GSTR-1 flow design, FastAPI and React implementation, sample invoice generation, UI polish, PDF review, and the demo walkthrough.

The most useful part was not code generation alone. The agent helped keep the product narrow. Whenever the app started to look like a generic invoice-review demo, I pushed it back toward one clear filing workflow: GSTR-1 preparation from sales invoices.

That made the final project stronger. It has a specific user, a specific filing task, a clear supported scope, and visible review boundaries.

Prize Categories

gemma

Team

This is a team submission. Published by @sonu0702.

Teammates:

• @chandan_sharma