Documents

CloudPay Documents

The written record that lives in the Clover-CloudPay repository. Paths are relative to the repository root. The agent guides (AGENTS.md) are the most complete and current; the two app READMEs are out of date.

Start here

READMEMarkdownThe monorepo: what is in src/web, src/api, pipeline/, scripts/, documentation/ and infra/, the quick start, and the branch model in brief.README.md

Agent guide: monorepoMarkdownLayout and rules of the road: run tooling from each app's folder, path-filtered pipelines, the Docker build context, branching, and how the two repositories were combined. Its claim that the API's history was kept is wrong; see Resources.AGENTS.md

Agent guide: web appMarkdownStack, App Router layout, scripts, Vitest, conventions, how the app talks to the API, Clover and the DMS, environment variables, CI and gotchas. Mostly current; a few points have drifted (it counts four baked variables where there are five, and says invoices have no tests).src/web/AGENTS.md

Agent guide: APIMarkdownSolution layout, build and test commands, test patterns, migrations, configuration, authentication, background services, CI and gotchas. Two points are stale: /health is served in every environment, and the API does now store DMS data (the invoice snapshot).src/api/AGENTS.md

Branching and deploymentMarkdownLong-lived branches, PR policies (1 reviewer into development, 2 into main), the release flow and the four pipelines. Note that editing a document inside src/web or src/api does trigger that app's pipeline.documentation/branching.md

Pull request templateMarkdownChange description, type of change, related work items, and the development and code-review checklists..azuredevops/pull_request_template.md

Product and design

Product identityMarkdownSpike A (Task #2632, 2026-08-19): "CloudPay" is the only product name (MiCloudPay is retired), blue-500 is the brand colour, and logo files are named cloudpay-{wordmark|mark}-on-{light|dark}.svg after the background they sit on. Lists the icon formats still missing.documentation/product-identity.md

Design scalesMarkdownSpike B (Task #2633, 2026-08-20): an audit of type, spacing, radius, elevation and components, with proposed tokens and a 7–9 day migration plan. A backlog, not the current state: none of it has been adopted yet.documentation/design-scales.md

Marketing materialMarkdownHow the landing-page screenshots are captured and masked (screenshots/mask.js, optimize.py), and how the 14-slide sales deck is generated with python-pptx, exported to PDF and attached to the work items.documentation/marketing/README.md

App READMEs (out of date)

Prefer the agent guides and these pages until the READMEs are rewritten.

Web app READMEMarkdownThe original frontend README. It still describes Prisma and MySQL (removed in May 2026), Next.js 15, and running on the same Wi-Fi as the terminal.src/web/README.md

API READMEMarkdownA short product summary. It says ASP.NET Core 8 and Next.js 15 (the code is on .NET 10 and Next.js 16), presents Redis as part of the stack (it is optional), and has no run instructions.src/api/README.md

Infrastructure and pipelines

Azure Pipelines and the manual fallbacks. The API pipelines run the xUnit tests; the web pipelines only type-check, inside the Docker build.

Infrastructure inventoryMarkdownThe Azure resources, Azure DevOps pipelines, environments, variable groups and service connections for each environment. There is no infrastructure-as-code yet, so this page is the source of truth. It names internal resources, so it stays in the repository.infra/README.md

API pipeline templateYAMLRestores, builds and tests src/api with the .NET 10 SDK on a Windows agent, publishes the API as a zip, deploys it to App Service, then polls /health (6 tries, 15 seconds apart).pipeline/templates/api-build-deploy.yml

API development pipelineYAMLRuns on development for changes under src/api, and deploys to the development App Service with no approval.pipeline/api/dev.yml

API production pipelineYAMLRuns on main, and deploys to production after approval on the production environment.pipeline/api/prod.yml

Web pipeline templateYAMLBuilds the Docker image from src/web with the five NEXT_PUBLIC_* build arguments, pushes {env}-{buildId} and {env}-latest, points the container app at the new build tag, then checks that / does not answer 5xx.pipeline/templates/web-build-deploy.yml

Web development pipelineYAMLRuns on development for changes under src/web. Uses the development variable group and registry; no approval.pipeline/web/dev.yml

Web production pipelineYAMLRuns on main. Uses the production variable group and the shared production registry, and waits for approval.pipeline/web/prod.yml

Manual web deploy: developmentPowerShellPoints the development container app at an existing image tag. Its default tag, latest, is not one the pipeline pushes; pass -Tag dev-latest.scripts/deploy-web-dev.ps1

Manual web deploy: productionPowerShellThe production equivalent (default tag prod-latest), with the subscription as a parameter. Needs Contributor on the production resource group.scripts/deploy-web-prod.ps1

Sales deck: export to PDFPowerShellConverts the generated deck to PDF through PowerPoint, which must be installed.documentation/marketing/sales-deck/export-pdf.ps1

Sales deck: attach to work itemsPowerShellUploads the deck and its PDF to Azure DevOps work items (US 2922, Task 2924) with the signed-in az account.documentation/marketing/sales-deck/attach-to-ado.ps1

Work items

Commits and PRs reference Azure DevOps work items (US 2922, Task #2774, Bug 2617) in the Clover-CloudPay project. PR numbers are shared across the organisation, so they are not consecutive.