the calendar is your timesheet
Keep your calendar up-to-date with what you work on, and that's it. You're done.
📖 Table of Contents
* [➤ Roadmap](#-roadmap)
* [➤ Backlog](#-backlog)
* [➤ Environments](#-environments)
* [➤ Contributing](#-contributing)
* [Getting started](#getting-started)
* [Set up environment](#set-up-environment)
* [Code structure](#code-structure)
* [Node version](#node-version)
* [Authentication](#authentication)
* [Google](#google)
* [Branching / Deploying](#branching--deploying)
* [Main branch](#main-branch)
* [Dev branch](#dev-branch)
* [Feature branches](#feature-branches)
* [Naming conventions](#naming-conventions)
* [See also](#see-also)
* [GraphQL](#graphql)
* [Extensions for VS Code](#extensions-for-vs-code)
* [Maintenance Mode](#maintenance-mode)
| Milestone | Release date | Version |
|---|---|---|
| 💧 1 - Hydrogen | 03.02.2020 |  |
| 🎈 2 - Helium | 02.04.2020 |  |
| 🔋 3 - Lithium | 11.05.2020 |  |
| 🛰 4 - Beryllium | 22.05.2020 |  |
| ☄️ 5 - Boron | 19.08.2020 |  |
| 🌱 6 - Carbon | 09.09.2020 |  |
| 💨 7 - Nitrogen | 15.10.2020 |  |
| 15.12.2020 |  |
|
| 🦷 9 - Fluor | 27.04.2021 |  |
| 💡 10 - Neon | 16.11.2022 |  |
| 🧂 11 - Sodium | 17.04.2023 |  |
| 🧲 12 - Magnesium | 21.02.2024 |  |
| ⚪ 13 - Aluminium | 25.02.2025 |  |
| 🛎️ 14 - Silisium | 12.03.2025 |  |
| 🦿 15 - Fosfor | 19.03.2025 |  |
Our backlog can be found here.
| Environment | Branch/Tag | Node Version | CI | Status |
|---|---|---|---|---|
| Production | main | Node 22 LTS (22.14.0) | Stage swapping | - |
| Development (new features) | dev and feat/ | Node 22 LTS (22.14.0) | Yes |  |
| Staging (pre-prod) | Release tags | Node 22 LTS (22.14.0) | Yes |  |
Contributions are very velcome! Here's some guidance to get started! ❤️
- Check out the
devbranch - Run
npm install - Run
npm run-script create-envto create your own.envfile for local testing - Set neccessary parameters in your new
.envfile (seeSet up .envbelow) - Install the Azure App Service extension for vscode
- Install the ESLint extension for vscode
- Install the i18n Ally extension for vscode
- Create an Azure app registration
- Run
npm run-script watchto watch bothserverandclientchanges concurrently
The following permissions are required by Azure App Registration:
You've copied .env.sample into .env, anually or using npm run-script create-env.
Now you need to set the required environment variables from this table:
| Key | Description | Required |
|---|---|---|
AUTH_PROVIDERS |
Auth providers. E.g. azuread-openidconnect and google. |
Yes |
MICROSOFT_CLIENT_ID |
ID of the AD application registration. | Yes |
MICROSOFT_CLIENT_SECRET |
Password/secret of the AD application registration. | Yes |
MICROSOFT_REDIRECT_URI |
Redirect URL for Microsoft (azuread-openidconnect) login |
Yes |
MICROSOFT_SCOPES |
Scopes for Microsoft Graph queries. See https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent. | Yes |
GOOGLE_CLIENT_ID |
ID of the Google application registration | No |
GOOGLE_CLIENT_SECRET |
Password/secret of the Google registration. | No |
GOOGLE_REDIRECT_URI |
Redirect URL for Google login | No |
GOOGLE_SCOPES |
Scopes for Google APIs and login | No |
PORT |
Defaults to 9001 |
No |
SESSION_NAME |
A unique name for the sessions. | No |
SESSION_SIGNING_KEY |
Just a random string to secure the sessions. | Yes |
REDIS_CACHE_HOSTNAME |
Hostname for the Redis cache | Yes |
REDIS_CACHE_KEY |
Secret key for the Redis cache | Yes |
APOLLO_KEY |
Key for reporting to Apollo Studio | Yes |
APOLLO_GRAPH_VARIANT |
Graph variant for reporting to Apollo Studio. See this article | Yes |
MONGO_DB_CONNECTION_STRING |
Connection string for MongoDB | Yes |
MONGO_DB_DB_NAME |
Database name for MongoDB | Yes |
API_TOKEN_SECRET |
Secret to generate API tokens | Yes |
DEBUG |
To debug the Node backend. E.g. app* to see all logs from app. See debug. |
No |
LAUNCH_BROWSER |
Set to 1 if you want to automatically open did in the browser when running watch task. |
No |
| Folder/File | Description |
|---|---|
/shared |
Shared code between client and server |
/shared/config |
Configuration files used across client and server |
/shared/config/security |
Shared security configuration and permission definitions |
/shared/utils |
Utility functions shared between client and server |
/client |
Client TypeScript source using React and Apollo Client |
/client/app |
Core application files including entry point and router |
/client/components |
Reusable React components used throughout the solution |
/client/graphql-client |
Apollo client setup and configuration |
/client/graphql-mutations |
GraphQL mutation definitions |
/client/graphql-queries |
GraphQL query definitions |
/client/hooks |
Custom React hooks |
/client/i18n |
Internationalization files and translation resources |
/client/logging |
Client-side logging functionality |
/client/pages |
Main application pages organized by feature |
/client/parts |
Page sections and partial components |
/client/theme |
Styling, theme configuration, and icon catalog |
/client/types |
TypeScript type definitions and interfaces |
/client/utils |
Client-side utility functions |
/server/public |
Public assets and static files served under "/" |
/server/routes |
Express routes using Handlebars views |
/server/graphql |
GraphQL schema and resolvers |
/server/middleware |
Express middleware functions |
/server/services |
Business logic services (MS Graph, database, etc.) |
/server/utils |
Server-side utility functions |
/server/views |
Express Handlebars view templates |
/server/app.ts |
Express app configuration |
/server/index.ts |
Node.js server entry point |
/assets |
Static assets like images and error pages |
/webpack |
Webpack configuration and build utilities |
NB: did should be developed with Node 22.14.0 (LTS).
It's recommended to use nvm. We have a .nvrc with node version set to 18.18.0.
did supports authentication with both Microsoft (azuread-openidconnect) and Google, but google support is in experimental state only supporting adding gmail accounts as externals to an existing Microsoft did subscription.
The auth providers are set in process.env.AUTH_PROVIDERS and sent to the client through GraphQL query authProviders.
See wiki for more details on using did with Google.
After successful review and CI/CD pipeline completion, changes are deployed to the staging slot at didapp-staging.azurewebsites.net. Once verified in staging, the changes can be swapped to production at did.puzzlepart.com.
The /dev branch also requires pull requests, and is set up with a CI/CD pipeline which deploys to didapp-dev.azurewebsites.net.
For new features use the naming convention below. A CI/CD pipeline which deploys to didapp-dev.azurewebsites.net is set up for branches matching the pattern feat/* and dev.
You are encouraged to branch with either of the following prefixes
- hotfix/
- bugfix/
- feat/
See also A successful Git branching model
If you want to test with your web app, checkout Creating your own app registration in the Azure Portal in our wiki.
The extension Apollo extension for VS Code is recommended for working with GraphQL in vscode.
The Apollo VS Code extension provides an all-in-one tooling experience for developing apps with Apollo.
The extension enables you to:
- Add syntax highlighting for GraphQL files and gql templates inside JavaScript files
- Get instant feedback and intelligent autocomplete for fields, arguments, types, and variables as you write queries
- Manage client side schema alongside remote schema
- See performance information inline with your query definitions
- Validate field and argument usage in operations
- Navigate projects more easily with jump-to and peek-at definitions
- Manage client-only schemas
- Switch graph variants to work with schemas running on different environments
The application supports a maintenance mode that can be enabled during deployments or system updates. When maintenance mode is enabled, all requests will be served with a maintenance page instead of the regular application.
To enable maintenance mode, set the MAINTENANCE_MODE environment variable to true or 1. This can be done in your deployment process or directly in your environment:
[](#enable-maintenance-mode)
# ➤ Enable maintenance mode
export MAINTENANCE_MODE=true
[](#disable-maintenance-mode)
# ➤ Disable maintenance mode
export MAINTENANCE_MODE=false
[](#or-unset-the-variable)
# ➤ or unset the variable
unset MAINTENANCE_MODEAPI routes (paths starting with /api/) will still function normally even in maintenance mode to allow for background services to continue functioning.
We use https://studio.apollographql.com/ for GraphQL schema documentation.
 |
 |
 |
|---|---|---|
| Carl Joakim Damsleth | Ole Martin Pettersen | Ole Kristian Mørch-Storstein |
| [email protected] | [email protected] | [email protected] |