docs(api): Add docs folder at root, add OpenAPI spec docs (#884)

- Add Documentation section in REAMDE
- Add docs folder at root, add OpenAPI spec docs

---------

Signed-off-by: Mathieu Anderson <[email protected]>

Author: Mathieu Anderson

CONTRIBUTING.md

@@ -105,6 +105,8 @@ __1. Every PR has to be releasable__
 
 - Every PR that is merged on `main` should be treated like we release it into production right away.
 - The `main` branch should always be in a state where it can be deployed and used right away.
+- If API changes were made, ensure the `openapi.yaml` spec was generated and added to the commit, and that the frontend types have been generated with `pnpm extract-api-types`. [Read about why here](./docs/openapi.md).
+- All GitHub actions checks must be green.
 
 __2. A clear goal with a small scope__
 

README.md

@@ -99,7 +99,12 @@ For the versions available, see the [tags on this repository](https://github.com
 
 - Help Wizard to setup Klaw
 
-- Documentation : https://klaw-project.io/docs
+## Documentation
+
+- User documentation : https://klaw-project.io/docs
+- Technical documentation for contributors:
+  - general documentation: [`./docs`](./docs)
+  - specific documentation for the React app `coral`: [`./coral/docs`](./coral/docs)
 
 ## Install
 

docs/README.md

@@ -0,0 +1,3 @@
+## Table of content
+
+- [API source of truth: OpenAPI spec](openapi.md)

docs/generation_schema.png

@@ -0,0 +1,13 @@
+## What is the Klaw API source of truth?
+
+The OpenAPI spec `./openapi.yaml` at the root of the project is our source of truth. It is _auto-generated_ from the current state of the API code when `mvn verify` is ran from `core`, and is therefore always up to date with the current state of the API.
+
+We use this OpenAPI spec as a source for the generation of the TypeScript types the frontend relies on to accurately type our business logic (mainly in [the `.coral/domain` folder](../coral/docs/directory-structure.md#first-level-domain-folder)). The script to generate those types is `extract-api-types` in `coral/package.json`, and the output can be seen in `coral/types/api.d.ts`.
+
+Therefore, every time the API changes, the OpenAPI spec will change, and the generated types for the frontend will keep in sync with the evolution of the API.
+
+## Generating the OpenAPI spec and TypeScript types
+
+This is a high level diagram of the process described above.
+
+![Diagram illustrating the flow described in the previous paragraph](./generation_schema.png)