Reorganize developer docs into devdocs/; new CLAUDE.md and .NET 10 port plan
This commit is contained in:
132
devdocs/modernization/CODEBASE-REFERENCE.md
Normal file
132
devdocs/modernization/CODEBASE-REFERENCE.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# AyaNova v8 codebase reference
|
||||
|
||||
Technical facts about the v8 code, gathered from notes written in February–March 2026.
|
||||
Version numbers are a snapshot from then: **`AyaNova.csproj` and `package.json` are the
|
||||
truth**. Anything marked **[unverified]** has not been checked against the code.
|
||||
|
||||
## Back end — `raven/server/AyaNova/`
|
||||
|
||||
### Stack (February 2026, before the .NET 10 port)
|
||||
|
||||
| Component | Version | Notes |
|
||||
|---|---|---|
|
||||
| .NET / ASP.NET Core | 8.0 | |
|
||||
| Entity Framework Core | 8.0.8 | |
|
||||
| Npgsql.EntityFrameworkCore.PostgreSQL | 8.0.4 | |
|
||||
| Microsoft.AspNetCore.Authentication.JwtBearer | 8.0.4 | Custom JWT implementation |
|
||||
| PuppeteerSharp | 17.0.0 | PDF reports through headless Chrome |
|
||||
| MailKit | 4.5.0 | Email |
|
||||
| Swashbuckle.AspNetCore | 6.5.0 | OpenAPI |
|
||||
| NLog.Web.AspNetCore | 5.3.11 | Logging |
|
||||
| Asp.Versioning.Mvc | — | API versioning **[unverified]** |
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
raven/server/AyaNova/
|
||||
├── AyaNova.csproj
|
||||
├── Program.cs, Startup.cs
|
||||
├── resource/ report templates and static resources, copied to output
|
||||
│ └── rpt/ report templates (.ayrt)
|
||||
└── wwwroot/ built front end and customer manual, copied in by the build
|
||||
```
|
||||
|
||||
Older notes also list `Controllers/`, `Models/`, `Services/` and `Data/` folders
|
||||
**[unverified]**: that list reads like a generic template, not the actual layout.
|
||||
Data-list classes live in the `AyaNova.DataList` namespace, and their class names are the
|
||||
list keys (`WorkOrderDataList`, `CustomerDataList` …).
|
||||
|
||||
### Hosted vs self-hosted
|
||||
|
||||
```xml
|
||||
<DefineConstants Condition=" '$(SUBSCRIPTION_BUILD)' == 'true' ">$(DefineConstants);SUBSCRIPTION_BUILD</DefineConstants>
|
||||
```
|
||||
|
||||
```csharp
|
||||
#if SUBSCRIPTION_BUILD
|
||||
// hosted-subscription-only code
|
||||
#endif
|
||||
```
|
||||
|
||||
### Reports
|
||||
|
||||
PuppeteerSharp renders PDFs in headless Chrome, downloaded on first run. A customer
|
||||
setting holds extra browser launch parameters, and an environment variable can point at
|
||||
an existing browser instead of downloading one (`REPORT_RENDER_BROWSER_PATH` in older
|
||||
notes **[unverified]**).
|
||||
|
||||
### Configuration
|
||||
|
||||
Older notes list `ConnectionStrings__DefaultConnection`, `JWT_SECRET` and
|
||||
`ASPNETCORE_ENVIRONMENT` as the server's settings **[unverified]**. Sockeye, the near-copy,
|
||||
reads `SOCKEYE_*` keys from a `config.json` beside the app (`SOCKEYE_DB_CONNECTION`,
|
||||
`SOCKEYE_USE_URLS`, `SOCKEYE_JWT_SECRET`, `SOCKEYE_DATA_PATH` …), so AyaNova likely does the
|
||||
same with its own prefix. The Linux packages ship a `config.json` from
|
||||
`dist/assets/linux-server/` or `dist/assets/linux-desktop/`, which supports that.
|
||||
|
||||
### API conventions
|
||||
|
||||
Confirmed by the integration tests. Base `http://localhost:7575/api/v8/`.
|
||||
|
||||
| Call | Response |
|
||||
|---|---|
|
||||
| POST | 201, `{ data: <full object> }` |
|
||||
| GET | 200, `{ data: <full object> }` |
|
||||
| DELETE | 204, no body |
|
||||
| PUT on Customer, QuoteItem, PMItem | 200, `{ data: { Concurrency: N } }` (concurrency only) |
|
||||
| PUT on Quote, PM, Contract, WorkOrder headers | 200, `{ data: <full object> }` |
|
||||
| Concurrency conflict | 409 |
|
||||
| Referential integrity violation | 400, `error.code = 2200` |
|
||||
| Not found | 404, `error.code = 2010` |
|
||||
|
||||
Saved data-list filters: `/data-list-filter` (not the older `data-list-view`); list with
|
||||
`GET /data-list-filter/list?ListKey=WorkOrderDataList`.
|
||||
|
||||
## Front end — `raven-client/ayanova/`
|
||||
|
||||
### Stack
|
||||
|
||||
| Package | Version | Notes |
|
||||
|---|---|---|
|
||||
| vue | 2.6.14 | End of life December 2023 |
|
||||
| vuetify | 2.6.6 | |
|
||||
| vue-router | 3.5.4 | |
|
||||
| vuex | 3.6.2 | plus `vuex-persistedstate` 2.7.1 |
|
||||
| @vue/cli-service | 4.5.15 | |
|
||||
| webpack | 4.46.0 | |
|
||||
| sass / sass-loader | 1.52.3 / 8.0.2 | |
|
||||
| fibers | 4.0.3 | Deprecated native addon; the reason Node is pinned |
|
||||
| monaco-editor | 0.30.1 | Large worker files |
|
||||
| others | | chart.js 2.9, luxon 1.28, marked 1.2, dompurify 2.3, jwt-decode 3.1, papaparse 5.3 |
|
||||
|
||||
Node.js **12.22.9**, pinned. Plain JavaScript, no TypeScript.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
raven-client/ayanova/
|
||||
├── src/
|
||||
│ ├── api/ API utilities, auth, error handling
|
||||
│ ├── components/ ~80 components
|
||||
│ ├── views/ ~100 page components
|
||||
│ ├── plugins/ Vuetify configuration
|
||||
│ ├── App.vue, main.js, router.js, store.js
|
||||
├── public/
|
||||
├── package.json, vue.config.js, webpack.config.js
|
||||
```
|
||||
|
||||
View prefixes: `acc-` accounting (rates, taxes), `adm-` administration, `cust-` customers,
|
||||
`home-` dashboard and user home, `inv-` inventory, `ops-` server operations, `svc-` service
|
||||
(work orders, quotes, PMs).
|
||||
|
||||
## QuickBooks integration — `ravenqbi/`
|
||||
|
||||
.NET Framework 4.8, Windows Forms, x86 only (the QuickBooks SDK is 32-bit). References
|
||||
`interop.QBFC14.dll`, which needs the QuickBooks SDK installed on the build machine.
|
||||
Visual Studio is required for the Forms designer. Not part of `build-release.bat`.
|
||||
|
||||
## Customer manual — `raven/docs/8.0/`
|
||||
|
||||
MkDocs with the Material theme, two sites: `ayanova/` (main manual) and `customer/`
|
||||
(customer portal). Each `mkdocs.yml` sets `site_dir` to build straight into the server's
|
||||
`wwwroot/docs`.
|
||||
Reference in New Issue
Block a user