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 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.0, on main

The .NET 10 port (case 4690) is merged into main in raven, raven-client, raven-launcher and raven-test-integration (2026-10-23), not yet tagged or released. Before release: the "next release" cases, each with its own case number and its own commits on main (case NNNN - …); then the final build, the final gate, Cypress on the devtestn10 droplet, the 8.3.0 tag and the rollout.

Read devdocs/modernization/NET10-PORT.md first. It holds the release checklist (section 5), the Deferred list (including the cases chosen for this release) and the log. Update its checklist and log in the same commit as the change they record.

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.
• 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

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, 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