# Technical Implementation

Hi there, you are probably new to the project. Here you can find a quick overview of what you can expect and what is expected from you as a contributor.

## Technology

### General

Our main programming language is [TypeScript](https://www.typescriptlang.org/). TypeScript is a popular programming language which is compiled into JavaScript and offers strict data types, readable code and a compiler that catches many errors. Deep integration in development tools helps teams build and maintain large solutions.

We use [NX](https://nx.dev) to manage the monorepo structure. We have one set of NodeJS modules used by all code and any changes in there affect potentially multiple services. 

| Tool                                          | Description                          |
| --------------------------------------------- | ------------------------------------ |
| [NodeJS](https://nodejs.org/en/)              | Scripts and server-side framework.   |
| [TypeScript](https://www.typescriptlang.org/) | Programming language.                |
| [NX](https://nx.dev/react)                    | Monorepo tools and code scaffolding. |

### Frontend

When creating interfaces, teams should use the [React](https://reactjs.org/) frontend framework. With React, teams create user interface (UI) components which they then arrange to form complete interfaces.

Many of these UI components can be reused for multiple interfaces, across teams and projects, e.g. buttons, inputs and navigation. Teams should add these to [Storybook](https://storybook.js.org/), which provides an overview of all reusable components, as well as a testing environment for interested stakeholders.

| Tool                                                          | Description                                                 |
| ------------------------------------------------------------- | ----------------------------------------------------------- |
| [React](https://reactjs.org/)                                 | UI framework.                                               |
| [NextJS](https://nextjs.org/)                                 | Front-end framework with routing and server side rendering. |
| [Vanilla Extract](https://vanilla-extract.style/)             | Stylesheets in TypeScript.                                  |
| [Storybook](https://storybook.js.org/)                        | Develop and document React components in isolation.         |
| [Apollo Client](https://www.apollographql.com/docs/react/)    | GraphQL client.                                             |
| [GraphQL Code Generator](https://graphql-code-generator.com/) | Generate GraphQL clients and types.                         |
| [Playwright](https://playwright.dev/)                         | Automated browser testing tool.                             |

### Backend

The backend is also implemented in **TypeScript**, using the [Node.JS](https://nodejs.org/en/about/) framework. By using the same programming language in the frontend and backend, we can share code, e.g. types and validation. The work becomes more efficient, with fewer developer roles since more developers can work on both sides. Node.JS also has a large and active open-source community, with mature code libraries covering most needs.

Backend servers should provide a [GraphQL](https://graphql.org/) interface for frontend clients. It defines a schema that describes all the available data and operations. Whenever possible, the schema should represent an idealised world independent of implementation details. When designed well, it is possible to replace backend systems without changing the schema or frontend.

GraphQL provides better separation between the frontend and backend. In one GraphQL query, the frontend can ask for everything it requires. The GraphQL server calls web services and databases as needed to resolve the query, and the result contains only the data that the frontend requested.

| Tool                                                 | Description                                  |
| ---------------------------------------------------- | -------------------------------------------- |
| [NestJS](https://nestjs.com/)                        | Server-side framework for NodeJS.            |
| [Sequelize](https://sequelize.org/)                  | Database object relational mapper.           |
| [OpenAPI Generator](https://openapi-generator.tech/) | Generate clients and types for OpenAPI APIs. |

### Code Quality

| Tool                             | Description             |
| -------------------------------- | ----------------------- |
| [Jest](https://jestjs.io/)       | Automated testing tool. |
| [ESLint](https://eslint.org/)    | Code checker.           |
| [Prettier](https://prettier.io/) | Code formatter.         |

### Protocols and specifications

| Tool                                           | Description                             |
| ---------------------------------------------- | --------------------------------------- |
| [GraphQL](https://graphql.org/)                | API protocol for our frontend projects. |
| [OpenAPI](https://www.openapis.org/)           | Specification to describe rest APIs.    |
| [Open ID Connect](https://openid.net/connect/) | Authentication protocols.               |

### Code storage and Repositories

The main digital government platform is in a monorepo stored in GitHub. It contains the code for all of its solutions in one code repository with collaboration between all teams.  See more on [monorepo](/technical-overview/monorepo.md).

| Tool                                                         | Description                                            |
| ------------------------------------------------------------ | ------------------------------------------------------ |
| [GitHub](https://github.com/)                                | Platform to create, store, manage and share code.      |
| [Island.is monorepo](https://github.com/island-is/island.is) | Open source repository for Iceland's digital services. |

### Infrastructure

We host our solutions in a containerised cloud environment, using [Docker](https://www.docker.com/resources/what-container) and [Kubernetes](https://kubernetes.io/), on  [AWS](/development/devops/environment-setup.md). infrastructure. Applications are composed of services that are [packaged in Docker containers](#dockerizing) and then deployed in a Kubernetes cluster using Helm.  To avoid lock-in, we use open-source databases and tools that we can host on any cloud infrastructure.

With Docker containers, services run independently of the hardware. They are easy to spin up, especially suitable for Agile development with continuous delivery and can handle increased load and hardware problems.

We've configured our cloud environment with a secure virtual private network that limits external access to sensitive services as well as allowing us to set up VPN connections and fixed IP addresses to integrate with external services. We also have an X-Road Security Server to access other government organisations through Straumurinn.

| Tool                                                                                             | Description                                                                                |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| [Docker](https://www.docker.com/)                                                                | Virtual machine containers for continuous integration and deployment.                      |
| [Kubernetes](https://kubernetes.io/)                                                             | Host docker containers in production.                                                      |
| [Helm](https://helm.sh/)                                                                         | Kubernetes deployment configuration.                                                       |
| [X-Road](https://x-road.global/)                                                                 | X-Road is a centrally managed distributed Data Exchange Layer between information systems. |
| [Straumurinn](https://docs.devland.is/technical-overview/x-road/straumurinn-usage-and-operation) | The Icelandic government x-road network.                                                   |

### Content and documentation

<table><thead><tr><th width="473">Tool</th><th>Description</th></tr></thead><tbody><tr><td><a href="https://www.gitbook.com/">Gitbook</a></td><td>Content management for technical documentation.</td></tr><tr><td><a href="https://www.contentful.com/">Contentful</a></td><td>Headless content management system for application's content.</td></tr><tr><td><a href="www.notion.so/">Notion.so</a></td><td>Tool used for internal documentation and task management.</td></tr></tbody></table>

## Practices

To contribute you need to follow the standard [GitHub Pull Request (PR)](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) workflow. When you open a PR, your code will be run through the [CI process](/technical-overview/adr/0002-continuous-integration.md) automatically. Ask for a [code-review](/technical-overview/code-reviews.md) and when you get an approval, merge to `main`. Rinse and repeat.

When a code change gets on `main`, that will create Docker containers for all services and everything will get deployed to `Dev` env. For more info please see the [Continuous Delivery process](/development/devops/continuous-delivery.md).

We expect contributors to deliver the following:

* the business logic
* the tests
* documentation
* [logs](/development/devops/logging.md)
* [metrics](/development/devops/metrics.md)

## Starting a new project/application

If you are adding a new application, please follow the instructions [here](/development/generate.md).

## Dockerizing

You simply need to add an NX target to your service to enable creating a Docker image for it. For more info see [dockerizing](/development/devops/dockerizing.md).

## Kubernetes

We have developed a DSL to describe a service infrastructure setup. You pretty much only need to add your ingress (optional), environment variables (optional) and secrets (optional) and your service can get deployed to Dev. For more info, please see [Service Configuration](/development/devops/service-setup.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.devland.is/technical-overview/technical-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.