raven/BACKEND-BUILD-ENVIRONMENT.md

# AyaNova v8 Backend Build Environment Documentation

> **Purpose**: This document captures the complete backend build process for AyaNova v8, including all deployment targets and installers.

## Overview

The backend build produces **6 deployment packages** from **3 projects**:

### Projects

| Project | Framework | Purpose |
|---------|-----------|---------|
| AyaNova (server) | .NET 8.0 | Main ASP.NET Core web server |
| raven-launcher | .NET 8.0 | Windows launcher for standalone mode |
| AyaNovaQBI | .NET Framework 4.8 | QuickBooks Desktop integration (separate build) |

### Deployment Targets

| Target | Description | Output |
|--------|-------------|--------|
| Subscription Linux x64 | Your hosted service (DigitalOcean) | `ayanova-subscription-linux-x64-server.zip` |
| Perpetual Linux Server | Self-hosted Linux server | `ayanova-linux-x64-server.zip` |
| Perpetual Linux Desktop | Single-user Linux desktop | `ayanova-linux-x64-desktop.zip` |
| Windows Standalone | Self-contained single-user (includes .NET runtime + PostgreSQL) | `ayanova-windows-x64-single-setup.exe` |
| Windows LAN | Network server (requires separate .NET + PostgreSQL) | `ayanova-windows-x64-lan-setup.exe` |
| QuickBooks Integration | Windows desktop app | `ayanova-qbi-setup.exe` (separate build) |

---

## Directory Structure

```
c:\data\code\
├── raven\                              # Main repository root
│   ├── build-release.bat               # Master build script
│   ├── raven.sln                       # Visual Studio solution
│   ├── server\
│   │   └── AyaNova\                    # ASP.NET Core server project
│   │       ├── AyaNova.csproj
│   │       ├── Program.cs
│   │       ├── Startup.cs
│   │       ├── wwwroot\                # Frontend files copied here
│   │       └── resource\               # Report templates, etc.
│   ├── docs\
│   │   └── 8.0\
│   │       ├── ayanova\                # Main documentation (MkDocs)
│   │       │   └── mkdocs.yml
│   │       └── customer\               # Customer portal documentation
│   │           └── mkdocs.yml
│   ├── dist\
│   │   ├── assets\                     # Shared assets (license, configs, icons)
│   │   │   ├── LICENSE
│   │   │   ├── license.rtf
│   │   │   ├── linux-desktop\config.json
│   │   │   ├── linux-server\config.json
│   │   │   ├── lan-install-config.json
│   │   │   └── logo.ico
│   │   ├── install\
│   │   │   └── windows\x64\            # Inno Setup scripts
│   │   │       ├── standalone.iss
│   │   │       └── lan.iss
│   │   ├── installers\                 # Build output (generated)
│   │   ├── linux-x64\                  # Linux build output (generated)
│   │   ├── subscription-build-linux-x64\  # Subscription build output (generated)
│   │   └── win-x64\                    # Windows build output (generated)
│   │       ├── ayanova\
│   │       │   ├── standalone\         # Self-contained build
│   │       │   └── framework-dependent\ # Requires .NET installed
│   │       ├── launcher\               # Launcher build output
│   │       └── postgres-standalone\    # Embedded PostgreSQL for standalone
│   └── graphics\                       # Icons, logos
│
├── raven-client\                       # Frontend (separate repo/folder)
│   └── ayanova\
│
├── raven-launcher\                     # Launcher project
│   ├── raven-launcher.csproj
│   └── config.json
│
└── ravenqbi\                           # QuickBooks integration (separate)
    ├── AyaNovaQBI\
    │   └── AyaNovaQBI.csproj
    └── install\
        └── qbi.iss
```

---

## Build Requirements

### Software

| Tool | Version | Purpose |
|------|---------|---------|
| .NET SDK | 8.0.x | Build ASP.NET Core projects |
| Node.js | 12.22.9 | Build frontend (see frontend docs) |
| Python | 3.11.x | Build MkDocs documentation |
| MkDocs | Latest | Documentation generator |
| Inno Setup | 6.x | Windows installer creation |
| 7-Zip | Latest | Create Linux distribution zips |
| Visual Studio 2022 | Latest | Build QBI project (.NET Framework 4.8) |

### Paths (hardcoded in build scripts)

The build scripts expect these exact paths:
- `C:\data\code\raven\` - Main repository
- `C:\data\code\raven-client\ayanova\` - Frontend project
- `C:\data\code\raven-launcher\` - Launcher project
- `C:\data\code\ravenqbi\` - QuickBooks integration
- `C:\Program Files\7-Zip\7z.exe` - 7-Zip
- `C:\Program Files (x86)\Inno Setup 6\ISCC.exe` - Inno Setup compiler

---

## Build Process (build-release.bat)

The master build script executes in this order:

### 1. Clean Output Folders
```batch
rmdir c:\data\code\raven\server\AyaNova\wwwroot /s/q
mkdir c:\data\code\raven\server\AyaNova\wwwroot
rmdir C:\data\code\raven\dist\installers /s/q
mkdir C:\data\code\raven\dist\installers
```

### 2. Build Documentation (MkDocs)
```batch
cd c:\data\code\raven\docs\8.0\ayanova
mkdocs build

cd c:\data\code\raven\docs\8.0\customer
mkdocs build
```
Output goes to `wwwroot/docs` (configured in mkdocs.yml).

### 3. Build Frontend (Vue.js)
```batch
cd c:\data\code\raven-client\ayanova
call npm run build
xcopy dist\* ..\raven\server\AyaNova\wwwroot\ /e
```

### 4. Build Subscription Linux x64
```batch
dotnet publish --property:PublishDir=C:\data\code\raven\dist\subscription-build-linux-x64\ \
    -c Release -r linux-x64 --no-self-contained -p:SUBSCRIPTION_BUILD=true
```
Key flag: `-p:SUBSCRIPTION_BUILD=true` sets a compile-time constant for subscription-specific features.

Then packages to zip with config:
```batch
7z a ayanova-subscription-linux-x64-server.zip subscription-build-linux-x64\*
7z a ayanova-subscription-linux-x64-server.zip assets\linux-server\config.json
```

### 5. Build Perpetual Linux x64
```batch
dotnet publish --property:PublishDir=C:\data\code\raven\dist\linux-x64\ \
    -c Release -r linux-x64 --no-self-contained -p:SUBSCRIPTION_BUILD=false
```

Creates two packages (same build, different config):
- `ayanova-linux-x64-desktop.zip` (with desktop config)
- `ayanova-linux-x64-server.zip` (with server config)

### 6. Build Windows Standalone (Self-Contained)
```batch
dotnet publish -c Release --property:PublishDir=C:\data\code\raven\dist\win-x64\ayanova\standalone\ \
    -r win-x64 --self-contained
```
This includes the .NET runtime in the output (~150MB larger).

### 7. Build Windows Framework-Dependent
```batch
dotnet publish -c Release --property:PublishDir=C:\data\code\raven\dist\win-x64\ayanova\framework-dependent\ \
    -r win-x64 --no-self-contained
```
Requires .NET 8 runtime installed on target machine.

### 8. Build Launcher
```batch
cd C:\data\code\raven-launcher\
dotnet publish -c Release --property:PublishDir=C:\data\code\raven\dist\win-x64\launcher\ \
    -r win-x64 --self-contained
```
The launcher is always self-contained (uses `PublishTrimmed` to reduce size).

### 9. Create Windows Installers (Inno Setup)
```batch
ISCC.exe standalone.iss
ISCC.exe lan.iss
```

---

## Project-Specific Notes

### AyaNova Server (AyaNova.csproj)

**Conditional Compilation:**
```xml
<DefineConstants Condition=" '$(SUBSCRIPTION_BUILD)' == 'true' ">$(DefineConstants);SUBSCRIPTION_BUILD</DefineConstants>
```
Use `#if SUBSCRIPTION_BUILD` in code for subscription-only features.

**Key Dependencies:**
- Entity Framework Core 8.0 with Npgsql (PostgreSQL)
- PuppeteerSharp for PDF report generation (downloads Chromium on first run)
- MailKit for email
- JWT authentication

**Resource Files:**
Report templates and other resources are copied to output:
```xml
<Content Include=".\resource\*.*">
  <CopyToOutputDirectory>Always</CopyToOutputDirectory>
</Content>
```

### Launcher (raven-launcher.csproj)

Simple console app that:
1. Starts embedded PostgreSQL (standalone mode only)
2. Starts the AyaNova server
3. Opens default browser to the login page
4. Waits for user to close

Uses `PublishTrimmed` to reduce self-contained size.

### QuickBooks Integration (AyaNovaQBI.csproj)

**Important:** This is a .NET Framework 4.8 Windows Forms application, NOT .NET Core.

- Requires Visual Studio 2022 (not VS Code) for the Windows Forms designer
- References `interop.QBFC14.dll` from QuickBooks SDK (must be installed)
- Targets x86 (32-bit) because QuickBooks SDK is 32-bit only
- Has a pre-build event that runs a timestamp utility

**Why Visual Studio is required:**
The Windows Forms designer only works in Visual Studio. The code could theoretically be edited in VS Code, but the designer is essential for the UI work.

---

## Windows Installer Details

### Standalone (standalone.iss)

Includes:
- Self-contained AyaNova server (with .NET runtime)
- Self-contained launcher
- Embedded PostgreSQL (`postgres-standalone` folder)
- Empty database template

Creates desktop shortcut to launcher. User clicks one icon, everything starts.

**Key paths:**
- App: `{autopf}\ayanova`
- Data: `{commonappdata}\ayanova\database`
- Logs: `{commonappdata}\ayanova\logs`

### LAN (lan.iss)

Includes:
- Framework-dependent AyaNova server (no .NET runtime)
- Config file for network mode

Does NOT include PostgreSQL - user must install separately.

Prompts user to download:
- ASP.NET Core Runtime Hosting Bundle
- PostgreSQL

---

## Embedded PostgreSQL (Windows Standalone)

The standalone installer includes a portable PostgreSQL in `dist\win-x64\postgres-standalone\`.

This is a pre-configured PostgreSQL installation that:
- Runs without system installation
- Stores data in `{commonappdata}\ayanova\database`
- Is started/stopped by the launcher

**Source:** You'll need to maintain this - it's a copy of a PostgreSQL Windows binary distribution with a pre-initialized data directory.

---

## QuickBooks Integration Build (Separate)

The QBI is built separately and not included in the main build script.

```batch
cd c:\data\code\ravenqbi\AyaNovaQBI
msbuild /p:Configuration=Release

cd c:\data\code\ravenqbi\install
"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" qbi.iss
```

Output: `c:\data\code\ravenqbi\install\output\ayanova-qbi-setup.exe`

---

## Version Management

Versions must be updated in multiple places:

| File | Location |
|------|----------|
| `AyaNova.csproj` | `<Version>8.2.4</Version>` |
| `standalone.iss` | `#define MyAppVersion "8.2.4"` |
| `lan.iss` | `#define MyAppVersion "8.2.4"` |
| `qbi.iss` | `#define MyAppVersion "8.0.2"` |
| `package.json` (frontend) | `"version": "8.2.4"` |

Consider creating a version file or script to update all at once.

---

## Containerization Considerations

### What CAN be containerized (for build):

1. **Frontend build** - Already done (Dockerfile.frontend)
2. **Documentation build** - Already done (Dockerfile.docs)
3. **Linux server builds** - .NET SDK in Docker can cross-compile for Linux
4. **Windows framework-dependent build** - Can be built in Docker

### What CANNOT be easily containerized:

1. **Windows self-contained builds** - Need Windows container or Windows host
2. **Inno Setup installers** - Windows-only tool
3. **QuickBooks Integration** - .NET Framework 4.8, Windows Forms, requires Visual Studio
4. **Embedded PostgreSQL** - Windows-specific binaries

### Recommendation:

For a VPS-based build:
- Use Docker/Linux for: Frontend, Docs, Linux targets
- Keep Windows laptop for: Windows installers, QBI
- Or: Use a Windows VM/GitHub Actions for Windows builds

---

## Troubleshooting

### "PuppeteerSharp failed to download Chromium"

The server downloads Chromium on first run for PDF generation. If this fails:
1. Check internet connectivity
2. Check firewall/proxy settings
3. Pre-download Chrome and set `REPORT_RENDER_BROWSER_PATH` environment variable

### "SUBSCRIPTION_BUILD not defined"

Ensure you're passing the flag correctly:
```batch
dotnet publish ... -p:SUBSCRIPTION_BUILD=true
```

### Inno Setup errors

- Ensure all source paths exist
- Check that previous build steps completed
- Verify 7-Zip and Inno Setup are installed at expected paths

---

## Version History

| Date | Change |
|------|--------|
| 2026-02-01 | Initial documentation created |