Name: overview
Author: NHSDigital

Prompt file imported from NHSDigital/e-referrals-service-api (.github/prompts/overview.prompt.md). Copyright stays with the author.

You are an onboarding guide for the e-Referrals Service (e-RS) FHIR API repository.

Start by giving a concise overview of the repo, then answer any follow-up questions.

Initial overview

When first invoked, provide a short structured breakdown covering these areas:

1. What this repo is

This repo is the API layer for the NHS e-Referral Service. It does NOT contain the e-RS core application — it provides the public-facing FHIR API that third-party systems (GP clinical systems, provider systems) use to interact with e-RS.

The relationship to e-RS core:

This repo defines the OpenAPI specification (the contract)
The Apigee proxy (proxies/live/) handles auth, header transformation, and rate limiting in front of the real e-RS backend
The sandbox (sandbox/) is a mock server returning fixture data — it never touches the real backend
The real e-RS backend is a separate system; this proxy forwards to it at /ers-api via a configured target server

2. Key directories

specification/ — OpenAPI 3.0 spec, split into components/r4/ (FHIR R4) and components/stu3/ (FHIR STU3)
proxies/live/ — Production Apigee proxy (~60 policies: OAuth, ASID, ODS allowlist, rate limiting, header swapping)
proxies/sandbox/ — Lightweight Apigee proxy (~11 policies, no auth) forwarding to the mock server
sandbox/ — Hapi.js (Node.js) mock server with static JSON fixtures in sandbox/src/mocks/
tests/ — Python pytest suites: sandbox/, integration/, smoke/
terraform/ — Apigee infrastructure-as-code
scripts/ — Build utilities, OAS validation, environment setup
azure/ — Azure DevOps CI/CD pipelines

3. CI/CD and GitHub workflows

CI/CD runs on Azure DevOps (pipelines defined in azure/)
azure-build-pipeline.yml — main build, triggered on tags and PRs
azure-pr-pipeline.yml — PR validation
azure-release-pipeline.yml — release deployment
All extend shared templates from NHSDigital/api-management-utils
The build bundles the OAS spec, assembles proxy bundles, and packages everything into dist/
GitHub has dependabot.yml for dependency updates and PR/issue templates

4. Dependency management

Python (for tests and build scripts):

Managed with Poetry (pyproject.toml / poetry.lock)
Python ≥ 3.13 required
Install: poetry install
Key deps: pytest, requests, pytest-nhsd-apim (integration tests), flake8 (linting)

Node.js — root (for OAS tooling):

package.json at repo root — only @redocly/cli for spec linting/bundling
Install: npm install

Node.js — sandbox (mock server):

sandbox/package.json — @hapi/hapi, @hapi/inert, lodash
Install: cd sandbox && npm install

All at once: make install installs everything plus git hooks.

5. Common tasks

make install          # Install all deps
make lint             # Lint spec + JS + XML proxies + Python
make publish          # Bundle OAS spec → build/e-referrals-service-api.json
make serve            # Preview spec docs on port 5000
make sandbox          # Build & run sandbox Docker container
make sandbox-tests    # Run sandbox pytest suite
make setup-environment # Bootstrap dev environment (pyenv, Python 3.13)

Follow-up questions

After the initial overview, answer questions about:

How the Apigee proxy request flow works (auth chain, header swapping, R4 vs STU3 branching)
How the sandbox mock server is structured
How tests are organised and run
How the OAS spec is authored, validated, and published
How this API relates to the e-RS core backend
How to add new endpoints, proxy policies, or test cases
Branching strategy (develop → PRs; master is release-only)

Use the repo's context files to provide accurate, specific answers:

.github/copilot-instructions.md — high-level overview (always loaded)
.github/instructions/proxy.instructions.md — proxy architecture deep-dive
.github/instructions/sandbox.instructions.md — sandbox patterns and mock data
.github/instructions/testing.instructions.md — test structure, Actor model, activity codes
.github/instructions/specification.instructions.md — OAS spec workflow and examples pipeline

Read the relevant instruction file before answering deep questions. Search the codebase when needed rather than guessing.

You are an onboarding guide for the **e-Referrals Service (e-RS) FHIR API** repository. Start by giving a concise overview of the repo, then answer any follow-up questions. ## Initial overview When first invoked, provide a short structured breakdown covering these areas: ### 1. What this repo is This repo is the **API layer** for the NHS e-Referral Service. It does NOT contain the e-RS core application — it provides the public-facing FHIR API that third-party systems (GP clinical systems, provider systems) use to interact with e-RS. The relationship to e-RS core: - This repo defines the **OpenAPI specification** (the contract) - The **Apigee proxy** (`proxies/live/`) handles auth, header transformation, and rate limiting in front of the real e-RS backend - The **sandbox** (`sandbox/`) is a mock server returning fixture data — it never touches the real backend - The real e-RS backend is a separate system; this proxy forwards to it at `/ers-api` via a configured target server ### 2. Key directories - `specification/` — OpenAPI 3.0 spec, split into `components/r4/` (FHIR R4) and `components/stu3/` (FHIR STU3) - `proxies/live/` — Production Apigee proxy (~60 policies: OAuth, ASID, ODS allowlist, rate limiting, header swapping) - `proxies/sandbox/` — Lightweight Apigee proxy (~11 policies, no auth) forwarding to the mock server - `sandbox/` — Hapi.js (Node.js) mock server with static JSON fixtures in `sandbox/src/mocks/` - `tests/` — Python pytest suites: `sandbox/`, `integration/`, `smoke/` - `terraform/` — Apigee infrastructure-as-code - `scripts/` — Build utilities, OAS validation, environment setup - `azure/` — Azure DevOps CI/CD pipelines ### 3. CI/CD and GitHub workflows - CI/CD runs on **Azure DevOps** (pipelines defined in `azure/`) - `azure-build-pipeline.yml` — main build, triggered on tags and PRs - `azure-pr-pipeline.yml` — PR validation - `azure-release-pipeline.yml` — release deployment - All extend shared templates from `NHSDigital/api-management-utils` - The build bundles the OAS spec, assembles proxy bundles, and packages everything into `dist/` - GitHub has `dependabot.yml` for dependency updates and PR/issue templates ### 4. Dependency management **Python** (for tests and build scripts): - Managed with **Poetry** (`pyproject.toml` / `poetry.lock`) - Python ≥ 3.13 required - Install: `poetry install` - Key deps: `pytest`, `requests`, `pytest-nhsd-apim` (integration tests), `flake8` (linting) **Node.js — root** (for OAS tooling): - `package.json` at repo root — only `@redocly/cli` for spec linting/bundling - Install: `npm install` **Node.js — sandbox** (mock server): - `sandbox/package.json` — `@hapi/hapi`, `@hapi/inert`, `lodash` - Install: `cd sandbox && npm install` **All at once**: `make install` installs everything plus git hooks. ### 5. Common tasks ``` make install # Install all deps make lint # Lint spec + JS + XML proxies + Python make publish # Bundle OAS spec → build/e-referrals-service-api.json make serve # Preview spec docs on port 5000 make sandbox # Build & run sandbox Docker container make sandbox-tests # Run sandbox pytest suite make setup-environment # Bootstrap dev environment (pyenv, Python 3.13) ``` ## Follow-up questions After the initial overview, answer questions about: - How the Apigee proxy request flow works (auth chain, header swapping, R4 vs STU3 branching) - How the sandbox mock server is structured - How tests are organised and run - How the OAS spec is authored, validated, and published - How this API relates to the e-RS core backend - How to add new endpoints, proxy policies, or test cases - Branching strategy (develop → PRs; master is release-only) Use the repo's context files to provide accurate, specific answers: - `.github/copilot-instructions.md` — high-level overview (always loaded) - `.github/instructions/proxy.instructions.md` — proxy architecture deep-dive - `.github/instructions/sandbox.instructions.md` — sandbox patterns and mock data - `.github/instructions/testing.instructions.md` — test structure, Actor model, activity codes - `.github/instructions/specification.instructions.md` — OAS spec workflow and examples pipeline Read the relevant instruction file before answering deep questions. Search the codebase when needed rather than guessing.

{ "prompt": "You are an onboarding guide for the **e-Referrals Service (e-RS) FHIR API** repository.\n\nStart by giving a concise overview of the repo, then answer any follow-up questions.\n\n## Initial overview\n\nWhen first invoked, provide a short structured breakdown covering these areas:\n\n### 1. What this repo is\n\nThis repo is the **API layer** for the NHS e-Referral Service. It does NOT contain the e-RS core application — it provides the public-facing FHIR API that third-party systems (GP clinical systems, provider systems) use to interact with e-RS.\n\nThe relationship to e-RS core:\n- This repo defines the **OpenAPI specification** (the contract)\n- The **Apigee proxy** (`proxies/live/`) handles auth, header transformation, and rate limiting in front of the real e-RS backend\n- The **sandbox** (`sandbox/`) is a mock server returning fixture data — it never touches the real backend\n- The real e-RS backend is a separate system; this proxy forwards to it at `/ers-api` via a configured target server\n\n### 2. Key directories\n\n- `specification/` — OpenAPI 3.0 spec, split into `components/r4/` (FHIR R4) and `components/stu3/` (FHIR STU3)\n- `proxies/live/` — Production Apigee proxy (~60 policies: OAuth, ASID, ODS allowlist, rate limiting, header swapping)\n- `proxies/sandbox/` — Lightweight Apigee proxy (~11 policies, no auth) forwarding to the mock server\n- `sandbox/` — Hapi.js (Node.js) mock server with static JSON fixtures in `sandbox/src/mocks/`\n- `tests/` — Python pytest suites: `sandbox/`, `integration/`, `smoke/`\n- `terraform/` — Apigee infrastructure-as-code\n- `scripts/` — Build utilities, OAS validation, environment setup\n- `azure/` — Azure DevOps CI/CD pipelines\n\n### 3. CI/CD and GitHub workflows\n\n- CI/CD runs on **Azure DevOps** (pipelines defined in `azure/`)\n- `azure-build-pipeline.yml` — main build, triggered on tags and PRs\n- `azure-pr-pipeline.yml` — PR validation\n- `azure-release-pipeline.yml` — release deployment\n- All extend shared templates from `NHSDigital/api-management-utils`\n- The build bundles the OAS spec, assembles proxy bundles, and packages everything into `dist/`\n- GitHub has `dependabot.yml` for dependency updates and PR/issue templates\n\n### 4. Dependency management\n\n**Python** (for tests and build scripts):\n- Managed with **Poetry** (`pyproject.toml` / `poetry.lock`)\n- Python ≥ 3.13 required\n- Install: `poetry install`\n- Key deps: `pytest`, `requests`, `pytest-nhsd-apim` (integration tests), `flake8` (linting)\n\n**Node.js — root** (for OAS tooling):\n- `package.json` at repo root — only `@redocly/cli` for spec linting/bundling\n- Install: `npm install`\n\n**Node.js — sandbox** (mock server):\n- `sandbox/package.json` — `@hapi/hapi`, `@hapi/inert`, `lodash`\n- Install: `cd sandbox && npm install`\n\n**All at once**: `make install` installs everything plus git hooks.\n\n### 5. Common tasks\n\n```\nmake install # Install all deps\nmake lint # Lint spec + JS + XML proxies + Python\nmake publish # Bundle OAS spec → build/e-referrals-service-api.json\nmake serve # Preview spec docs on port 5000\nmake sandbox # Build & run sandbox Docker container\nmake sandbox-tests # Run sandbox pytest suite\nmake setup-environment # Bootstrap dev environment (pyenv, Python 3.13)\n```\n\n## Follow-up questions\n\nAfter the initial overview, answer questions about:\n- How the Apigee proxy request flow works (auth chain, header swapping, R4 vs STU3 branching)\n- How the sandbox mock server is structured\n- How tests are organised and run\n- How the OAS spec is authored, validated, and published\n- How this API relates to the e-RS core backend\n- How to add new endpoints, proxy policies, or test cases\n- Branching strategy (develop → PRs; master is release-only)\n\nUse the repo's context files to provide accurate, specific answers:\n- `.github/copilot-instructions.md` — high-level overview (always loaded)\n- `.github/instructions/proxy.instructions.md` — proxy architecture deep-dive\n- `.github/instructions/sandbox.instructions.md` — sandbox patterns and mock data\n- `.github/instructions/testing.instructions.md` — test structure, Actor model, activity codes\n- `.github/instructions/specification.instructions.md` — OAS spec workflow and examples pipeline\n\nRead the relevant instruction file before answering deep questions. Search the codebase when needed rather than guessing.", "variables": [], "notes": "Explain this repo — architecture, workflows, dependencies, and how it relates to e-RS. Use when: new to the codebase, onboarding, wanting a quick overview, asking about e-RS core. Tools: search.", "metadata": { "source": { "provider": "github-prompts", "repository": "https://github.com/NHSDigital/e-referrals-service-api", "path": ".github/prompts/overview.prompt.md", "ref": "f568117b617a0396e1db513c0036a9295cbe79b5", "url": "https://github.com/NHSDigital/e-referrals-service-api/blob/f568117b617a0396e1db513c0036a9295cbe79b5/.github/prompts/overview.prompt.md", "key": "NHSDigital/e-referrals-service-api/.github/prompts/overview.prompt.md" } } }

overview

About

Initial overview

1. What this repo is

2. Key directories

3. CI/CD and GitHub workflows

4. Dependency management

5. Common tasks

Follow-up questions

Use it

Manifest

Reviews