103 lines
6.5 KiB
Markdown
103 lines
6.5 KiB
Markdown
# 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 |
|