kereru-forms/docs/AGENTS.md

Design

Note AI AGENT NOT TO UPDATE THIS FILE

This is the design for a simple forms site to be used to capture a number of survey type questions fom a person. The forms will be like Adove PDF forms and allow for configuration of questions to ask and an answer. The questions can be multiline text and do not contain formatting commands within the question.

The answer can be of types:

1. True or false
2. Numeric answer
3. Drop down options
4. Free form text
5. Date field

Project name is Kererū forms and its internal identifier is kereru.forms.

Technology stack

The design is based around a modern web UI using React + Vite + Tailwind CSS as the frontend and a Golang backend.

The database is any standard SQL DB and the initial verion is using SQLite. A SQL provider will allow future flexibility for other database SQL variants such as:

• Postgres
• MariaDB

Backend

The backend executable server name is to be kereru-forms.

The backend is to expose APIs that are defined in an OpenAPI file which is used to generate the golang code. A health service is to be included.

Include telemetry, logging and observability.

Frontend

Allow for themeing the UI for light, dark and system.

Past data captured is not presented again to the user inputing the data

A management section exists for viewing past data forms completions, and managing forms. Forms can be inactivated and can have versions.

A form can contain an introduction section explaining purpose, background and further contact or support details.

There is the ability by the user supplying the form to request a PDF version that is generated from the form definition. The PDF form can be generated by the person submitting the form so that the PDF form can be completed offline and even printed. The PDF form is to have an area for including the submitters details. Alternatively the PDF form can be a prebuilt Adbove PDF document linked to the survey definition.

The form can be configured to request a unique user code for filling in the form and once used the code cannot be used again.

The questions are to be presented on one line with question at left and answer options on right, except for free form text which is input below the question. Questions are to be numbered.

Questions can be grouped together with leading text as a section. A section will have an identifier such as letter or number. Question within a section will have a new number that is prefixed by the section identifier.

A form can have a digital signature defined at the end which can capture a drawn sigature, a picture file with signature, name of person and optional title.

Include an option at the start of the survey to upload a PDF form that has been completed offline by the user. This upload will still need to capture the identity of the person uploading the PDF document.

Include UI for displaying the OpenAPI definition as a web page under path /docs. The UI for OpenAPI definition is not to be linked to an external service providing the rendering and must be able to be run locally for offline dvelopment.

For management section when viewing past submissions and answers, show the question along with the answwer.

Database Schema

The schema is to allow for multiple forms and capture the user input using an user identifier such as email, username, international phone number, foreign key or GUID. The identifier is captured at the start.

Forms can be versioned and include a logo and company name plus contact details that is linked to the form. Existing forms can be edited which will generate a new version number for the form definition.

A form can be configured to require an external reference identifier such as invoice number, account number, policy number. This identifier will be used to verfiy and link the form to an external consumer of the data.

Each form capture is to gather details about the time, place, IP, browser as tracking detais.

Authentication

Include OAuth authentication for the management services including viewing past submissions.

The OAuth is to be configurable to use external service such as Okta, KeyCloak. If no serviec provided then a simple password is to be used so that the application can be tested locally.

Accessing the form submission can optionally be configured to require authentication against the OAuth identity provider. Access for submission does not require a role claim just authentication.

Access to manage forms for CRUD purposes requires an admin role claim in the JWT. Access to view forms that have been submitted requires a view role claim in the JWT. Uusers with admin role claim only cannot view submissions.

Configuration

The solution is to include configuration. Configuration is supplied via a JSON or YAML file.

The configuration file is loaded first and can be specified as argument --conf to the backend program. Once the configuration file is loaded the values are overridden by envionment variables that can also be supplied as a .env file in the path of the executable.

The following arguments can be supplied to executable as arguments, overriding the configuration and environment inputs.

• configuration file location
• logging level
• listening address either IPv4 and/or IPv6. Both can be supplied.
• listening port

Testing

Create test cases for code in both frontend and backend.

Containerisation

The solution is to be containerised and has

• Dockerfile
• Docker compose file

Instructions for Docker, Podman and Kubernetes setup are to be provided.

Documentation

The design documentation and design decisions are to be captured in document ARCHITECTURE.md in folder docs.

Create a sample environment and configuration file.

Development

Create developer instructions for local execution and producton deployment.

The frontend is to be executable separately from the backend using npm run dev for local development

The backend is to be executed in local development with standard Golang command to run.