Split FireForm into two repos and restructure both. Make the repository maintainable

[chetanr25]

A few things I noticed while reading the code. Writing them here so we can talk about it before any PR goes up.

What is wrong right now

api/ and src/ both look like the backend at first. They are not duplicates. api/ is the FastAPI service. src/ is the LLM + PDF engine the routes call into. The names do not say that, and a new contributor will guess wrong. The same repo also holds the Electron frontend, which has nothing to do with the Python side. release.yml is already using a working-directory: frontend workaround because of this.

frontend/app.js is one file, over a thousand lines long. It has the API client, the localStorage state, the tab UI and the Electron glue all in one place. No modules, no lint, no build step.

What I want to do

Split the project into two repos and restructure both.

• fireform-server: FastAPI app, DB, LLM/PDF pipeline.
• fireform-desktop: Electron app, talks to the server over HTTP.

They only talk over one URL today so the split is cheap.

Server repo layout

Top level:

fireform-server/
  backend/              # application code
  docker/               # per-environment build + compose files
  conf/                 # runtime configs (nginx, ollama, logging)
  docs/                 # short, focused markdown
  scripts/              # one-off ops/dev helpers
  tests/
  docker-compose.yml    # thin top-level, uses docker/dev by default
  Makefile
  pyproject.toml
  README.md
  CONTRIBUTING.md  SECURITY.md  CODE_OF_CONDUCT.md  LICENSE

backend/ is one Python package, layered:

backend/
  api/
    routes/             # forms.py, templates.py
    schemas/            # pydantic request/response models
    deps.py
  services/             # llm.py, file_manipulator.py, filler.py  (was src/)
  models/               # sqlmodel/orm models
  db/                   # database.py, repositories.py, init_db.py
  core/                 # config, logging, error handlers
  utils/                # small helpers with no dependencies
  main.py               # FastAPI app factory + lifespan

docker/ is one folder per environment:

docker/
  dev/
    Dockerfile          # mounts source, --reload
    compose.yml
  prod/
    Dockerfile          # multi-stage, no source mount, gunicorn
    compose.yml

  entrypoint.sh
  README.md             # which file to use when

<some more docker compose to test out few features, or for admin etc>

conf/ is external service config that we ship with the repo so deploys are reproducible. Only add what we actually use.

conf/
  nginx/(prod)
  wellknown/

docs/ is short, single-purpose files. Clear name prefixes: how-to-*, explain-*, ref-*, tutorial-*. Each file does one thing and fits on one screen. Use diataxis Style

docs/
  index.md
  dev/
    how-to-quick-start.md
    how-to-develop-using-docker.md
    how-to-write-and-run-tests.md
    explain-architecture.md       # backend/ layout, request flow
    explain-llm-pipeline.md       # how filler + llm + file_manipulator interact
    ref-makefile.md
  api/
    index.md                       # link to /docs (FastAPI auto)
    ref-endpoints.md
    explain-template-vs-form.md

scripts/ is ops and dev helpers that are not part of the runtime. Right now the Makefile reaches into the container for these. Moving them out means they run outside Docker too.

scripts/
  pull-model.sh         # guarded ollama pull (skip if mistral exists)
  reset-db.sh           # delete fireform.db and re-init
  seed-templates.py     # load example_template.json into a fresh DB
  smoke.sh              # curl the API endpoints, fail on non-2xx

Makefile targets become thin wrappers: make pull-model runs ./scripts/pull-model.sh.

Server migration steps, one PR each:

1. Move api/ and src/ into backend/, fix imports.
2. Split the Dockerfile and docker-compose.yml into docker/{dev,prod,...}/.
3. Rewrite docs/ to match the new layout, one short file at a time.

---

Desktop repo layout

React + Vite + Electron, with TypeScript. Replace the single app.js file.

fireform-desktop/
  src/
    renderer/                # React app
      components/            # presentational
      features/              # per-feature: template-builder, fill-form, templates-list
        template-builder/
          TemplateBuilder.tsx
          fields-builder.tsx
          hooks.ts
      lib/
        api.ts               # fetch wrappers, one function per endpoint
        storage.ts           # localStorage keys and helpers
      store/                 # zustand or context, templates, field rows
      App.tsx
      main.tsx
      styles/
    main/                    # Electron main process
      index.ts
      preload.ts
  index.html
  vite.config.ts
  electron-builder.yml
  package.json
  tsconfig.json

Why React over vanilla modules or Svelte/Vue:

• Biggest contributor pool. GSoC applicants and OSS reviewers already know it.
• Component model maps cleanly onto the current tab/panel structure in app.js.
• Vite + electron-builder is a standard combo with good docs.

Desktop migration:

1. Restructure the backend in place. Keep frontend/ where it is for now.
2. Cut fireform-server and fireform-desktop from the restructured tree.
3. In the desktop repo, scaffold React + Vite + Electron next to the existing app.js. Port one feature at a time (templates list, fill form, template builder). Delete app.js once the last feature is done.

Step 3 is the slowest. Doing it inside the new repo (not on main here) keeps it off the critical path for everyone else.

Few questions

• Two repos vs one repo. Is there a reason to keep one that I am missing.
• Layered vs domain-style for the backend. I went with layered because the feature count is small right now, but domain-style from the start might be better if we plan to grow fast.
• React vs just splitting the existing vanilla JS into modules. React feels right but it is the bigger lift.
• Order. Restructure on main first and then cut the new repos, or cut first and restructure inside them.

Happy to start with the backend restructure, if this sounds reasonable.

[chetanr25]

@marcvergees @vharkins1
I can proceed to create an issue on this, if this sounds good.

[marcvergees]

How are we feeling about calling both repos fireform-frontend and fireform-backend?

The rest looks good to me.

@vharkins1, opinions?

[chetanr25]

This would absolutely work!