{"id":23421108,"url":"https://github.com/nhsdigital/nbs-appointments-management-service","last_synced_at":"2025-04-09T09:34:29.956Z","repository":{"id":260070784,"uuid":"807579984","full_name":"NHSDigital/nbs-appointments-management-service","owner":"NHSDigital","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-07T16:44:22.000Z","size":4746,"stargazers_count":1,"open_issues_count":12,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-07T17:42:10.374Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NHSDigital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-29T11:24:47.000Z","updated_at":"2025-04-07T10:20:48.000Z","dependencies_parsed_at":"2025-01-03T12:23:41.724Z","dependency_job_id":"dd358374-3afb-4a76-99b7-fdb227159dc7","html_url":"https://github.com/NHSDigital/nbs-appointments-management-service","commit_stats":null,"previous_names":["nhsdigital/nbs-appointments-management-service"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fnbs-appointments-management-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fnbs-appointments-management-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fnbs-appointments-management-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fnbs-appointments-management-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NHSDigital","download_url":"https://codeload.github.com/NHSDigital/nbs-appointments-management-service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248012996,"owners_count":21033283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-23T02:14:02.475Z","updated_at":"2025-04-09T09:34:29.895Z","avatar_url":"https://github.com/NHSDigital.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# National Booking Service - Manage Your Appointments (MYA)\n\n## Introduction\n\nAn appointment and booking api designed to support national vaccination bookings.\n\n[Product Backlog](https://nhsd-jira.digital.nhs.uk/secure/RapidBoard.jspa?rapidView=7622\u0026projectKey=APPT\u0026view=planning.nodetail\u0026selectedIssue=APPT-26\u0026issueLimit=100#)\n\n[Slack chanel - #appointments-service](https://nhsdigitalcorporate.enterprise.slack.com/archives/C062RBW4NF4)\n\n## Team\n\n- Sponsor - James Spirit\n- Product Owner - Lauren Caveney\n- Development Team - Vincent Crowe, Sam Biram, Kim Crowe, Khurram Aziz, Saritha Lakkreddy, Ste Banks\n- Past Development Team - Joe Farina\n\n### Technologies\n\n- Dotnet V8\n- C# V12\n- Azure Functions V4\n- Javascript/Typescript (React V18)\n- Next.js V14\n- Cosmos document database\n\n### Project Goal\n\nWe will build an Appointments API using\n\n- Will follow REST principles as much as possible\n- Github (for code repo)\n- Azure Devops (for CI pipelines)\n- C# (development language)\n- Azure Functions (as a platform for hosting)\n\nWe will build a web based application for appointment and site management\n\n- We will use React/Next.js\n- Github (for code repo)\n- Azure Devops (pipelines)\n- Azure Web Apps (to host the NextJS server)\n\n## GitHub Repo and signed commits\n\nThe repo has signed commits enabled. This means that only commits that are verified can be merged into the main branch. More information about signed commits can be found [here](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).\n\nYour workstation will need to be set up to use signed commits. Please follow this guide for [instructions](https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/practices/guides/commit-signing.md).\\*\n\n\\*At the time of writing this guide is missing a step in the Windows section. After running `git config --global commit.gpgsign true` you must then run `git config --global user.signingkey \u003ckey\u003e` to actually tell git about the key you just created.\n\n## Running Locally\n\n### Setup\n\n- Install [Docker for Windows](https://docs.docker.com/desktop/install/windows-install/) (use Linux\n  Containers)\n- Install [.NET 8.0](https://learn.microsoft.com/en-us/dotnet/core/install/windows?tabs=net60)\n- Install the [Azure Functions Core\n  Tools](https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local?tabs=windows%2Cisolated-process%2Cnode-v4%2Cpython-v2%2Chttp-trigger%2Ccontainer-apps\u0026pivots=programming-language-csharp)\n- Install [Node V20](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager)\n- Install [NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)\n\n#### VS Code Setup (optional)\n\nIf you are using VS Code, you may find it beneficial to open the repo by opening the `nbs-ams.code-workspace` file itself. This will open a workspace configured with several productivity boons:\n\n- The Explorer window is split into folders for convenience and to make navigating the repo quicker/easier\n- Terminals can be opened straight into any of these folders using the `ctrl-shift-'` command\n- Default build tasks have been configured for Dotnet and Typescript. You can run these with the `ctrl-shift-b` command\n- Non-build tasks have been configured for starting the docker, dotnet, and NextJS services. These are configured in `tasks.json` folders and can be ran through `Terminal` -\u003e `Run Task...`\n\n### Running locally\n\nEach of the following steps needs to be done in a separate terminal window\n\n- Run containerised services\n  - From the root folder run `docker compose --profile local up --build -d `\n  - (OR if using VS Code) run the `Start local development containers` task\n\nIt is also possible to run next and api services locally **not** using docker:\n\n- Start mock-api, mock-oidc-server and cosmos containers:\n  - run ` docker compose up --build -d mock-api oidc-server cosmos`\n- Run the API\n  - From the folder `/src/api/Nhs.Appointments.Api` run the command `func start`\n  - (OR if using VS Code) run the `Clean and Run API` task\n- Run the Web Application\n  - From the folder `/src/client/` run `npm install` and then run `npm run dev`\n  - (OR if using VS Code) run the `Run Client in Dev Mode` task\n\n### Setting a cert for the OIDC server\n\nTo run the oidc-server you will need to install a certificate. You will need to generate\nand trust a dev cert with the following command (in order to ensure that the certificate\nis placed in the correct location you should run the command from your user profile folder\nor amend the command accordingly).\n\n`dotnet dev-certs https -ep .aspnet/https/aspnetapp.pfx -p password -t -v`\n\n### Notes about configuration\n\nThe API expects cosmos to be running at \"https://localhost:8081\"\nThe API expects the mockapi to be running at \"http://localhost:4011\"\nThe Web Application expects the API to be running at \"http://localhost:7071\"\n\nIf your configuration causes any of these to be running differently then you will need to change the application\nconfiguration files accordingly. (Or use environment variables to override local configuration)\n\nAPI configuration file is found at `/src/Nhs.Appointments.Api/localsettings.json`\nClient configuration file is found at `/src/client/.env`\n\n### Exploring the Cosmos Database\n\nWhen running locally in docker the data in the cosmos database can be viewed and modified using the cosmos emulator\nexplorer. To access the explorer visit `https://localhost:8081/_explorer/index.html` (note you may get an unsafe page\nwarning unless you import the certificate from the cosmos container, this can safely be ignored for this url)\n\n### Seeding the Cosmos Database\n\nTo meaningfully explore the API/frontend you'll need a minimum set of data present in the Cosmos DB. There is a .NET Console App which uploads a set of cosmos-friendly documents in `/src/data/CosmosDbSeeder`.\n\nYou simply need to run this app to upload the default mock data. If using VS Code you can do this by running the `Seed Cosmos` task. You can also run it manually with the `dotnet run` terminal command in that folder.\n\nThe folder/file structure within the `items` folder matches the desired structure in Cosmos 1:1 (that is, there will be a Cosmos container called `index_data` which will contain each child `.json` file as a document). If you wish to create or modify a container simply alter these files, then re-run the seeder. Remember that if you run the app manually you will need to run `dotnet clean` first for the changes to be picked up (the VS Code task does this for you automatically).\n\nAlternatively, you can upload these files one at a time yourself through the [emulator's browser interface](https://localhost:8081/_explorer/index.html).\n\n## Authenticating calls to the API\n\nREST calls using an API user must be signed (via HMAC) using the key associated with the api user.\nThe api user is identified using the ClientId header - so the in the above example a signed request with a ClientId header of `dev` would be needed to make api calls\n\n## Code Style \u0026 Formatting\n\n.NET code style and formatting rules are imposed by [dotnet format](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-format) because it is IDE and platform agnostic, and natively included in the .NET SDK. Rule are dictated by an [.editorconfig file](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/code-style-rule-options).\n\nThe warnings and errors about violations of these rules could be surfaced at build time by enabling [Enforce Code Style In Build (\u003cEnforceCodeStyleInBuild\u003e)](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#enforcecodestyleinbuild) in each `.csproj` file.\n\n#### How do I configure my IDE?\n\nBecause the `.editorconfig` file is attached to the solution, both Rider and Visual Studio should automatically use its rules in place of their own defaults.\n\n- on Visual Studio, you may need to visit `Analyze -\u003e Code Cleanup -\u003e Configure Code Cleanup`, then change your default profile to include only the `Fix all warnings and errors set in EditorConfig` step.\n- on Rider, you may need to visit `Settings -\u003e Editor -\u003e Inspection Settings` then ensure `Read settings from editorconfig, project settings and rule sets` is ticked.\n\n#### How do I format only one file?\n\nThe easiest way is probably through an IDE, configured as per the step above. Most IDEs can format single files if you right-click it in the explorer.\nFailing that, the harder way is to pass an `--include \u003cPATH\u003e` argument to `dotnet format` on the command line, providing it the files you want it to format.\n\n#### How do I run the formatter manually?\n\nYou can invoke dotnet format on the command line like so:\n\n```\ndotnet format nbs-manage-your-appointments.sln --verify-no-changes --report dotnet-format-report.json\n```\n\nThis will create a report named `dotnet-format-report.json` in the repository root. This has been added to the `.gitignore` file so should not cause a tracked change.\n\nThe `--verify-no-changes` argument tells `format` to make no changes. If you want it to automatically apply fixes, simply remove this argument:\n\n```\ndotnet format nbs-manage-your-appointments.sln\n```\n\nIf you want to run it against one or more specific directories in the solution (or indeed exclude one or more), these can be specified through the `--include \u003cPATH\u003e` and `--exclude \u003cPATH\u003e` arguments.\n\nIf you want to see only errors, or include suggestions, pass a new value to the severity argument (accepted values are `error`, `warn`, and `info`):\n\n```\ndotnet format nbs-manage-your-appointments.sln --severity \u003cSEVERITY\u003e\n```\n\nSee the [docs](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-format) for more on this.\n\n## Tests\n\n### Frontend Unit Tests (using Jest)\n\nFrom `~/src/client`:\n\n- Ensure you have ran `npm i`\n- Simply run `npm run test`\n\nIf running the workspace in VS Code, the Jest tests should be automatically discovered in the test explorer window. You should be able to run and debug them via the UI.\n\n### Frontend E2E Tests (using Playwright)\n\nFrom `~/src/client`:\n\n- Ensure you have ran `npm i`\n- The very first time you run the tests you will need to run `npx playwright install`. This instructs Playwright to download and instantiate the latest version of the browsers it requires.\n- Ensure the Docker and .NET services are running following their respective setup commands (In the future we hope to be set these up automatically)\n- Optionally run the frontend app (If you're not already running it, Playwright will start it up for you)\n- Run `npm run test:e2e`. Optionally if you wish to view a step-by-step visual output of each test, run `npm run test:e2e:ui`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fnbs-appointments-management-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnhsdigital%2Fnbs-appointments-management-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fnbs-appointments-management-service/lists"}