MAIC Tree Builder

A React-based visual editor for managing the MAIC (Milwaukee AI Club) Learning Tree. This tool allows you to create, edit, and organize learning tree nodes, generate article content, and save/load data directly to your local maic-content repository.

Features

• Local Repository Integration — Connect directly to your local maic-content repo for seamless loading and saving
• Visual Tree Editor — Interactive React Flow canvas for viewing and editing the learning tree
• Drag-and-Drop Positioning — Freely position nodes or use auto-layout
• Node Management — Add, edit, and delete nodes with full metadata support
• Category Management — Create and organize categories with custom colors
• Article Wizard — Generate markdown articles with metadata, ready for maic-content
• Import/Export — Load from CDN or local files, export as JSON
• Dark Theme — Sleek dark interface matching MAIC branding

Getting Started

Prerequisites

• Node.js 18+
• npm or bun

Installation

# Clone the repository
git clone https://github.com/MSOE-AI-Club/maic-tree-builder.git
cd maic-tree-builder

# Install dependencies
npm install

# Start development server (includes local API server)
npm run dev

The application will be available at http://localhost:5173/.

Usage

Connecting to Your Local maic-content Repository

1. On first launch, you'll see a setup dialog prompting for your repository path
2. Enter the full path to your local maic-content folder (e.g., C:\Users\...\maic-content)
3. The app will validate the path and load tree.json automatically
4. Changes are saved directly to your local repository

Loading Tree Data

1. From Local Repo: If connected, data loads automatically from data/learning-tree/tree.json
2. From CDN: Click "Load" → "Load from CDN" to fetch the latest tree.json from maic-content
3. From File: Click "Load" → "Load from File" to import a local tree.json file

Editing Nodes

1. Select a node by clicking on it in the canvas or category panel
2. Edit properties in the right sidebar panel:
   • Name and description
   • Category assignment
   • Link URL (e.g., `/library?nav=Articles&article=...`)
   • Image path for thumbnail
   • Parent/child relationships

Adding Nodes

1. Click the + button in the toolbar
2. Fill in the node details:
   • Name (required)
   • Description
   • Category
   • Parent nodes (optional)
3. Click "Add Node" - the node will be positioned automatically

Managing Categories

1. Use the left sidebar to view all categories
2. Click the + icon to add a new category
3. Edit category colors by clicking the edit icon
4. Expand categories to see and select nodes

Creating Articles

1. Click the Article Wizard button in the toolbar
2. Step 1 - Metadata: Enter title, authors, date, summary, difficulty, and categories
3. Step 2 - Content: Write markdown content using the live editor
4. Step 3 - Preview: Review metadata.json and article content
5. Click "Generate Article" to download files

Exporting Data

• Export JSON: Downloads tree.json file
• Save: Uses File System Access API to save directly (Chrome/Edge) or downloads

Project Structure

``` maic-tree-builder/ ├── src/ │ ├── components/ │ │ ├── TreeEditor.tsx # Main React Flow canvas │ │ ├── TreeNode.tsx # Custom node component │ │ ├── NodeEditor.tsx # Node editing form │ │ ├── CategoryPanel.tsx # Category sidebar │ │ ├── Toolbar.tsx # Top action bar │ │ ├── AddNodeDialog.tsx # New node dialog │ │ └── ArticleWizard.tsx # Article generation wizard │ ├── hooks/ │ │ └── useTreeData.ts # Tree data state management │ ├── types/ │ │ └── tree.ts # TypeScript definitions │ ├── utils/ │ │ ├── colorUtils.ts # Category color schemes │ │ ├── edgeGenerator.ts # React Flow edge generation │ │ ├── positionCalculator.ts # Auto-layout algorithm │ │ └── exportUtils.ts # Export/save utilities │ ├── App.tsx # Main application │ └── main.tsx # Entry point ├── package.json └── vite.config.ts ```

Configuration

Environment Variables

Create a `.env` file to customize:

```env

Override CDN base URL (optional)

VITE_CONTENT_BASE_URL=https://msoe-ai-club.github.io/maic-content ```

Tech Stack

• React 19 with TypeScript
• @xyflow/react (React Flow v12) — Interactive node-based canvas
• Material UI v6 — Component library
• @uiw/react-md-editor — Markdown editor
• Tailwind CSS v4 — Utility styling
• Vite — Build tool

Integration with maic-content

After editing the tree:

1. Export the `tree.json` file
2. Copy to `maic-content/data/learning-tree/tree.json`
3. For new articles, copy generated files to `maic-content/articles/[category]/`
4. Commit and push changes to trigger CDN update

Git Workflow

```bash

Navigate to maic-content

cd path/to/maic-content

Copy exported tree.json

cp ~/Downloads/tree.json data/learning-tree/tree.json

For new articles

mkdir -p articles/[category]/your_article cp ~/Downloads/your_article.md articles/[category]/your_article/ cp ~/Downloads/metadata.json articles/[category]/your_article/

Commit and push

git add . git commit -m "Update learning tree" git push origin main ```

Color Reference

Available category colors:

• `red`, `orange`, `yellow`, `limegreen`, `lime`, `green`
• `teal`, `cyan`, `blue`, `indigo`, `violet`, `purple`, `pink`
• `gray`, `brown`, `beige`, `black`, `white`, `olive`

Milwaukee School of Engineering AI Club

Part of the MAIC ecosystem:

• MAIC Website
• MAIC Content CDN