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