admin/raven-client
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add CLAUDE.md; point README at the build docs in raven

Browse Source
This commit is contained in:
John Cardinal
2026-10-22 11:54:09 -07:00
parent ab72022c08
commit 838ce9f390
2 changed files with 61 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

271
BUILD-ENVIRONMENT.md
View File

@@ -1,271 +0,0 @@
# AyaNova v8 Build Environment Documentation
> **Purpose**: This document captures the exact build environment for AyaNova v8 as of February 2026. Use this to recreate the build environment on a new machine or in a container.
## Overview
AyaNova v8 consists of three main build components:
1. **Frontend** - Vue.js 2 application (JavaScript, not TypeScript)
2. **Documentation** - MkDocs with Material theme
3. **Backend** - ASP.NET Core 8.0 server (C#)
The frontend and docs are built first, then copied into the backend project's `wwwroot` folder before the backend is built and packaged for distribution.
---
## Current Build Machine Specifications
| Component | Version | Notes |
|-----------|---------|-------|
| Operating System | Windows 11 | ThinkPad X13 Gen 3 |
| Node.js | v12.22.9 | **End-of-life** - do not upgrade without testing |
| npm | (check with `npm -v`) | Comes with Node |
| Python | 3.11.1 | For MkDocs |
| .NET SDK | 8.0.x | For backend build |
---
## Frontend Build Environment
### Directory Structure
```
c:\data\code\
├── raven-client\
│ └── ayanova\ # Vue.js frontend project
│ ├── src\ # Source code
│ ├── public\ # Static assets
│ ├── dist\ # Build output (generated)
│ ├── package.json
│ ├── vue.config.js
│ └── buildrelease.bat
├── raven\
│ ├── server\
│ │ └── AyaNova\
│ │ └── wwwroot\ # Frontend files copied here after build
│ └── docs\
│ └── 8.0\
│ └── ayanova\ # MkDocs source
│ └── mkdocs.yml
```
### Node.js Version: Critical Information
**Current version: Node.js 12.22.9**
This project uses an old Node version because:
1. The `fibers` package (used by sass-loader for faster Sass compilation) is a native C++ addon that stopped being maintained and doesn't compile on newer Node versions
2. Various other dependencies have peer dependency requirements that break on Node 14+
**Do not upgrade Node without first testing in an isolated environment.**
### Key Dependencies
From `package.json`:
| Package | Version | Purpose |
|---------|---------|---------|
| vue | 2.6.14 | Core framework (Vue 2, end-of-life Dec 2023) |
| vuetify | 2.6.6 | UI component library |
| @vue/cli-service | 4.5.15 | Build tooling |
| webpack | 4.46.0 | Module bundler |
| sass | 1.52.3 | Sass compiler |
| fibers | 4.0.3 | **Problematic** - native addon for Sass |
| monaco-editor | 0.30.1 | Code editor component |
### Build Process
The frontend build is executed via `buildrelease.bat`:
```batch
@echo **************************************************************
@echo ******************** BUILD CLIENT ****************************
@echo **************************************************************
rmdir c:\data\code\raven\server\AyaNova\wwwroot /s/q
mkdir c:\data\code\raven\server\AyaNova\wwwroot
cd c:\data\code\raven\docs\8.0\ayanova
mkdocs build
cd c:\data\code\raven-client\ayanova
call npm run build
xcopy c:\data\code\raven-client\ayanova\dist\* C:\data\code\raven\server\AyaNova\wwwroot\ /e
pause
```
This does:
1. Clears and recreates the backend's wwwroot folder
2. Builds the MkDocs documentation (output goes directly to wwwroot/docs via mkdocs.yml config)
3. Runs `npm run build` which calls `vue-cli-service build`
4. Copies the built frontend from `dist/` to the backend's `wwwroot/`
### Known Build Warnings (Safe to Ignore)
These warnings appear during every build and do not affect the output:
1. **Browserslist warning**: "caniuse-lite is outdated"
- Harmless - just means browser compatibility database is old
2. **Dart Sass division warnings**: "Using / for division is deprecated"
- Come from Vuetify's stylesheets, not your code
- Will continue working until Dart Sass 2.0
3. **Asset size warnings**: Various files exceed 244 KiB
- Expected with Monaco editor (ts.worker.js is 4.5MB)
- Application still works correctly
### NPM Scripts
```json
{
"serve": "vue-cli-service serve", // Development server
"build": "vue-cli-service build", // Production build
"lint": "vue-cli-service lint" // Code linting
}
```
---
## Documentation Build Environment
### MkDocs Configuration
From `mkdocs.yml`:
| Setting | Value |
|---------|-------|
| Theme | Material |
| Output directory | `../../../server/AyaNova/wwwroot/docs` |
| Site URL | https://ayanova.com/docs/ |
### Required Python Packages
```bash
pip install mkdocs mkdocs-material
```
The `pymdownx` extensions (highlight, superfences) come bundled with mkdocs-material.
### Build Command
```bash
cd c:\data\code\raven\docs\8.0\ayanova
mkdocs build
```
Output goes directly to the backend's wwwroot/docs folder.
---
## Backend Build Environment
### .NET Version
- **Target Framework**: .NET 8.0
- **Project Type**: ASP.NET Core
### Build Tools Required
- .NET 8.0 SDK
- Visual Studio 2022 or VS Code with C# extension
### Build Outputs
The backend build produces multiple deployment targets:
1. Linux hosted (DigitalOcean service)
2. Windows networked (IIS hosted)
3. Windows single-user (self-contained)
4. Linux server
5. Linux desktop
Windows installers are created with Inno Setup.
---
## Recreating the Build Environment
### Option 1: Native Installation (Windows)
1. Install Node.js 12.22.9 specifically:
- Download from https://nodejs.org/dist/v12.22.9/
- Or use nvm-windows: `nvm install 12.22.9 && nvm use 12.22.9`
2. Install Python 3.11:
- Download from python.org
- Ensure it's in PATH
3. Install MkDocs:
```bash
pip install mkdocs mkdocs-material
```
4. Install .NET 8.0 SDK:
- Download from https://dotnet.microsoft.com/download
5. Clone/checkout repository from SVN
6. Install frontend dependencies:
```bash
cd c:\data\code\raven-client\ayanova
npm ci
```
Note: Use `npm ci` (not `npm install`) to install exact versions from package-lock.json
### Option 2: Docker (Recommended for Reproducibility)
See `Dockerfile.frontend` and `Dockerfile.docs` in this repository for containerized builds that don't require any local installation except Docker.
---
## Troubleshooting
### "fibers" fails to install
This native module requires:
- Python 2.7 or 3.x
- Visual Studio Build Tools (Windows) or build-essential (Linux)
- Specific Node.js version compatibility
If it fails, you can try removing it (it's optional):
1. Remove `"fibers": "^4.0.3"` from package.json
2. Remove the `fiber: require("fibers")` line from webpack.config.js
3. Run `npm install` again
The build will be slightly slower but should work.
### Node version mismatch
If you see errors about incompatible Node versions:
1. Check your Node version: `node -v`
2. It must be 12.22.9 for guaranteed compatibility
3. Use nvm to switch versions if needed
### "Module not found" errors
Try:
```bash
rm -rf node_modules
rm package-lock.json
npm install
```
---
## Future Modernization Notes
When time permits, consider:
1. **Remove fibers dependency** - It's optional and causes most build issues
2. **Upgrade to Vue 3 + Vite** - Much faster builds, better tooling, active support
3. **Migrate to TypeScript** - Better IDE support and fewer runtime errors
4. **Update Node to LTS** - Current LTS is Node 20.x
These are significant changes that should be done incrementally with thorough testing.
---
## Version History
| Date | Change |
|------|--------|
| 2026-02-01 | Initial documentation created |

61
CLAUDE.md Normal file
View File

@@ -0,0 +1,61 @@
# AyaNova v8 front end — instructions for Claude Code
Shared AyaNova context and working rules, from the server repo (the master):
@../raven/CLAUDE.md
Everything below is specific to this repo.
## What this is
The AyaNova v8 web client, in `ayanova/`. Vue 2.6, Vuetify 2.6, Vuex, Vue Router, plain
JavaScript (no TypeScript), Vue CLI 4 / webpack 4. Stack details:
`../raven/devdocs/modernization/CODEBASE-REFERENCE.md`.
## During the .NET 10 port
The port is back-end only. **No changes in this repo** unless John asks, apart from a
rebuild if the port needs one. Whether the client gets rebuilt in this pass is an open
question in `../raven/devdocs/modernization/NET10-PORT.md`.
If a port item touches the client (for example removing a package from both repos), it
goes on a `net10-port` branch here too, with its own commit.
## Constraints
- **Node.js 12.22.9 exactly.** `fibers` breaks on anything newer. Check with `node -v` before building.
- **No dependency changes**: no `npm install <package>`, no `npm update`, no version edits in `package.json`. Front-end upgrades are roadmap step F, not current work.
- Install with `npm ci` (exact versions from `package-lock.json`), never `npm install`.
- Vue 2 / Vuetify 2 are end of life. Do not upgrade them, and do not write Vue 3 style code.
- Add `data-testid` attributes to elements that Cypress tests select.
## Commands
```powershell
cd ayanova
npm ci # first time, or after package-lock.json changes
npm run serve # dev server with hot reload
npm run build # production build into dist\
npm run lint
```
## How the build reaches the server
`npm run build` writes to `ayanova\dist\`. `raven\build-release.bat` (or `buildrelease.bat`
here) copies it into `raven\server\AyaNova\wwwroot\`. The .NET build does not produce
`wwwroot`: whatever is there when the server is published is what ships.
Webpack content-hash file names (`app.<hash>.js` …) change on every build even when the
contents do not. Compare file contents, not names.
Warnings on every build that are harmless: Browserslist "caniuse-lite is outdated"; Dart
Sass division deprecation (from Vuetify); asset size (Monaco's workers).
## Code layout
`src/api/` API utilities, auth and error handling; `src/components/` about 80 components;
`src/views/` about 100 pages; `src/plugins/` Vuetify setup; `router.js`, `store.js`,
`main.js`, `App.vue`.
View prefixes: `acc-` accounting, `adm-` administration, `cust-` customers, `home-`
dashboard, `inv-` inventory, `ops-` server operations, `svc-` service (work orders, quotes,
PMs).