Setup docs

CONTRIBUTING.md

@@ -39,25 +39,14 @@ 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.
+**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.
 
-### Prerequisites
+## 💬 Community
 
-- [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)
+Join our Discord server to ask questions, discuss issues, and coordinate work with other contributors: https://discord.gg/nBv5b6kF68
 
-### Desktop App Development
-
-The frontend is a vanilla HTML/CSS/JS app wrapped in Electron. To run it locally:
+## 🛠️ Local Development Setup
 
-```bash
-cd frontend
-npm install    # one-time setup
-npm start      # launches the Electron desktop window
-```
+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.
 
-The backend (API + Ollama) must be running separately via Docker — see `make fireform`.
+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.

docs/1. SETUP.md

@@ -0,0 +1,99 @@
+# 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
+- [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

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_<area>.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.