159 lines
5.7 KiB
Markdown
159 lines
5.7 KiB
Markdown
# 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.
|
|
|
|
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.
|