developer-setup.md

WE Developer Setup Guide

This guide explains how to set up the WE workspace for development or production builds.

Prerequisites

• Node.js 18+
• pnpm (npm install -g pnpm)
• Rust and Cargo (for AD4M and Tauri)
• Yarn (for Flux)

Quick Start

1. Clone Repositories

# Clone all required repositories
git clone https://github.com/your-org/we.git
git clone https://github.com/your-org/flux.git
git clone https://github.com/your-org/ad4m.git

# Your directory structure should look like:
# Coding/
#   ├── we/
#   ├── flux/
#   └── ad4m/

2. Build External Dependencies

# Build AD4M executor (required for Electron and Tauri)
cd ad4m
cargo build --release
# This creates: target/release/ad4m-executor (~350MB)

# Build Flux app (required for all platforms)
cd ../flux/app
yarn install
yarn build
# This creates: dist/ folder with built app

3. Configure WE Seed File

cd ../../we
nano we-seed.json  # Or use your favorite editor

Edit the paths in we-seed.json:

{
  "ad4m": {
    "repoPath": "../ad4m", // Path to AD4M repo
    "executorPath": "../ad4m/target/release/ad4m-executor"
  },
  "apps": [
    {
      "id": "flux",
      "paths": {
        "projectRoot": "../flux/app",
        "dist": "../flux/app/dist" // Path to built Flux app
      }
    }
  ]
}

Note: All paths are relative to the we/ directory.

4. Run Setup

# From the we/ directory
pnpm setup

This single command:

• ✅ Installs all dependencies
• ✅ Validates your seed configuration
• ✅ Checks external dependencies exist
• ✅ Builds all internal WE packages
• ✅ Generates platform-specific configurations

5. Start Developing!

# Choose your platform:
pnpm dev:web       # Web development server
pnpm dev:electron  # Electron development mode
pnpm dev:tauri     # Tauri development mode

Build for Production

# Build specific platform
pnpm build:web
pnpm build:electron  # Creates AppImage in apps/we-electron/release/
pnpm build:tauri     # Creates AppImage in apps/we-tauri/src-tauri/target/release/bundle/

# Or build everything
pnpm build:all

Available Commands

Root Commands (run from we/ directory)

Command	Description
pnpm setup	Complete workspace setup (run after clone or seed changes)
pnpm validate	Validate seed file configuration
pnpm dev	Start web dev (same as dev:web)
pnpm dev:web	Start web development server
pnpm dev:electron	Start Electron in dev mode
pnpm dev:tauri	Start Tauri in dev mode
pnpm build	Build all packages
pnpm build:web	Build web distribution
pnpm build:electron	Build Electron AppImage
pnpm build:tauri	Build Tauri AppImage
pnpm build:all	Build all distributions

Per-App Commands

You can also run commands directly from each app directory:

# Web
cd apps/we-web
pnpm dev
pnpm build

# Electron
cd apps/we-electron
pnpm electron:dev
pnpm electron:build

# Tauri
cd apps/we-tauri
pnpm tauri:dev
pnpm tauri:build

Architecture

Single Source of Truth

The we-seed.json file is the single source of truth for all configuration:

• App definitions (name, routes, paths)
• Port assignments
• AD4M paths
• Build resources

All platform-specific files are auto-generated from this seed file:

Electron:

• apps/we-electron/electron/seed-servers.js
• apps/we-electron/electron/seed-port-map.json
• apps/we-electron/electron/seed-extra-resources.json
• apps/we-electron/electron-builder.config.js

Tauri:

• apps/we-tauri/src-tauri/Cargo.toml (from template)
• apps/we-tauri/src-tauri/src/generated/seed_servers.rs
• apps/we-tauri/src-tauri/src/generated/seed-port-map.json
• apps/we-tauri/src/generated/seed-port-map.json

Never edit generated files directly - they are overwritten on every build.

Troubleshooting

"AD4M executor not found"

Build AD4M first:

cd ad4m
cargo build --release

"Flux dist not found"

Build Flux first:

cd flux/app
yarn install
yarn build

"Cargo.toml not found" (Tauri)

Run the generator:

cd apps/we-tauri
node scripts/generate-seed-config.cjs

Or just run pnpm setup from the root.

Validation Errors

Check your paths:

pnpm validate

This will show exactly what's missing or incorrect.

Project Structure

we/
├── we-seed.json                  # Single source of truth
├── package.json                  # Root orchestrator
├── scripts/
│   ├── setup-workspace.cjs       # Setup automation
│   └── validate-seed.cjs         # Validation tool
├── packages/
│   ├── app-framework/            # Core framework
│   └── cli/                      # Build tooling
└── apps/
    ├── we-web/                   # Web app
    ├── we-electron/              # Electron app
    │   ├── electron/
    │   └── scripts/
    │       └── generate-seed-config.cjs
    └── we-tauri/                 # Tauri app
        ├── src-tauri/
        │   ├── Cargo.toml.template
        │   └── src/generated/    # Auto-generated (gitignored)
        └── scripts/
            └── generate-seed-config.cjs

Development Workflow

1. Initial Setup (once):

   # Build external deps
   cd ad4m && cargo build --release
   cd ../flux/app && yarn install && yarn build
   
   # Setup WE
   cd ../../we
   pnpm install
   nano we-seed.json  # Configure paths
   pnpm setup

2. Daily Development:

   cd we
   pnpm dev:tauri  # or electron, or web

3. After Pulling Changes:

   pnpm install  # Update dependencies
   pnpm setup    # Regenerate configs

4. After Changing Seed File:

   pnpm setup    # Regenerate all configs

Tips

• Web development doesn't require AD4M or Flux to be built
• Electron and Tauri need both AD4M executor and app dist folders
• Run pnpm validate to check if everything is configured correctly
• Run pnpm setup after any seed file changes
• All paths in seed file are relative to the we/ directory

Advanced Configuration

Launcher UI Customization

You can fully customize the launcher shell (boot screen, app settings) via the seed file. See Launcher UI Customization for detailed documentation and examples.

Seed System

For complete details about the seed system architecture, app modes, and configuration options, see Seed System.

Support

For issues or questions, please open an issue on GitHub.