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.103 only (no 8 SDK; it still builds net8.0). Runtimes 8.0.24 and 10.0.3 (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/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