Proposal to design and follow OpenAPI contract

[chetanr25]

FireForm API Contract - First Draft Open for Review

Interactive docs (Swagger UI): https://fireform-gsoc.chetanr25.in

---

Why an API contract first?

Before writing a single line of backend code, I wanted to discuss about what the system accepts, returns, and promises not as a vague spec doc, but as a machine-readable OpenAPI contract that both humans and tools can work from.

The contract-first approach matters here because FireForm's pipeline has several moving parts (voice/text input → async LLM extraction → PDF generation), and without a shared contract, the API layer and the extraction logic would need to be built in lockstep by the same person. With a published contract, frontend, backend, and tests can be developed in parallel. Anyone picking up the project knows exactly what each endpoint expects without having to read the implementation.

---

How the pipeline maps to routes

The contract is organized as four sequential layers, each with its own endpoint group:

Layer	Routes	What it does
1. Input	POST /api/v1/input/text · POST /api/v1/input/voice	Accept a responder's incident narrative (text or audio)
2. AI Extraction	POST /api/v1/extract/{input_id} · GET /api/v1/extract/{extract_id}/validate	Run local LLM, extract structured data into the incident contract JSON
3. Form Generation	POST /api/v1/forms/generate/all · GET /api/v1/forms/{form_id}/pdf	Map incident data → agency-specific PDFs
4. Incident Management	GET /api/v1/incidents · GET /api/v1/incidents/{incident_id}	Tie all the pieces (input → extraction → forms) into one incident record

LLM extraction is async — the /extract call returns a job_id immediately, and the client polls /api/v1/jobs/{job_id} for status. This keeps the API responsive even when the local model takes a few seconds.

---

Template registry - extensibility without code changes

One of the core goals is that any agency should be able to register their PDF form and have it supported immediately, without a developer writing a mapper or pushing a release.

The /api/v1/templates group covers this: an agency admin uploads their PDF template, marks field positions, and maps those fields to the canonical incident contract. From that point on, POST /api/v1/forms/generate/all automatically includes their form in the output.

---

A note on multi-agency access

Right now the design targets fully local deployments one org, one server, all data stays inside their infrastructure. Agency scoping (ApiKeyAuth per agency) is already in the contract to ensure incident data is never exposed across org boundaries within a single deployment.

There's an open question worth discussing:

• should the contract also support a future shared-server model where multiple agencies connect to one hosted endpoint? That changes how auth, data isolation, and routing work. I haven't locked this in

happy to hear thoughts before it gets baked into the implementation.

---

Contract and Visual flow-chart of the functionality

This is API design which I would like to propose. (Clicking on the image below will download a PDF of 6 pages).
These APIs were designed after taking all our requirements and constraints into consideration.

---

What I'd love feedback on

• Does the four-layer pipeline structure make sense, or should extraction and form generation be collapsed?
• Any fields missing from the incident contract schema? See the incident contract schema at fireform-gsoc.chetanr25.in/incident-contract on the Swagger site.
• Thoughts on the multi-agency / shared-server question above.

The contract is the easiest thing to change right now much easier than refactoring a running backend or whole system later.

Once the API-Contract is finalised, I think we can have the contract in our codebase itself for future references.
https://fireform-gsoc.chetanr25.in

[chetanr25]

would love to hear feedback from the community
@marcvergees @vharkins1 @abhishek-8081

I believe that we need to finalise our APIs which we would be building and then work on them one by one.

[marcvergees]

Okay, let's go step-by-step.

1. Your Question: Does the four-layer pipeline structure make sense, or should extraction and form generation be collapsed?
   I like the fact that everything is separated, that way we'll have the option to reutilise endpoints in case we need them in the future.

2. Regarding the table you did at the beginning, I like the idea of having a 4th row with incident management, which it'll allow us to create a "Incident History" and build analytics from here, and any kind of useful features in a close future.

3. Even though I know that the structure of the API would change a lot if it's local or server, let's focus on local systems, so that you don't have to implement auth keys, and there's no need to build a "manager" role that creates templates. At least, not yet. Let's keep it for a 2nd phase.

4. I like the fact of having the openapi contract in our codebase, as you were pointing out too.

5. Remember that we'll need to imlement jobs because of async processes.

6. I've going again over your document with the whole specification of the OpenAPI contract. I think it's the approach to follow if we migrate to cloud system, but not know.

[chetanr25]

Thanks for going through the proposal, a couple of things I want to confirm before we move ahead.

We can definitely remove agencies and auth if we're focusing on hosting the FireForm backend within an organisation. As you mentioned, we can keep that for phase 2 when the same server needs to handle multiple agencies with different permission levels, auth becomes necessary. But for now, going ahead with all other APIs without authentication makes complete sense.

My assumption here is that the FireForm backend will first be hosted on an organisation's local servers, accessible only within their network. In that case, there's less need for auth the infrastructure boundary handles isolation on its own. Phase 1 is essentially a closed local system.

Phase 2 would then be about adding internal permissions within an organisation, and if we ever decide to host this on cloud and serve multiple organisations, that's when the agencies APIs need to be built.

Just wanted to confirm is this the correct requirement and the direction that FireForm is heading? And can we have the contracts in the codebase itself? If yes, I'll raise a PR for that.

Before we go ahead, I think it'd be good to have a round of discussion on the overall API architecture whatever suits FireForm best, keeping in mind all requirements and long-term maintainability. This proposal is my way of thinking, and I definatly want inputs from the community and find a middle ground that works for everyone. The main idea is to first design and document our technical requirements with the end product in mind, so we have a clear direction to work on FireForm going forward.

---

TL;DR

Phase 1 is a local org deployment with no auth core pipeline only, contracts live in codebase. Phase 2 introduces permissions, multi-agency support, and an optional path to cloud hosting.

Feature	Phase 1	Phase 2
Voice & text input	Yes	-
LLM extraction	Yes	-
PDF form generation	Yes	-
Incident history & analytics	Yes	-
Async job tracking	Yes	-
Auth	-	Yes
Multi-agency support (Agencies API)	-	Yes

[marcvergees]

You're right about everything you said. Exactly that's what we need in each phase, as we've been discussing so far these weeks. Feel free to go ahead and raise PR for that.

[chetanr25]

Perfect, will raise PR for this.

[chetanr25]

Just raised PR #535

Based on the requirements of the FireForm, I put together incident-contract.yaml (see file) this defines every field we store per incident as JSON in the database. The idea is that this becomes the single standard the whole pipeline works from: the LLM extracts into it, and all form mappers read from it. I built an interactive viewer at fireform-gsoc.chetanr25.in/incident-contract to make it easier to go through open to feedback on any fields that are missing or don't make sense.

Would be good to discuss this before we move ahead once the pipeline is built around this, changing it will be a lot of work. Adding fields is fine, but changing the structure later will affect everything. So I think it would be better if we review this and finalise the JSON schema what ever works for FireForm

Looking for your suggestions and Please let me know if any changes are required.

Would love to have everyone's Feedback @marcvergees @vharkins1 @abhishek-8081 (For the PR #535 )

[abhishek-8081]

Thanks for putting this together, @chetanr25 .

The contract-first approach makes sense to me here — with several of us working in parallel and a multi-step pipeline, having an agreed contract up front is the right call. The four-layer split and deferring auth/multi-agency to Phase 2 both look reasonable for a local-first deployment.

I'll go through #535 and leave my detailed feedback on the schema there.

Thanks for driving this.