Skip to content

DEVELOPER.md

Latest commit

 

History

History
374 lines (270 loc) · 10.4 KB

DEVELOPER.md

File metadata and controls

374 lines (270 loc) · 10.4 KB

Developer Guide

This guide is for developers who want to modify and extend the TermNorm Excel Add-in codebase. Whether you're customizing the UI, enhancing the Python backend, or building new features, this document will get you set up.

📚 Learning Resources

Office Add-ins Development

New to Excel Add-ins? Start here:

Deployment & Distribution

🚀 Getting Started

Prerequisites

Install these tools before starting:

Set Up VS Code

1. Install VS Code Extensions:

Open VS Code and install these extensions:

  • Office Add-ins Developer Kit (msoffice.microsoft-office-add-in-debugger)
  • ESLint (for code linting)
  • Prettier (optional, for code formatting)

2. Configure the Developer Kit:

The Office Add-ins Developer Kit provides:

  • ✅ One-click debugging in Excel
  • ✅ Manifest validation
  • ✅ Built-in webpack dev server
  • ✅ Automatic sideloading

📥 Download the Source Code

Option 1: Clone with Git (Recommended)

git clone https://github.com/runfish5/TermNorm-excel.git
cd TermNorm-excel

Option 2: Download ZIP

  1. Visit: https://github.com/runfish5/TermNorm-excel
  2. Click Code → Download ZIP
  3. Extract to your desired location
  4. Open terminal in the extracted folder

🔧 Frontend Development Setup

Initial Setup

1. Install dependencies:

npm install

This installs all required packages (webpack, babel, office-addin-* tools, etc.)

2. Verify installation:

npm run validate

This checks your manifest.xml for errors.

Development Workflow

Option A: Using VS Code Office Add-ins Developer Kit (Recommended)

  1. Open the project in VS Code
  2. Press F5 or click Run → Start Debugging
  3. The Developer Kit will:
    • Start the webpack dev server (https://localhost:3000)
    • Validate the manifest
    • Sideload the add-in in Excel
    • Open Excel with your add-in loaded

Option B: Using Command Line

Start the dev server:

npm run dev-server

Then sideload manually:

npm run start              # Sideload in Excel Desktop
npm run start:web          # Sideload in Excel Online

Building for Production

The build command you use determines what the UI displays to users. Choose based on your deployment scenario:

Standard build (GitHub Pages / Development):

npm run build

Shows development paths and assumes GitHub Pages deployment.

IIS Server deployment:

# Set the deployment path to match your IIS server location
set DEPLOYMENT_PATH=C:\inetpub\wwwroot\termnorm
npm run build:iis
  • UI displays "IIS Server" deployment type
  • Shows server filesystem paths for admin access
  • Includes note about drag-and-drop for regular users

Microsoft 365 deployment:

npm run build:m365
  • UI displays "Microsoft 365" deployment type
  • Hides all filesystem paths
  • Shows drag-and-drop instructions only

Custom deployment with full control:

set DEPLOYMENT_URL=http://your-server:8080/
set DEPLOYMENT_PATH=C:\inetpub\wwwroot\termnorm
set DEPLOYMENT_TYPE=iis
npm run build

Available environment variables:

  • DEPLOYMENT_URL - Base URL for manifest (default: GitHub Pages)
  • DEPLOYMENT_TYPE - UI behavior: development, iis, or m365 (default: development)
  • DEPLOYMENT_PATH - Filesystem path shown in UI (default: build directory)

The built files will be in the dist/ folder.

Legacy deployment script (deprecated):

scripts\deployment\build-http.bat  # Use npm run build:iis instead

🐍 Backend Development Setup

Initial Setup

1. Navigate to backend directory:

cd backend-api

2. Create virtual environment:

python -m venv .venv

3. Activate virtual environment:

Windows:

.\.venv\Scripts\activate

Mac/Linux:

source .venv/bin/activate

4. Install dependencies:

pip install -r requirements.txt

5. Set environment variables:

Create a .env file in backend-api/:

GROQ_API_KEY=your_groq_api_key_here
BRAVE_SEARCH_API_KEY=your_brave_api_key_here  # Optional

Or set system environment variables:

setx GROQ_API_KEY "your_groq_api_key_here"

Development Workflow

Start the backend server:

Local development:

python -m uvicorn main:app --reload

Server runs at: http://127.0.0.1:8000

Network access (for testing on other devices):

python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Server accessible at: http://your-ip:8000

Quick start (automated setup):

# From project root
start-server-py-LLMs.bat

Testing the Backend

Health check:

curl http://127.0.0.1:8000/health

Test connection from frontend:

  • Open TermNorm task pane in Excel
  • Go to Settings tab
  • Server URL should show green status indicator

Pipeline Node Session Requirements

Only fuzzy_matching and token_matching require a session (indexed terms). All other nodes work session-free:

Node Session Notes
fuzzy_matching Yes Matches against indexed terms
token_matching Yes Token-level lookup against terms
web_search No Web research on query alone
entity_profiling No LLM profile from web content
llm_ranking No Ranks candidates via LLM
llm_only No Direct LLM prompt
cache_lookup No Cached results

Pipelines without fuzzy/token nodes skip POST /sessions entirely.

📦 Deployment

Frontend Deployment

1. Build production files for your deployment type:

For IIS Server:

set DEPLOYMENT_PATH=C:\inetpub\wwwroot\termnorm
npm run build:iis

For Microsoft 365:

npm run build:m365

For GitHub Pages or custom hosting:

set DEPLOYMENT_URL=https://your-domain.com/path/
npm run build

2. Deploy to IIS (Windows Server):

Use the PowerShell deployment commands from the Installation Guide.

3. Or deploy to any static host (GitHub Pages, Netlify, etc.):

  • Upload dist/ folder contents
  • Update manifest URLs to match your host

Important: The build command determines what users see in the UI. Use build:iis for IIS deployments to show correct filesystem paths to administrators.

Backend Deployment

1. Set up as Windows service (production):

Install NSSM:

nssm install TermNormBackend "C:\path\to\.venv\Scripts\python.exe" "-m uvicorn main:app --host 0.0.0.0 --port 8000"
nssm set TermNormBackend AppDirectory "C:\path\to\backend-api"
nssm start TermNormBackend

2. Or use Docker:

Create Dockerfile in backend-api/:

FROM python:3.9
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Build and run:

docker build -t termnorm-backend .
docker run -p 8000:8000 termnorm-backend

🔧 Optimizing Your Fork for GitHub Releases

If you fork this project, you'll face the same repository size issue: Your git repo is small (~4MB), but developers need to download ~1GB of node_modules/ for development. However, your end users should not need to download all that.

The Problem

  • Git clone downloads ~4MB (source code)
  • npm install downloads ~900MB (node_modules)
  • Total: ~1GB local directory
  • End users don't need node_modules - they only need the pre-built dist/ folder!

The Solution

This repository uses automated GitHub Release deployment packages that create lightweight deployment zips (~5-10MB) when you publish a release. These packages include only:

  • ✅ Pre-built dist/ folder
  • ✅ Python backend-api/
  • ✅ Manifest files
  • ✅ Configuration templates
  • ❌ No source code
  • ❌ No node_modules

Setup Instructions

Instead of manually configuring this, use Claude Code in VS Code to set it up for you:

  1. Open your forked project in VS Code
  2. Open Claude Code (Ctrl+L or Cmd+L)
  3. Ask: "Set up automated GitHub release deployment packages like the original TermNorm project. Create a workflow that builds the project and packages only dist/, backend-api/, and manifests into a deployment zip when I publish a release. No node_modules should be included."

Claude Code will:

  • Create the GitHub Actions workflow file
  • Set up proper packaging
  • Update your README with instructions
  • Explain how to create releases

Benefits:

  • Your end users download 5-10MB instead of cloning + npm install (~1GB)
  • Developers still have full source access
  • Automated - runs every time you publish a release
  • No manual zip creation needed

Note: The workflow already exists in .github/workflows/release-package.yml if you want to review it, but asking Claude Code ensures it's properly configured for your fork's specific needs.