CloudPay Resources

1. 1
   PrerequisitesNode 20 (npm 11 keeps the lockfile unchanged), the .NET 10 SDK, and az login with access to the development Key Vault, which the API reads. dotnet-ef only if you add migrations.
2. 2
   Installnpm i at the root installs only concurrently; npm run setup runs npm ci in src/web.
3. 3
   Configure the web appCopy src/web/.env.example to src/web/.env.local, set NEXT_PUBLIC_BACKEND_URL=http://localhost:5085, and fill in the Clerk, Clover and DMS values from the team. Use the NEXT_PUBLIC_ names for the Clover domain and remote app id.
4. 4
   Run bothnpm run dev starts the web app on http://localhost:3000 and the API on http://localhost:5085 (HTTPS on 7291 with --launch-profile https). Swagger is at /swagger.

npm i && npm run setup
npm run dev                         # web :3000 + api :5085
npm run dev:web                     # or one side only: npm run dev:api

cd src/api && dotnet test CloudPayClover.slnx
cd src/web && npm run typecheck && npm test

dotnet ef migrations add <Name> --project src/CloudPayClover.Infrastructure --startup-project src/CloudPayClover.Api
dotnet ef database update      --project src/CloudPayClover.Infrastructure --startup-project src/CloudPayClover.Api

1. 1
   BranchOff development, named after the story: us/{story}/….
2. 2
   Test locallyNo pipeline runs on a PR, and the web pipeline runs no tests or lint at all. Run dotnet test and npm run typecheck && npm test yourself.
3. 3
   PR into development1 reviewer, every comment resolved, the PR template filled in. Complete it with Merge (no fast-forward).
4. 4
   Development deployMerging runs the pipeline of each app you touched (path filters on src/web and src/api) and deploys it to the development environment.
5. 5
   Release PRdevelopment into main, with 2 reviewers.
6. 6
   ApproveThe production deploy waits on the production environment until someone approves it in Azure DevOps.
7. 7
   VerifyThe API pipeline polls /health and the web pipeline checks that / does not answer 5xx. Then take a sale and send an invoice.

There are no version numbers or tags: src/web/package.json has said 0.1.0 since the first commit. Releases go by date and PR.

185 test methods in 27 classes; five theories bring it to 194 cases. Tests use EF Core's in-memory provider, so SQL Server behaviour is not exercised (the invoice-stats test only checks the generated SQL). Nothing covers the Clover OAuth exchange or the token refresh.

163 it declarations in 23 files; it.each rows bring it to about 204 cases. The Sales Terminal (PaymentInput, CloverService), the admin pages, Settings, Preferences and the route handlers other than the DMS client have no tests, and no pipeline runs the suite.

• There are two copies of payments. The Dashboard reads Clover live; the DMS pages and payment details read the API's webhook copy. A payment can show in one before the other, and webhooks arrive only where Clover is configured to send them.
• Cents and dollars. Payments amounts are cents; Invoices amounts are dollars. The invoice matcher divides by 100 before comparing.
• Invoice status is a number on the wire. New statuses were appended so that existing numbers stay put; keep it that way.
• `Settings` and `Preferences` are JSON columns without value comparers. Assign a new object, or mark the property modified, or EF Core will not save an in-place change.
• There are two token systems. The Clerk token lasts about a minute; the API's JWT lasts 60 minutes and lives in memory. Respect the refresh-and-retry code and its comments: clearing the settings cache on a recoverable 401 was a past bug.
• Settings and time-zone changes travel as DOM events (merchant-settings-changed, cloudpay-timezone-changed), not React context. Dispatch them when you change either.
• Keep the DMS hooks gated (enabled) on Reynolds and the department toggle, or they fail with not_provisioned (409).
• `CustomTable` in server-side mode expects only the current page plus totalCount. Passing the full list pages it twice.
• `proxy.ts` is the middleware in Next.js 16. Do not add a middleware.ts.
• `npm start` does not work locally: server.js exists only in the standalone build. npm run lint runs next lint, which Next.js 16 removed, so it probably fails.
• The API's git history is not here. The monorepo merge (PR 325) was squashed, so git log src/api starts on 2026-09-28. Older API history is in the read-only Clover-CloudPayService repository. git log --follow does work for src/web.
• Dead code is still in the tree: services/mockUpData, the mocks in lib/index.ts, services/pdf/GeneratePDF.ts, lib/oauth-session, several unused components, and the unused nodemailer, ssh2-sftp-client and jszip packages. Email and SMS are sent by the API only.
• `CloudPayClover.Api.http` is a template leftover (GET /weatherforecast).