raven/CLAUDE.md

# AyaNova v8 — instructions for Claude Code

Loaded in every session started in this repo, and imported by the CLAUDE.md files in
`raven-client` and `raven-test-integration`. Keep it short: detail lives in `devdocs/`.

Statements marked **[unverified]** came from older notes and have not been checked against
the code. Check one before relying on it, then fix the statement or remove the marker.

## What this is

AyaNova v8: commercial service management software (ayanova.com), sold since 1998,
built and maintained by one developer, John. It is a production product. Hosted
subscription customers and self-hosted customers on Windows and Linux run this code, and
deployed clients call its API routes.

## Repositories

Separate Git repos under `C:\data\code\`, hosted on a self-hosted Gitea. The build scripts
hardcode these paths: do not move or rename the folders.

| Folder | What | Stack |
|---|---|---|
| `raven` | **This repo, the master.** Back-end server, customer manual, build and installer scripts | ASP.NET Core 8, C#, EF Core 8, Npgsql, PostgreSQL |
| `raven-client` | Front end, in `ayanova/` | Vue 2.6, Vuetify 2.6, Vuex, Vue Router, plain JavaScript, Node 12.22.9 |
| `raven-test-integration` | API integration tests against a running server | xUnit, .NET 8 |
| `raven-launcher` | Windows standalone launcher | .NET 8, self-contained, trimmed |
| `ravenqbi` | QuickBooks Desktop integration | .NET Framework 4.8 WinForms, x86, Visual Studio only |
| `raven-test` | Cypress E2E suite in `e2e/` (Cypress 9.7.0, targets remote devtest servers); also JMeter (`load/`) and Locust (`loadlocust/`) load tests | Node, Cypress |
| `sockeye` | Internal licensing server, a near-copy of this codebase, **already ported to .NET 10** (tag `8.1.0`, baseline tag `net6-baseline`) | same as `raven` |

## Layout of this repo

- `server/AyaNova/` — the application, `AyaNova.csproj`. Publish this csproj directly, never `raven.sln`.
- `docs/` — the **customer** help manual (MkDocs). Not developer documentation. Do not edit unless asked.
- `devdocs/modernization/` and `devdocs/build/` — current developer docs. Anything else in `devdocs/` is old historical notes: ignore unless asked.
- `dist/` — packaging assets, Inno Setup scripts, build outputs.
- `build-release.bat` — master release build.

## Current work: .NET 10 port, branch `net10-port`

Move the server from .NET 8 to .NET 10 and every back-end package to its current release.
Front end: minimal or no change.

**Before any port work, read `devdocs/modernization/NET10-PORT.md`.** It holds the plan,
the checklist and the decisions still open. Update its checklist and log in the same
commit as the change they record.

Sockeye went through the same port first. When a port question comes up, look at how
Sockeye solved it: `git -C ..\sockeye log --oneline net6-baseline..8.1.0`.

The rest of the modernization plan: `devdocs/modernization/ROADMAP.md`.

## Working rules

- No change to production code without John's explicit approval. Propose a plan first for anything beyond a one-line fix.
- One concern per commit, so a regression can be found with `git log` and undone with `git revert`. The version bump is always the first commit on a release branch.
- Do not mix refactoring, bug fixes and features. If you spot something worth refactoring during the port, add it to "Deferred" in `NET10-PORT.md` instead of doing it.
- Dependency changes: back-end packages only, and only on `net10-port`. No front-end dependency changes (Node is pinned at 12.22.9 because of `fibers`).
- Do not add `[ApiController]` to controllers that lack it. It changes model binding and error responses on routes deployed clients call.
- No new features.
- Git: keep it simple and explicit. Do not push, tag, merge or rewrite history unless asked. Tags are annotated and pushed by name.
- Nothing is accepted blindly: show the diff and say why.
- Secrets and customer data never go in a repo. Fixtures that contain customer data live outside the repo and are found through an environment variable.

## Environment

- Windows 11, PowerShell, VS Code. Visual Studio only for `ravenqbi`.
- .NET SDK 10.0.402 (installed with winget) and 10.0.103 (from Visual Studio 2026); no `global.json`, so builds use the newest. No 8 SDK (the 10 SDK still builds `net8.0`). Runtimes 8.0.24, 10.0.3 and 10.0.13 (also 6.0.36).
- Local server: `http://localhost:7575`, API base `/api/v8/`.
- Compile-time constant `SUBSCRIPTION_BUILD` (`-p:SUBSCRIPTION_BUILD=true`) distinguishes the hosted build; use `#if SUBSCRIPTION_BUILD`.

## Commands

```powershell
dotnet build server\AyaNova\AyaNova.csproj
dotnet run --project server\AyaNova

# integration tests: the server must be running first
cd ..\raven-test-integration; dotnet test raven-integration.csproj

# hosted (subscription) Linux build, as build-release.bat does it
dotnet publish server\AyaNova\AyaNova.csproj -c Release -r linux-x64 --no-self-contained -p:SUBSCRIPTION_BUILD=true

# full release: docs, client, all five packages, installers
.\build-release.bat
```

## Reference (read when relevant, not every session)

| File | Covers |
|---|---|
| `devdocs/modernization/NET10-PORT.md` | The current port: plan, checklist, open questions, log |
| `devdocs/modernization/ROADMAP.md` | Modernization steps and their status |
| `devdocs/modernization/PROJECT-OVERVIEW.md` | Products, deployment targets, business context |
| `devdocs/modernization/CODEBASE-REFERENCE.md` | Stack, structure, configuration, API conventions |
| `devdocs/modernization/TESTING.md` | Test suites and their state |
| `devdocs/build/BUILD.md` | Release build, packaging, version numbers |
| `devdocs/build/DEV-VM-SETUP.md` | Deprecated build VM plan; its tool list still serves for setting up a build machine. Releases are built on the workstation |