[FEAT]: Field Mapping Wizard for Non-Technical Users

[krrishrastogi05]

Name: 🚀 Feature Request
About : Suggest an idea or a new capability for FireForm.
Title: "[FEAT]: Field Mapping Wizard for Non-Technical Users"
labels: enhancement

---

📝 Description

I propose building a Field Mapping Wizard to make FireForm truly self-service. Right now, setting up a new agency's PDF template means a developer has to go in and manually map the JSON fields. That's a huge technical blocker for fire departments and emergency services that don't have dedicated IT staff.

The end goal here is a full-stack, visual drag-and-drop interface where administrative staff can just upload a PDF and visually map the fields to our IncidentSchema.

To make this manageable and easy to review, I'd like to break this down into phases. This specific issue focuses strictly on Phase 1: the backend PDF Field Detection engine, which we absolutely need before we can build out the frontend canvas.

💡 Rationale

If FireForm is going to scale globally as a Digital Public Good, we can't be the bottleneck for every new form that a department wants to use. Giving fire chiefs and admins the power to configure their own templates will democratize the platform, completely remove IT dependencies, and speed up adoption massively.

🛠️ Proposed Solution

I want to start by laying the backend groundwork to power the future frontend canvas. Here is the plan for Phase 1:

• Introduce a PDFFieldDetector class to parse the /Annots and /Widget subtypes of uploaded PDFs.

• Extract the exact metadata we'll eventually need for the UI: Field Name, Type (Text, Button, Choice), and Bounding Box Coordinates (X, Y, Width, Height).

• Wire this up to a new FastAPI route (e.g., /api/v1/wizard/detect-fields).

• Logic change in src/ (New field_detector.py module and api/routes/wizard.py).

• Update to requirements.txt (Adding pypdf for the explicit annotation extraction).

• New prompt for Mistral/Ollama (Not applicable for this phase).

✅ Acceptance Criteria

How will we know this is finished?

• The endpoint successfully extracts Text (/Tx), Button/Checkbox (/Btn), and Choice/Dropdown (/Ch) fields.
• Returns precise X, Y, Width, and Height coordinates for frontend visual rendering.
• Safely ignores pages or PDFs without interactive form widgets.
• Feature works in Docker container.
• JSON output validates against the schema and is fully testable via the FastAPI Swagger UI (/docs).

📌 Additional Context

Before: Mapping a PDF requires developers to manually open the file, inspect the field names, and hardcode JSON dictionaries.
After (End Goal): Users upload a PDF in the UI, visually see all fillable fields highlighted, and drag-and-drop connections to FireForm's standard data schema.

This issue scopes out the backend plumbing necessary to make the "After" scenario a reality.

Note: I've actually been playing around with the pypdf implementation locally and have a working prototype for this backend detection engine. I'll open a PR momentarily for Phase 1 so you can see how it fits into the current architecture!

[marcvergees]

Very good idea. Nice to hear good proposals. If you haven't presented your candidature of GSOC 2026 yet, reach me out in mvergess@ucsc.edu.

[utkarshqz]

Hi @marcvergees @vharkins1 @jansans04 @juanalvv !

I believe the Master Incident Data Lake + AI Semantic Mapper I just implemented (PR #385 + PR #386 ) provides a foundation that makes this Field Mapping Wizard significantly more powerful than a static wizard alone.

Rather than asking users to manually map textbox_0_0 → "Officer Name" every time, the AI Semantic Mapper already performs this translation dynamically for any PDF — with zero user configuration. The wizard UI could serve as a visual override layer for edge cases where the AI needs a human correction, while the AI handles 95% of mappings automatically.

I'd love to take this further and discuss how we can integrate both approaches for the GSoC summer project!