edit-resource

Edit resource

End-to-end workflow for editing or creating a resource in the FIS project.

Scoping the change

Before starting, identify which layers of the stack are actually affected. Not every change requires touching all layers. For example, a purely frontend change (e.g., displaying an already-accessible field on a new page) does not require documentation, database, backend, or test changes. Conversely, adding a new field to a resource will typically touch every layer.

When the change only affects the frontend, check that the data the UI will fetch is already accessible to the relevant roles by verifying:

• The permissions CSV grants R on the fields for the roles that will see the data.
• The API views / RLS policies have branches for those roles.

If both are satisfied, proceed directly to the frontend section. If not, discuss the required backend/permission changes with the user before proceeding.

Project structure

The project is organised with the following components, to edit in the same order:

Documentation

This is a research project, so this is the most important part and must be valid at all times. The docs directory contains Markdown files for overall architecture, design decisions, and resource documentation. Resource documentation is in docs/resources, with one file per resource. The FIS project relies heavily on code generation from source-of-truth inputs. Each resource file includes auto-generated field tables and permission tables, along with hand-written sections on business rules and notifications. Any change to a resource should start with a change in the documentation when it concerns its fields or business rules for example. As it is generated, the first file to change is openapi/resources.yml and local/input/permissions.csv, which are the source of truth for the field definitions and permissions, respectively. There is a section in this skill for each of these two files, and a section for the resource documentation file. Then run just openapi and just permissions to update the generated documentation tables.

Database

The PostgreSQL database in db is organised in several schemas. A flex schema is used to define the internal tables and data layout of our resources. It also contains RLS policies and internal views that can be practical to avoid very verbose joins and reduce query complexity. An api schema is laid on top and contains views and functions that will later be exposed in our API. This allows changing the internal data layout without impacting the API, as long as we maintain the same API views. The other schemas are very specific to a certain aspect of the system and usually they do not need to be checked when editing a resource.

All stateful changes to the database must be made through Liquibase migrations, which are defined in changelog files. Most of the resources that have been modified at least once have a dedicated changelog file next to their definition file. We also maintain the definitions for documentation purposes, but also to be able to deploy a new instance of the system without having to replay all the migrations.

A section of this skill is dedicated to editing the flex tables and RLS policies. The api view will usually be generated, except in very specific cases. Another section covers the migrations.

Backend

The backend is a Go application in backend/, with a PostgREST proxy for standard CRUD operations and custom handlers for specific endpoints. Usually, modifications do not require changes to the endpoints, but resource creation requires to add new endpoints which usually look like this (when all CRUD operations are enabled):

mux.Handle("GET /<resource>", dataListPostgRESTHandler)     // List
mux.Handle("POST /<resource>", dataPostgRESTHandler)        // Create
mux.Handle("GET /<resource>/{id}", dataPostgRESTHandler)    // Read
mux.Handle("PATCH /<resource>/{id}", dataPostgRESTHandler)  // Update
mux.Handle("DELETE /<resource>/{id}", dataPostgRESTHandler) // Delete

mux.Handle("GET /<resource>_history", dataListPostgRESTHandler)  // History list
mux.Handle("GET /<resource>_history/{id}", dataPostgRESTHandler) // History read

Data models are generated by sqlc from the database schema. The just sqlc command should be run after any change to the database schemas to update the models.

Touching a resource through the API will trigger events and notifications to the users. Custom code is implemented in backend/event to identify notification recipients based on the resource and operation performed (a new case may be needed in the dispatcher, with a new query in the models.sql file). If the user mentions notifications, this should be part of the workflow. Otherwise, this can be done as a separate task.

A Kotlin backend is being developed in parallel, but it has not yet taken over, so it should not be modified as part of this workflow.

Tests

Tests to be edited are the Python API tests in test/api_client_tests. They use the auto-generated Python API client from test/flex, auto-generated from the OpenAPI specification, which allows for easy and up-to-date API tests.

API tests should be added or modified for any change that impacts the API contract, such as field changes, validation rules, or permissions.

just test --api should always pass after editing or creating a resource.

There is usually one file per resource to test. A setup fixture is used to create any necessary data that might be needed in all the tests in the file, such as creating dependent resources, etc.

Tests should cover the happy path for all allowed operations (e.g., create, read, update, delete), but also some error cases based on the validation rules and RLS policies defined on the resource (for instance, a resource depending on some qualification or status to be at the right place in order to be created or edited, or the user having a specific role).

There should be some test data for each resource in the database (db/test_data/test_data.sql). It should be modified when needed, so that the tests have the necessary data to run, if it is data that cannot be created in a fixture.

Frontend

The frontend is a React application in frontend, using React Admin as an initial framework but under step by step refactoring towards the EDS design system and custom components.

Each resource has its own folder in frontend/src/, with the React Admin pages (List, Show, Input, History). The React Admin resource registration is done in frontend/src/resources/index.tsx, but each resource is responsible for its own registration and subresources in a dedicated file under frontend/src/resources/. If the resource is a relation, it probably has a parent and a child resource, then the registration should be in the parent's file.

Changes to the UI may require changes to the API, or even changes to the RLS policies, so you should always consider such implications and discuss them with the user.

After any frontend change, run the TypeScript compiler to verify there are no type errors:

npx tsc --noEmit # in frontend/

Check the frontend part of the details section if frontend changes are needed in your task.

Details about some aspects of the workflow

Resources YAML

This is one of the main source of truth files. It defines all the fields for each resource at the api schema level, along with their description, type, some constraints, name in other languages for internationalisation, and extra metadata used for generation. Each resource is an entry in the top-level resources list.

Internationalisation is given as a {language->translation} map in the x-intl key at both resource and property level. Enum values also have their own translations for each value.

Resource-level attributes

CRUD operations to generate are defined as a list in the operations key, operations for the history resource being defined in the history key.

Setting audit to true will enable the audit trail, which means that the system will automatically record the author and timestamp of each change to the resource, and make them available in the API.

Setting generate_views to false will skip the generation of the API views, which is useful for resources with hand-written API views that do not follow the standard patterns. history_rls works the same way by disabling generation of RLS policies for the history resource, which is also useful in cases with more customisation.

Setting comments to true will automatically add a comment sub-resource, which is a common pattern in the system.

Property-level attributes

Attributes at this level are usually mapped to OpenAPI schema properties, so the usual JSON Schema validation keywords apply: readOnly, nullable, format, type, enum, minimum, maximum, maxLength, etc.

readOnly means the field won't be included in the Create and Update request schemas, but it will be in the response schema. nullable means the field can be null in the database and in the API. The combination of the right values for these attributes determines whether a field is required or not.

Always give an example value for better documentation and easier testing. When an optional field has a default value, do not forget to add it in the schema.

For more complex rules, we use x-* fields that will not be included in the OpenAPI specification, but will be used when generating code. x-filter is used to mark fields that should be filterable in the list endpoints. x-foreign-key is used to mark foreign key references, and it should include the referenced resource and field. x-no-update is used to mark fields that can be set on create but not updated afterwards, which is a common pattern for fields like reference IDs that define the record but should not be changed afterwards. x-details includes extra documentation that is included in the generated Markdown field ta

---

Content truncated.