CONTRIBUTING.md

Getting Started

Prerequisites

• VS Code
  • choco install vscode
• WSL2
  • WSL2 Installation Guide
• Docker Desktop
  • choco install docker-desktop
• pgAdmin
  • choco install pgadmin4

Project Setup

1. Start Docker Desktop.
2. Open the project in VS Code.
3. The project should automatically detect the .devcontainer folder and ask you to reopen the project in a container. Before doing so, Copy the .env.example file to .env and fill in the necessary values.
4. Reopen the project in the dev container. (You can also do this by clicking on the blue button in the bottom left corner of the window.)
5. The project will now start downloading the necessary dependencies and setting up the environment.
6. Docker images
7. Node modules
8. VS Code extensions

Database population

There are a number of commands defined in package.json that can be run to populate the database with data:

1. npm run orm-create-db
2. npm run orm-run-pending-migrations
3. npm run orm-seed-users

Running the project

The project can be run in debug mode via: npm run dev. You can then access the application at https://localhost:3000.

A production build can be run via: npm run build followed by npm run preview. You can then access the application at https://localhost:3000.

Application Infrastructure

The application is built using the following primary technologies:

• Nuxt.js
  • TypeScript
  • PrimeVue
  • PrimeFlex
  • Zod
• @azure/msal-node
• Node.js
• PostgreSQL
  • MikroORM
• Docker

Application Architecture

The application is a monolith following a layered architecture. The application is split into the following layers:

Server

• domain
  • Entities & Value Objects
• data
  • models (used by MikroORM)
• api
  • This is currently blending the application and infrastructure layers. This will be refactored in the future by separating the application and infrastructure layers.

Client

• pages
• components
• layouts

CI/CD Notes

The Infrastructure is managed by Azure Bicep. The CI/CD pipeline is managed by GitHub Actions. Communication between GitHub and Azure is managed by OpenID Connect.

• Configuration details
  • Supporting details
• GitHub Environment details

Slackbot testing

Create an ngrok tunnel to the local server:

ngrok http https://localhost:3000

Update the Slackbot configuration (Event Subscriptions) to point to the generated ngrok tunnel.

https://<ngrok-url>/api/slack

Note that this will only work if the server is running locally (npm run dev).

Once the local server is stopped, the ngrok tunnel will be closed and the Slackbot will no longer work.

Troubleshooting

Most issues can be resolved by restarting the dev container. This can be done by closinng and reopening VSCode. Don't do this too quickly. When VSCode is closed, the Docker containers take some time to stop.

If you are still having issues, try deleting the containers and images and restarting the dev container.

If you run into issues related to npm install hanging (Known bug). You can try running npm install on each dependency individually. For example: npm install @mikro-orm/core, npm install nuxt, etc. This is a worst case scenario and seems to surface intermittently. The bug is potentially related to IPV6.