feat(docs): Improve documentation and enforce markdown linting

.githooks/README.md

@@ -8,6 +8,6 @@ In this directory is a collection of helpful git hooks to ease your development
 
 Setup is easy, just configure git to use this as your hooks path instead of the default:
 
-```sh
+```bash
 git config core.hooksPath .githooks
 ```

.github/actions/README.md

@@ -1,35 +1,35 @@
 # GitHub Actions supporting scripts
 
 In this section of the repo you will find GitHub specific integrations. We really hope there will not be many of them.
 
 ## Testing
 
 ```
 yarn
 yarn test
 ```
 
 ## Building/Packaging
 
 ```
 yarn
 yarn build
 ```
 
 ## Running locally
 
 Running locally can be done by using [local-runner.ts](./local-runner.ts). You will need a GitHub PAT with `repo`
 permissions.
 
-```shell
+```bash
 node -r esbuild-runner/register local-runner.ts
 ```
 
 # Change detection script
 
 ## What is a Github PR?
 
 Basically a PR is a sort of "dry-run" of what would happen if you merged your branch to the base branch at a given point
 in time. Here is what roughly happens when you open a PR:
 
 ```mermaid
@@ -49,14 +49,14 @@
     classDef merge fill:orange;
 ```
 
 If the two branches cannot be merged together, someone must step in to fix that up. If the two branches can be merged
 together, then that's great and at least it means the head branch can be auto-merged into the base one. If there are
 GitHub Actions workflows configured for this event (pull request, that is) and the `PR1` merge was successful, then
 those are executed.
 
 ## The challenge
 
 In the context of monorepo, such as we are, re-building and re-integrating the code at every step fully is very
 expensive (and only getting more so over time) in all kinds of ways and is therefore impractical. We are employing a
 process where we re-integrate and re-build only the components that have changed from the last successful build.
 

.github/workflows/pullrequest.yml

@@ -333,6 +333,27 @@ jobs:
           ./scripts/ci/20_check-formatting.sh "write"
           ./infra/scripts/ci/git-check-dirty.sh "/" "nx format:write" "dirtybot"
 
+  docs:
+    needs:
+      - prepare
+    runs-on: ec2-runners
+    container:
+      image: public.ecr.aws/m3u4c4h9/island-is/actions-runner-public:latest
+    if: needs.prepare.outputs.LINT_CHUNKS
+    # env:
+    #   AFFECTED_PROJECTS: ${{ matrix.projects }}
+    #   NODE_OPTIONS: --max-old-space-size=4096
+    #   MAX_JOBS: 3
+    # strategy:
+    #   fail-fast: false
+    #   matrix: ${{ fromJson(needs.prepare.outputs.LINT_CHUNKS) }}
+    steps:
+      - name: Markdown linting
+        uses: DavidAnson/markdownlint-cli2-action@v17
+        with:
+          globs: |
+            **/*.md
+
   linting:
     needs:
       - prepare
@@ -362,7 +383,7 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           keys: ${{ needs.prepare.outputs.CACHE_KEYS }}
           enable-cache: 'node_modules,generated-files'
-      - name: Linting
+      - name: Nx linting
         run: ./scripts/ci/run-in-parallel-native.sh lint
 
   build:

.markdownlint.yaml

@@ -0,0 +1,7 @@
+# Default state for all rules
+default: true
+
+# MD013/line-length - Line length
+MD013:
+  line_length: 1000
+  tables: false

apps/air-discount-scheme/README.md

@@ -2,13 +2,9 @@
 
 ## About
 
-Generates discount codes that can be used for booking domestic flights online.
+Generates discount codes for booking eligible domestic flights. Eligibility criteria:
 
-There are certain precondition to be eligible for a discount. They are:
-
-- The person's legal domicile needs to be in a predefined set of towns outside
-  the capital (We fetch postal codes from Þjóðskrá to validate if user is
-  eligible).
+- Legal domicile in specific towns outside the capital. Postal codes from Þjóðskrá are used for validation.
 
 ## URLs
 
@@ -18,13 +14,7 @@ There are certain precondition to be eligible for a discount. They are:
 
 ## API
 
-The API is used by airlines to verify the discount code validity and get basic
-booking info about the user.
-
-The airlines that have access to this api are `Icelandair`, `Ernir` and
-`Norlandair`. Historically some flights were booked for `Norlandair` through
-`Icelandair`, those flights are marked with the `Icelandair` airline but have a
-cooperation field with `Norlandair`.
+The API allows airlines to verify discount code validity and access basic user booking info. Authorized airlines: `Icelandair`, `Ernir`, and `Norlandair`. Flights historically booked through `Icelandair` for `Norlandair` are marked with `Icelandair` but have a cooperation field with `Norlandair`.
 
 [Swagger API](https://loftbru.dev01.devland.is/api/swagger)
 
@@ -34,8 +24,7 @@ yarn start air-discount-scheme-api
 
 ## Backend
 
-The admin frontend has a view over the bookings that have been registered in
-the system. This is mainly for Vegagerðin.
+The admin interface provides an overview of registered bookings, primarily for Vegagerðin.
 
 [Admin](https://loftbru.dev01.devland.is/admin)
 
@@ -45,8 +34,7 @@ yarn start air-discount-scheme-backend
 
 ## Web
 
-The user frontend has information about the initiative, legal terms and a way
-for users to get their discount codes.
+The user interface includes initiative details, legal terms, and a tool for obtaining discount codes.
 
 [Dev](https://loftbru.dev01.devland.is)
 
@@ -56,31 +44,28 @@ yarn start air-discount-scheme-web
 
 ## Integrations
 
-- [Þjóðskrá](https://skra.is): To be able to verify the persons legal domicile,
-  give the airlines basic information about the person and fetch a persons
-  relations to show the discount codes for related children.
+- [Þjóðskrá](https://skra.is): Used to verify legal domicile, provide airlines with basic personal info, and retrieve discount codes for related children.
 
 ## Development
 
-To get started developing this project, go ahead and:
+To start developing:
 
-1. Fetch the environment secrets:
+1. Fetch environment secrets:
 
 ```bash
 yarn get-secrets air-discount-scheme-api
 yarn get-secrets air-discount-scheme-backend
 yarn get-secrets air-discount-scheme-web
 ```
 
-2. Start the resources with docker compose and migrate/seed the database:
+2. Start resources with Docker Compose and migrate/seed the database:
 
 ```bash
 docker compose -f apps/air-discount-scheme/backend/docker-compose.yml up
 ```
 
 ```bash
 yarn nx run air-discount-scheme-backend:migrate
-
 yarn nx run air-discount-scheme-backend:seed
 ```
 
@@ -90,55 +75,45 @@ yarn nx run air-discount-scheme-backend:seed
 yarn start air-discount-scheme-web
 ```
 
-4. Start the graphql api:
+4. Start the GraphQL API:
 
 ```bash
 yarn start air-discount-scheme-api
 ```
 
-5. Start the backend api:
+5. Start the backend API:
 
 ```bash
 yarn start air-discount-scheme-backend
 ```
 
-6. Check Contentful and AWS
+6. Verify Contentful and AWS:
 
-Login here <https://island-is.awsapps.com/start#/> (Contact devops if you need access)
-Copy env variables as instructed [here](https://docs.devland.is/technical-overview/devops/dockerizing#troubleshooting) (image arrows 1,2,3)
-Paste env variables into terminal
-Run `./scripts/run-es-proxy.sh` from island.is root
-You have success if you see `Forwarding from 0.0.0.0:9200 -> 9200` in terminal
+Log in at <https://island-is.awsapps.com/start#/> (Contact devops for access). Copy environment variables as described in [the documentation](https://docs.devland.is/technical-overview/devops/dockerizing#troubleshooting), then paste into terminal. Execute `./scripts/run-es-proxy.sh` from the island.is root directory. Success is indicated by `Forwarding from 0.0.0.0:9200 -> 9200` in terminal output.
 
-Navigate to [localhost:4200](http://localhost:4200) for the website or
-[localhost:4248/api/swagger/](http://localhost:4248/api/swagger/) for the
-airline api.
+Visit [localhost:4200](http://localhost:4200) for the website or [localhost:4248/api/swagger/](http://localhost:4248/api/swagger/) for the airline API.
 
 ### Admin
 
-To access the Admin UI, you'll need to add your Icelandic National ID to the
-comma separated environment variable `DEVELOPERS` (.env.secret) and restart the
-`api`.
+To access the Admin UI, add your Icelandic National ID to the `DEVELOPERS` environment variable in `.env.secret` and restart the API.
 
 ```bash
 export DEVELOPERS=1234567890
 ```
 
 ## Shortcuts
 
-Because of the short timeline this assignment had, there were few shortcuts
-taken that can be improved upon:
+Due to time constraints, certain shortcuts were necessary:
 
-- The authentication is pretty primitive, the IDP is still in development at
-  the time of this writing so we needed to use static api keys.
-- The deployment pipeline is outside of the islandis main pipeline.
-- The graphql api is separate of the main graphql api of islandis.
+- Authentication is basic; using static API keys as IDP was under development.
+- The deployment pipeline is separate from the main island.is pipeline.
+- The GraphQL API is independent of island.is's main GraphQL API.
 
-## Project owner
+## Project Owner
 
 - [Vegagerðin](http://www.vegagerdin.is)
 
-## Code owners and maintainers
+## Code Owners and Maintainers
 
 - [Brian - @barabrian](https://github.com/barabrian)
 - [Davíð Guðni - @dabbeg](https://github.com/dabbeg)

apps/api/README.md

@@ -2,7 +2,7 @@
 
 ## Quickstart
 
-Ensure docker is running, then run the following when running for the first time:
+Ensure Docker is running. For initial setup, execute:
 
 ```bash
 yarn dev-init api
@@ -14,57 +14,67 @@ To start the app:
 yarn dev api
 ```
 
-These commands are just shorthands for the setup described below.
-
 ## About
 
-This project forms the basis of a unified API for products belonging to island.is.
-
-It's built as a thin GraphQL layer on top of data and services provided by government organisations and island.is microservices, where each unit is wrapped in a domain.
-
-[![](https://mermaid.ink/img/eyJjb2RlIjoiZ3JhcGggVERcblx0c3ViZ3JhcGggSXNsYW5kLmlzXG5cdFx0c3ViZ3JhcGggQVBJXG5cdFx0XHRhcHBbXCJHcmFwaFFMIHNlcnZlcjxicj48YnI-L2FwcHMvYXBpPGJyPkF1dGhlbnRpY2F0aW9uPGJyPk1ldHJpY3NcIl1cblx0XHRcdGRvbWFpbltcIlJTSyBkb21haW48YnI-PGJyPi9saWJzL2FwaS9kb21haW5zL3Jzazxicj5HcmFwaFFMIFNjaGVtYTxicj5HcmFwaFFMIFJlc29sdmVyczxicj5TZXJ2aWNlc1wiXVxuXHRcdFx0ZG9tYWluMltcIkFwcGxpY2F0aW9ucyBkb21haW48YnI-PGJyPi9saWJzL2FwaS9kb21haW5zL2FwcGxpY2F0aW9uczxicj5HcmFwaFFMIFNjaGVtYTxicj5HcmFwaFFMIFJlc29sdmVyczxicj5TZXJ2aWNlc1wiXVxuXG5cdFx0XHRhcHAtLT58Q29tYmluZXMgR3JhcGhRTHxkb21haW4gJiBkb21haW4yXG5cdFx0XHRkb21haW4yIC0tPiB8Q2FsbHMgc2VydmljZXN8ZG9tYWluXG5cdFx0ZW5kXG5cdFx0eC1yb2FkW1wiWC1Sb2FkIFNlY3VyaXR5IFNlcnZlclwiXVxuXHRcdG1pY3Jvc2VydmljZVtcIkFwcGxpY2F0aW9ucyBNaWNyb3NlcnZpY2U8YnI-PGJyPi9hcHBzL3NlcnZpY2VzL2FwcGxpY2F0aW9uc1wiXVxuXHRcdGRhdGFiYXNlW1wiUG9zdGdyZVNRTCBEYXRhYmFzZVwiXVxuXHRcdGRvbWFpbjIgLS0-IG1pY3Jvc2VydmljZSAtLT4gZGF0YWJhc2Vcblx0ZW5kXG5cdHN1YmdyYXBoIFJTS1xuXHRcdHgtcm9hZDJbXCJYLVJvYWQgU2VjdXJpdHkgU2VydmVyXCJdXG5cdFx0cnNrLXNlcnZpY2VbXCJSU0sgV2Vic2VydmljZVwiXVxuXHRlbmRcblxuXHRkb21haW4gLS0-IHgtcm9hZFxuXHR4LXJvYWQgLS0-IHgtcm9hZDJcblx0eC1yb2FkMiAtLT4gcnNrLXNlcnZpY2VcbiIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZ3JhcGggVERcblx0c3ViZ3JhcGggSXNsYW5kLmlzXG5cdFx0c3ViZ3JhcGggQVBJXG5cdFx0XHRhcHBbXCJHcmFwaFFMIHNlcnZlcjxicj48YnI-L2FwcHMvYXBpPGJyPkF1dGhlbnRpY2F0aW9uPGJyPk1ldHJpY3NcIl1cblx0XHRcdGRvbWFpbltcIlJTSyBkb21haW48YnI-PGJyPi9saWJzL2FwaS9kb21haW5zL3Jzazxicj5HcmFwaFFMIFNjaGVtYTxicj5HcmFwaFFMIFJlc29sdmVyczxicj5TZXJ2aWNlc1wiXVxuXHRcdFx0ZG9tYWluMltcIkFwcGxpY2F0aW9ucyBkb21haW48YnI-PGJyPi9saWJzL2FwaS9kb21haW5zL2FwcGxpY2F0aW9uczxicj5HcmFwaFFMIFNjaGVtYTxicj5HcmFwaFFMIFJlc29sdmVyczxicj5TZXJ2aWNlc1wiXVxuXG5cdFx0XHRhcHAtLT58Q29tYmluZXMgR3JhcGhRTHxkb21haW4gJiBkb21haW4yXG5cdFx0XHRkb21haW4yIC0tPiB8Q2FsbHMgc2VydmljZXN8ZG9tYWluXG5cdFx0ZW5kXG5cdFx0eC1yb2FkW1wiWC1Sb2FkIFNlY3VyaXR5IFNlcnZlclwiXVxuXHRcdG1pY3Jvc2VydmljZVtcIkFwcGxpY2F0aW9ucyBNaWNyb3NlcnZpY2U8YnI-PGJyPi9hcHBzL3NlcnZpY2VzL2FwcGxpY2F0aW9uc1wiXVxuXHRcdGRhdGFiYXNlW1wiUG9zdGdyZVNRTCBEYXRhYmFzZVwiXVxuXHRcdGRvbWFpbjIgLS0-IG1pY3Jvc2VydmljZSAtLT4gZGF0YWJhc2Vcblx0ZW5kXG5cdHN1YmdyYXBoIFJTS1xuXHRcdHgtcm9hZDJbXCJYLVJvYWQgU2VjdXJpdHkgU2VydmVyXCJdXG5cdFx0cnNrLXNlcnZpY2VbXCJSU0sgV2Vic2VydmljZVwiXVxuXHRlbmRcblxuXHRkb21haW4gLS0-IHgtcm9hZFxuXHR4LXJvYWQgLS0-IHgtcm9hZDJcblx0eC1yb2FkMiAtLT4gcnNrLXNlcnZpY2VcbiIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)
+This project is a unified API for island.is products, built as a thin GraphQL layer on top of data/services from government organizations and island.is microservices. Each unit is wrapped in a domain.
+
+Here is a diagram of the project structure:
+
+```mermaid
+graph TD
+ subgraph Island.is
+  subgraph API
+   app["GraphQL server<br><br>/apps/api<br>Authentication<br>Metrics"]
+   domain["RSK domain<br><br>/libs/api/domains/rsk<br>GraphQL Schema<br>GraphQL Resolvers<br>Services"]
+   domain2["Applications domain<br><br>/libs/api/domains/applications<br>GraphQL Schema<br>GraphQL Resolvers<br>Services"]
+
+   app-->|Combines GraphQL|domain & domain2
+   domain2 --> |Calls services|domain
+  end
+  x-road["X-Road Security Server"]
+  microservice["Applications Microservice<br><br>/apps/services/applications"]
+  database["PostgreSQL Database"]
+  domain2 --> microservice --> database
+ end
+ subgraph RSK
+  x-road2["X-Road Security Server"]
+  rsk-service["RSK Webservice"]
+ end
+
+ domain --> x-road
+ x-road --> x-road2
+ x-road2 --> rsk-service
+```
 
 ## URLs
 
-- Dev: N/A
-- [Staging](https://beta.staging01.devland.is/api)
-- Production: N/A
+- Staging: [https://beta.staging01.devland.is/api](https://beta.staging01.devland.is/api)
 
 ## Project structure
 
-The code in this app package should be kept as small as possible. Most business logic should be in [domain libraries](https://github.com/island-is/island.is/tree/main/libs/api/domains). Shared utilities and middlewares should be in libraries as well.
+Keep app package code minimal. Business logic should reside in [domain libraries](https://github.com/island-is/island.is/tree/main/libs/api/domains). Shared utilities should also be in libraries.
 
 ### Domains
 
-Domain libraries represent and wrap an underlying data model or service. As a rule of thumb, each microservice and government organisation should have their own domain library.
-
-They can contain the following exports:
-
-- **typeDefs**: GraphQL schema describing the types, inputs, queries and mutations of the domain.
-- **resolvers**: Object containing GraphQL resolvers for any fields, queries and mutations as needed by the domain.
-- **services**: The domain can export arbitrary services for other domains. These should be strongly typed and not expose any internals of the domain.
+Domain libraries wrap data models or services. Microservices and organizations should have their own domain library, potentially including:
 
-The `typeDefs` and `resolvers` for all domains are merged into a single GraphQL server.
+- **typeDefs**: GraphQL schema for domain types, inputs, queries, mutations.
+- **resolvers**: GraphQL resolvers for the domain.
+- **services**: Services for other domains, with strong typing and no internal exposure.
 
-Generally, the resolvers should be really small. They should only manage the resolver arguments, including input and payload wrappers.
-
-The actual resolver logic should be in service functions. These may call another domain's service, call external services and publish messages on exchanges.
+Resolvers are merged into a single GraphQL server. They manage resolver arguments, delegating logic to service functions that may interact with other domains or services.
 
 ### Services
 
-Services are classes that contain most of the logic for a domain. They should be easy to test and use dependency injection (DI) to get access to other services and connectors.
-
-Currently, there is no DI container. Everything is hooked up manually in tests and `/apps/api/src/graphql/context`.
+Services encapsulate domain logic. They are easy to test and use dependency injection (DI) for accessing services/connectors. Dependency setup is manual in tests and `/apps/api/src/graphql/context`.
 
 ### Type Generation
 
-We use [graphql-codegen](https://graphql-code-generator.com/) to generate TypeScript types for the GraphQL schema.
-
-In addition, client apps can use `graphql-codegen` to join together the API schema with client operations. This validates that operations match the schema, and generates type definitions for operation inputs and payloads.
+Using [graphql-codegen](https://graphql-code-generator.com/), we generate TypeScript types for GraphQL schemas. Client apps can use it to merge the API schema with client operations for validation and type definitions.
 
 ### Shared libraries
 
-For code that can be reused, consider adding it to a shared library. If it's specific to the API, it should be under `/libs/api`, otherwise consider making it available wider. Either way, we can start flat and refactor into subfoldres as the number of libraries grows.
+Reusable code should be in shared libraries. API-specific code goes in `/libs/api`. Structure can be flat or grouped as needed.
 
 Examples:
 
@@ -80,46 +90,42 @@ Examples:
 
 ### Fetch development secrets
 
-Run `AWS_PROFILE=<profile> yarn nx get-secrets <project>`
-
-**Example**:
+Use `AWS_PROFILE=<profile> yarn nx get-secrets <project>`. Example:
 
 ```bash
 AWS_PROFILE=islandis yarn nx get-secrets api
 ```
 
 ### Test requirements
 
-This API has minimal logic and mostly wraps external services. Until we figure out an integration/contract testing strategy, the main focus is on unit tests using mocks for external dependencies.
-
-There should be good test coverage on shared code and services. The resolvers are tricky to test so they should be kept simple, with the main logic in unit tested services.
+This API mainly wraps external services. Focus is on unit tests with mocked external dependencies. Shared code/services should have good test coverage. Resolvers should stay simple.
 
 ## Getting started
 
-To start the API, run:
+Start the API:
 
 ```bash
 yarn start api
 ```
 
 ### Codegen
 
-If you change a GraphQL schema, you need to update the generated TypeScript types which are used by resolvers and client applications:
+After modifying a GraphQL schema, update generated TypeScript types:
 
 ```bash
 yarn nx run api-schema:codegen/frontend-client
 ```
 
 ### Tests
 
-To run tests, you can either run all tests affected by your changes, or run tests in a specific project:
+Run all affected tests or specify a project:
 
 ```bash
 yarn affected:test
 yarn test api
 ```
 
-Many jest arguments can be passed to test commands. For more details, add `--help`.
+Add `--help` for jest arguments:
 
 ```bash
 yarn test api --help
@@ -130,19 +136,19 @@ yarn test api --runInBand
 
 ### New domain
 
-You can create a new domain or shared library using an NX schematic:
+Create a new domain or library with an NX schematic:
 
 ```bash
 yarn generate @nrwl/node:library api/domains/your-domain
 yarn generate @nrwl/node:library api/your-library
 ```
 
-If your domain needs to expose fields in the GraphQL schema, make sure to export `typeDefs` and `resolvers` in your domain's `index.ts`, then add your domain to the list in `/apps/spi/src/graphql/domains.ts`.
+To expose fields in the GraphQL schema, export `typeDefs` and `resolvers` in your domain's `index.ts`, then add to `/apps/spi/src/graphql/domains.ts`.
 
 ## Code owners and maintainers
 
 - [Júní](https://github.com/orgs/island-is/teams/juni/members): `libs/cms`, `libs/api/domains/content-search`
 - [Aranja](https://github.com/orgs/island-is/teams/aranja/members): `libs/cms`, `libs/api/domains/application`, `libs/api/domains/content-search`
 - [Norda](https://github.com/orgs/island-is/teams/norda/members): `libs/api/domains/documents`, `libs/api/domains/national-registry`
 - [Stefna](https://github.com/orgs/island-is/teams/stefna/members): `libs/api/domains/content-search`
-- [Advania](https://github.com/orgs/island-is/teams/advania/members) `libs/api/domains/api-catalogue`
+- [Advania](https://github.com/orgs/island-is/teams/advania/members): `libs/api/domains/api-catalogue`