# 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 10, C#, EF Core 10, 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 10 |
| `raven-launcher` | Windows standalone launcher | .NET 10, 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: release 8.3.1, on `main`

8.3.0 (the .NET 10 port, case 4690) was released 2026-10-29, tagged `8.3.0` in `raven`,
`raven-client` and `raven-launcher`. 8.3.1 is a patch release of fixes; new features are planned
for a later 8.4.0. Each case has its own commits on `main` (`case NNNN - …`) and, if customers
would notice it, a line under "AyaNova 8.3.1" in the changelog. Release steps:
`devdocs/build/RELEASE-PROCEDURE.md`.

`devdocs/modernization/NET10-PORT.md` is the record of 8.3.0. Its Deferred list holds candidate
cases for later releases: when one is done, mark it there with its case number in the same commit.

Sockeye went through the same port first: `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, add it to "Deferred" in `NET10-PORT.md` instead of doing it.
- Dependency changes: back-end packages only, and only with John's approval (the port that updated them all is done). 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.
- Low-level server fixes (`util`, `generator`, `ControllerHelpers`, `DataList`, startup): check whether Sockeye needs the same fix with `..\sockeye\devdocs\compare-with-raven.sh` (names mapped in `NAME-MAP.md` there), and record the answer.
- 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/SECURITY-REVIEW.md` | Whole-codebase security review in passes: scope, threat model, route map, findings, pass log. Review only, fixes become cases |
| `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 |
| `devdocs/build/RELEASE-PROCEDURE.md` | Release steps from code-complete to announcement, tagging, subscription droplet upgrades and weekly updates, version bump |
| `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 |