# Project pack: OpnForm @ 769496b

Facts about **OpnForm** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> OpnForm is an open-source form builder, a Typeform alternative. You drag in questions, add logic, branding and notifications, and share a link or embed the form on your site. Responses land in a dashboard and can go to email, Slack, Google Sheets or webhooks.

## Version and source
- Repository: https://github.com/OpnForm/OpnForm
- Pinned commit: `769496b684ff8da2892b1a8d457ff9208ae87932`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/OpnForm/OpnForm/archive/769496b684ff8da2892b1a8d457ff9208ae87932.zip
- Official docs: https://docs.opnform.com
- Live demo: https://opnform.com/forms/create/guest. Try the form builder as a guest on the official site.
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations. The api/app/Enterprise folder is under a separate licence.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/OpnForm/OpnForm bespoke-opnform
  cd bespoke-opnform
  git checkout --detach 769496b684ff8da2892b1a8d457ff9208ae87932
  # Prepare development requirements and local configuration first.
  cp api/.env.example api/.env
  cp client/.env.example client/.env
  docker compose up -d
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Follow the Docker deployment guide at https://docs.opnform.com/deployment/docker, which provides the compose file and env templates.
  ```

- Needs: Docker; PHP 8.3, Composer and Node 22 for local development
- Develop: `docker compose up -d`
- Stack: php, javascript, vue (Laravel, Nuxt, Vue, Tailwind). Difficulty for a non-developer with an AI: **moderate**. A Laravel API plus a Nuxt front end. Forms are built in the visual editor; new field types and integrations touch both sides.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`.

## Customisation points (settings → extend → code)
- **form-builder** [settings]: Questions, branching, branding and what happens after submit. → `In the form editor (fields, logic, design, thank-you page)`
- **integrations** [settings]: Email, Slack, Discord, Google Sheets and webhooks. → `Form settings → Integrations`
- **embed-and-theme** [extend]: Put the form inside your website and match your style. → `Embed code and custom CSS in form settings`
- **field-types** [code]: New field types and validation. → `client/components and api/app`
- **integrations-code** [code]: New destinations for submissions. → `api/app/Integrations`

## Must keep working
- Submission storage and validation. Never lose a response.
- Database migrations. Add new ones; never edit old ones.
- File upload scanning and size limits.

## Staying updatable
Use form settings, embeds and integrations first. Add field types and integrations as new files and keep Enterprise code out.

## Data, costs and safety
- Personal data: **yes**. Stored in: A Postgres database plus a storage folder or bucket. Form responses may hold personal data of other people. Follow privacy laws and limit access.
- Service: Email (SMTP) (optional, usually free to a few dollars): Notifications and submission receipts.
- Service: File storage (S3-compatible) (optional, free locally): Uploaded files in forms.
- Setting `APP_KEY` (**secret**: the person enters it themselves, never in chat): Laravel encryption key. Never paste it into an AI chat.
- Setting `JWT_SECRET` (**secret**: the person enters it themselves, never in chat): Secret used to sign logins.
- Setting `DB_PASSWORD` (**secret**: the person enters it themselves, never in chat): Database password.
- Forms collect other people's data. Add consent text where required and secure the dashboard.
- Keep APP_KEY and database passwords out of Git and chats.

---

# Customising OpnForm

OpnForm has two apps: a Laravel API and a Nuxt client. For most uses the form editor is all you need.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Form editor and public form pages | client/components/ and client/pages/ |
| API endpoints and models | api/app/Http/ and api/app/Models/ |
| Integrations | api/app/Integrations/ |
| Database migrations | api/database/migrations/ |
| Docker setup | docker/ and docker-compose.yml |
| Tests | api/tests/ and client tests |

## Use the gentlest change first

1. **Settings (no code):** fields, logic, design and integrations in the form editor.
2. **Extend:** embed code, custom CSS and webhooks.
3. **Code:** new field types and integrations.

## Recipes

- **New field type:** add a component in `client/components` for editing and for filling, register it in the field list, and validate it in the API.
- **New integration:** create a handler class under `api/app/Integrations` and register it in the integrations list.

## Running and checking your changes

- Start with Docker, create a form, submit it and see the response.
- `php artisan test` for the API.
- Test the embedded form on a plain HTML page.

## Pitfalls

- Keep `.env` files out of Git.
- Do not edit migrations that already shipped.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/opnform/769496b/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/opnform/769496b/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/opnform/769496b/r2/SKILL.md)