From 0529cfd90f7abc39b6a9006674091375af1b13cf Mon Sep 17 00:00:00 2001 From: chetanr25 Date: Thu, 11 Jun 2026 23:43:17 +0530 Subject: [PATCH 1/3] added setup docs, updated contributing.md --- CONTRIBUTING.md | 23 +++--------- docs/SETUP.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+), 18 deletions(-) create mode 100644 docs/SETUP.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 154daf8..7d297fb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,25 +39,12 @@ If you have a great idea for FireForm, we'd love to hear it! Please open an issu 4. Make sure your code lints. 5. Issue that pull request! -## πŸ› οΈ Local Development Setup - -FireForm uses Docker and Docker Compose for the backend to ensure a consistent environment. - -### Prerequisites +**Issues are not formally assigned.** You are free to pick any open issue, work on it, and raise a PR directly. If multiple PRs address the same issue, the first one that actually fixes it generally gets preference. To avoid duplicating someone else's work, coordinate with other contributors on our [Discord](https://discord.gg/nBv5b6kF68) before starting. -- [Docker](https://docs.docker.com/get-docker/) -- [Docker Compose](https://docs.docker.com/compose/install/) -- `make` (optional, but recommended) -- [Node.js](https://nodejs.org/) 20+ (only needed for the desktop app) +## πŸ’¬ Community -### Desktop App Development +Join our Discord server to ask questions, discuss issues, and coordinate work with other contributors: https://discord.gg/nBv5b6kF68 -The frontend is a vanilla HTML/CSS/JS app wrapped in Electron. To run it locally: - -```bash -cd frontend -npm install # one-time setup -npm start # launches the Electron desktop window -``` +## πŸ› οΈ Local Development Setup -The backend (API + Ollama) must be running separately via Docker β€” see `make fireform`. +See the [Setup Guide](docs/SETUP.md) for the full walkthrough: prerequisites, running the backend with Docker, testing endpoints via Swagger UI, day-to-day commands, and troubleshooting. diff --git a/docs/SETUP.md b/docs/SETUP.md new file mode 100644 index 0000000..216bc24 --- /dev/null +++ b/docs/SETUP.md @@ -0,0 +1,98 @@ +# Setup Guide + +This guide gets the FireForm backend running locally with Docker. It assumes you are comfortable with git and a terminal, but new to this project. + +## Prerequisites + +- [Docker](https://docs.docker.com/get-docker/) **24 or newer**, with the Docker daemon running +- Docker Compose v2 (bundled with Docker Desktop; verify with `docker compose version`) +- `make` +- ~3 GB of free disk space (Docker images + LLM model weights) + +## Setup + +### 1. Clone the repository + +```bash +git clone https://github.com/fireform-core/FireForm.git +cd FireForm +``` + +### 2. Run first-time setup + +```bash +make init +``` + +This will: + +1. Check that Docker meets the requirements above +2. Create `docker/.env.dev` from `docker/.env.example` (gitignored; defaults work out of the box) +3. Prompt you to pick an Ollama model (the default, `qwen2.5:1.5b`, is the smallest and fine for development) +4. Offer to build and start everything answer `y`, or run `make fireform` later + +### 3. Build and start (if you skipped it in step 2) + +```bash +make fireform +``` + +This builds the Docker images, starts the containers, waits for Ollama, and pulls the LLM model. The first run takes several minutes (image build + model download); later runs are fast. + +When it finishes you'll see: + +``` +FireForm is ready! + API: http://localhost:8000 + API Docs: http://localhost:8000/docs +``` + +### 4. Verify it works + +Open **http://localhost:8000/docs** in your browser. This is the interactive Swagger UI you can explore and test every API endpoint directly from there (expand an endpoint, click _Try it out_, then _Execute_). + +## Day-to-day commands + +| Command | What it does | +| ------------ | ------------------------------------------------------------------------ | +| `make up` | Start containers | +| `make down` | Stop containers (data is preserved) | +| `make logs` | Stream all container logs (`make logs-app` / `make logs-ollama` for one) | +| `make shell` | Open a shell inside the app container | +| `make test` | Run the test suite | +| `make help` | List all commands | + +The dev container mounts the source code, so code changes reload automatically β€” no rebuild needed. Rebuild (`make build`) only when dependencies in `requirements.txt` or the Dockerfile change. + +## Frontend (optional) + +The desktop/web frontend lives in a separate repository: + +```bash +git clone https://github.com/fireform-core/fireform-frontend.git +``` + +Follow the README in that repository to run it. The backend from this guide must be running for the frontend to work. + +## Troubleshooting + +**`make init` fails dependency checks** +Docker isn't running or is too old. Start Docker Desktop (or the Docker daemon) and confirm `docker version` reports 24+. + +**Port 8000 already in use** +Another process is bound to the port. Either stop it, or change `APP_PORT` in `docker/.env.dev` and run `make down && make up`. + +**Model pull is slow or times out** +The first `make fireform` downloads the LLM weights (~1 GB for the default model). On a slow connection just wait, or re-run `make pull-model` it resumes safely. + +**Containers start but the API doesn't respond** +Check `make logs-app` for the actual error. The entrypoint runs database migrations on startup, so the API takes a few seconds after the container starts. + +**Want a clean slate** +`make super-clean` stops everything and **deletes all volumes** database, uploads, and downloaded model weights. Only use it when you intend to wipe all local data. + +## Where to go next + +- **Join our [Discord](https://discord.gg/nBv5b6kF68)** β€” ask questions and coordinate with other contributors +- [CONTRIBUTING.md](../CONTRIBUTING.md) - how to contribute +- [docker/README.md](../docker/README.md) - Docker layout, env vars, and volumes in detail From c131ee14d479a806c8037d9c8ab5e20d0cb5d795 Mon Sep 17 00:00:00 2001 From: chetanr25 Date: Fri, 12 Jun 2026 03:13:11 +0530 Subject: [PATCH 2/3] added project structure --- CONTRIBUTING.md | 2 + docs/{SETUP.md => 1. SETUP.md} | 1 + docs/2. PROJECT_STRUCTURE.md | 87 ++++++++++++++++++++++++++++++++++ 3 files changed, 90 insertions(+) rename docs/{SETUP.md => 1. SETUP.md} (97%) create mode 100644 docs/2. PROJECT_STRUCTURE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7d297fb..6cf0be7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,3 +48,5 @@ Join our Discord server to ask questions, discuss issues, and coordinate work wi ## πŸ› οΈ Local Development Setup See the [Setup Guide](docs/SETUP.md) for the full walkthrough: prerequisites, running the backend with Docker, testing endpoints via Swagger UI, day-to-day commands, and troubleshooting. + +Before writing code, read the [Project Structure](docs/PROJECT_STRUCTURE.md) guide β€” it explains how the codebase is organized and where new code should go. diff --git a/docs/SETUP.md b/docs/1. SETUP.md similarity index 97% rename from docs/SETUP.md rename to docs/1. SETUP.md index 216bc24..5b4de34 100644 --- a/docs/SETUP.md +++ b/docs/1. SETUP.md @@ -95,4 +95,5 @@ Check `make logs-app` for the actual error. The entrypoint runs database migrati - **Join our [Discord](https://discord.gg/nBv5b6kF68)** β€” ask questions and coordinate with other contributors - [CONTRIBUTING.md](../CONTRIBUTING.md) - how to contribute +- [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) - how the codebase is organized and where new code goes - [docker/README.md](../docker/README.md) - Docker layout, env vars, and volumes in detail diff --git a/docs/2. PROJECT_STRUCTURE.md b/docs/2. PROJECT_STRUCTURE.md new file mode 100644 index 0000000..cee9c40 --- /dev/null +++ b/docs/2. PROJECT_STRUCTURE.md @@ -0,0 +1,87 @@ +# Project Structure + +This document explains how the FireForm repository is organized and, when you add new code, where it should go. + +## Top-level layout + +``` +FireForm/ +β”œβ”€β”€ app/ # Backend source code (FastAPI application) +β”œβ”€β”€ tests/ # Test suite (pytest) +β”œβ”€β”€ docker/ # Dockerfiles, compose files, env templates +β”œβ”€β”€ scripts/ # Shell scripts +β”œβ”€β”€ docs/ # Project documentation +β”œβ”€β”€ examples/ # Standalone demo scripts +β”œβ”€β”€ data/ # Local runtime data (gitignored contents) +β”œβ”€β”€ Makefile # Entry point for all dev commands (`make help`) +└── requirements.txt # Python dependencies +``` + +| You want to… | Go to | +| -------------------------------- | ------------------------------------------------------- | +| Change backend behavior | `app/` | +| Add or fix tests | `tests/` | +| Change container setup, env vars | `docker/` (see [docker/README.md](../docker/README.md)) | +| Change setup/bootstrap scripts | `scripts/` | +| Add documentation | `docs/` | +| Add dev commands | `Makefile` | + +## Inside `app/` + +The backend follows a layered structure: **routes β†’ services β†’ repositories β†’ database**. Requests enter through the API layer, business logic lives in services, and all database access goes through repositories. + +``` +app/ +β”œβ”€β”€ main.py # App factory: creates FastAPI app, wires middleware and routers +β”œβ”€β”€ api/ # HTTP layer - request/response handling only, no business logic +β”‚ β”œβ”€β”€ router.py # Aggregates all route modules into one router; main.py mounts this +β”‚ β”œβ”€β”€ deps.py # Shared FastAPI dependencies (e.g. DB session injection) +β”‚ β”œβ”€β”€ routes/ # One module per feature (forms.py, templates.py, …) +β”‚ └── schemas/ # Pydantic request/response models, one module per feature +β”œβ”€β”€ core/ # App-wide infrastructure +β”‚ β”œβ”€β”€ config.py # All settings and env var reading nothing else reads os.environ +β”‚ β”œβ”€β”€ lifespan.py # Startup/shutdown logic (DB init, etc.) +β”‚ β”œβ”€β”€ logging.py # Logging configuration +β”‚ └── errors/ # Custom exception classes (base.py) and handlers (handlers.py) +β”œβ”€β”€ services/ # Business logic β€” LLM extraction, PDF filling, orchestration +β”œβ”€β”€ db/ # Database engine/session (database.py) and repositories.py +β”œβ”€β”€ models/ # SQLAlchemy ORM models +└── utils/ # Small generic helpers with no business logic +``` + +### Where does my new code go? + +**Adding a new API endpoint:** + +1. `app/api/schemas/<...>.py` - Pydantic models for the request and response bodies +2. `app/api/routes/<...>.py` - the route handlers; keep them thin, delegate to a service +3. `app/api/router.py` - register the new router (one `include_router` line) +4. Business logic goes in `app/services/`, not in the route handler + +**Adding business logic:** `app/services/`. A service should not know about HTTP (no FastAPI imports) it takes plain data in and returns plain data, so it can be tested and reused independently. + +**Adding a database table:** define the ORM model in `app/models/models.py`, and add its query/persistence functions to `app/db/repositories.py`. Services call repositories; routes never touch the database directly. + +**Adding a setting or env var:** declare it in `app/core/config.py` and document it in `docker/.env.example`. Code elsewhere imports from `config`, never reads `os.environ` itself. + +**Adding a custom error:** subclass in `app/core/errors/base.py`; map it to an HTTP response in `app/core/errors/handlers.py`. + +## Tests + +Tests live in `tests/`, run with `make test` (pytest inside the app container). `conftest.py` holds shared fixtures. Name files `test_.py` and mirror what you're testing: API endpoint tests alongside `test_api.py`, model/DB tests alongside `test_model.py`. +Note: Tests will be undergoing many changes hence the docs can be outdated, Please raise issue if tests or docs are outdated. + +## Docker & scripts + +- `docker/dev/` - development image (hot reload, source mounted) and its compose file. This is what `make up` runs. +- `docker/prod/` - production image (multi-stage build, gunicorn, no source mount). +- `docker/.env.example` - template for env vars; copied to `.env.dev` by `make init`. +- `scripts/` - shell scripts invoked by `make init` (dependency checks, env file creation, model selection) and by container startup. Not meant to be run directly. + +Full details: [docker/README.md](../docker/README.md). + +## Everything else + +- `examples/` - runnable demo scripts showing the pipeline end to end; not imported by the app. +- `data/` - runtime working data on your machine; contents are not part of the codebase. +- `src/`, `temp/` - scratch/legacy directories slated for cleanup; don't add new code here. From 6ea00393f865393b2a3aee3aa5c93942a17e5fc0 Mon Sep 17 00:00:00 2001 From: chetanr25 Date: Fri, 12 Jun 2026 19:17:47 +0530 Subject: [PATCH 3/3] Updated renamed file name --- CONTRIBUTING.md | 4 ++-- docs/1. SETUP.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6cf0be7..d30e9b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,6 +47,6 @@ Join our Discord server to ask questions, discuss issues, and coordinate work wi ## πŸ› οΈ Local Development Setup -See the [Setup Guide](docs/SETUP.md) for the full walkthrough: prerequisites, running the backend with Docker, testing endpoints via Swagger UI, day-to-day commands, and troubleshooting. +See the [Setup Guide](docs/1.%20SETUP.md) for the full walkthrough: prerequisites, running the backend with Docker, testing endpoints via Swagger UI, day-to-day commands, and troubleshooting. -Before writing code, read the [Project Structure](docs/PROJECT_STRUCTURE.md) guide β€” it explains how the codebase is organized and where new code should go. +Before writing code, read the [Project Structure](docs/2.%20PROJECT_STRUCTURE.md) guide β€” it explains how the codebase is organized and where new code should go. diff --git a/docs/1. SETUP.md b/docs/1. SETUP.md index 5b4de34..30d2aee 100644 --- a/docs/1. SETUP.md +++ b/docs/1. SETUP.md @@ -95,5 +95,5 @@ Check `make logs-app` for the actual error. The entrypoint runs database migrati - **Join our [Discord](https://discord.gg/nBv5b6kF68)** β€” ask questions and coordinate with other contributors - [CONTRIBUTING.md](../CONTRIBUTING.md) - how to contribute -- [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) - how the codebase is organized and where new code goes +- [PROJECT_STRUCTURE.md](2.%20PROJECT_STRUCTURE.md) - how the codebase is organized and where new code goes - [docker/README.md](../docker/README.md) - Docker layout, env vars, and volumes in detail