GitHub to Calcs Builder Workflow for Diagrams

Custom diagrams are developed in separate GitHub repositories, compiled locally, and then uploaded to the Calcs.com template builder. This workflow allows for sophisticated diagram development using modern web technologies.

Overview

The workflow involves:

Development: Code diagrams in TypeScript/JavaScript
Compilation: Build diagrams into deployable assets
Upload: Deploy compiled files to template builder
Integration: Use diagrams in Calcs.com templates

System Requirements

Prerequisites (macOS):

Homebrew package manager
Node.js and npm
Git
Code editor (VS Code recommended)

For Windows users, the process may differ slightly.

First Time Setup

1. Install Development Tools

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install npm via Homebrew
brew install npm

2. Clone Repository

# Clone the specific diagram repository
git clone https://github.com/ClearCalcs/[repository-name]

# Navigate to repository
cd [repository-name]

# Pull latest changes
git pull

3. Navigate to Diagram Folder

# Navigate to the appropriate folder:
cd /static      # For static diagrams
# OR
cd /interactive # For interactive diagrams

# For repositories with multiple diagrams:
cd solar/static              # Example: MAFI solar diagrams
cd bracket-checker/static    # Example: MAFI bracket diagrams

4. Install Dependencies

# Install required packages
npm install

You must run npm install in each diagram folder if the repository contains multiple diagrams.

Regular Development Workflow

1. Update Repository

# Ensure you're in the correct repository
pwd

# Pull latest changes
git pull

2. Install Dependencies (if needed)

# Navigate to diagram folder
cd /static  # or /interactive

# Update packages
npm install

3. Compile Diagram

# Compile the diagram
npm run-script compile

4. Locate Output Files

After compilation, you’ll find the built files:

Output File Locations

For Static Diagrams:

Location: /dist/compiled.js
File type: JavaScript module
Usage: Upload to template builder

For Interactive Diagrams:

Location: output/index.html
File type: HTML with embedded JavaScript
Usage: Upload to template builder

If Both Types:

Both files may need to be uploaded if modifications were made to each

5. Upload to Template Builder

# Files to upload:
# - Static: dist/compiled.js
# - Interactive: output/index.html

# Upload process:
# 1. Open Calcs.com template builder
# 2. Navigate to diagram widget
# 3. Upload the compiled file(s)
# 4. Update calculator

Repository Structure Examples

Single Diagram Repository

diagram-repo/
├── src/
│   ├── static/
│   │   ├── render.ts
│   │   └── package.json
│   └── interactive/
│       ├── interface.ts
│       └── package.json
├── dist/
└── output/

Multi-Diagram Repository

mafi-diagrams/
├── solar/
│   ├── static/
│   │   ├── package.json
│   │   └── src/
│   └── interactive/
│       ├── package.json
│       └── src/
├── bracket-checker/
│   ├── static/
│   │   ├── package.json
│   │   └── src/
│   └── interactive/
│       ├── package.json
│       └── src/
└── shared/
    └── components/

Development Best Practices

Version Control

# Always start with latest code
git pull

# Create feature branches for major changes
git checkout -b feature/new-diagram-type

# Commit regularly with descriptive messages
git commit -m "Add parameter validation for tube dimensions"

# Push changes for review
git push origin feature/new-diagram-type

Testing Workflow

Local Testing: Use npm test during development
Integration Testing: Upload to development template
User Testing: Test with real calculation scenarios
Production Deployment: Upload to live templates

Dependency Management

# Check for outdated packages
npm outdated

# Update specific package
npm update [package-name]

# Install new dependency
npm install [package-name] --save

Troubleshooting

Common Issues

Compilation Errors

Issue: npm run-script compile failsSolutions:

Ensure npm install was run successfully
Check for TypeScript/JavaScript syntax errors
Verify all required dependencies are installed
Check Node.js version compatibility

Upload Issues

Issue: Compiled file doesn’t work in template builderSolutions:

Verify correct file was uploaded (compiled.js or index.html)
Check file size limits
Ensure diagram parameters match template expectations
Test with minimal parameter set first

Debug Mode

# Run compilation with verbose output
npm run-script compile --verbose

# Check for detailed error messages
npm run-script compile 2>&1 | tee compile.log

Video Tutorial

For a complete visual walkthrough of this workflow:

📹 Watch the complete tutorial: GitHub to Calcs Builder WorkflowThis video covers the entire process from repository setup to template deployment.

Next Steps

After successfully compiling and uploading your diagram:

Test Integration: Verify the diagram works in a test template
Parameter Validation: Ensure all parameters are handled correctly
Documentation: Update template documentation
User Testing: Get feedback from intended users
Production Deployment: Release to live templates

Keep a local development environment set up for quick iterations. The compilation and upload process becomes much faster with practice.

Always test compiled diagrams thoroughly before uploading to production templates. Diagram errors can break template functionality for end users.

GitHub workflow diagrams

GitHub workflow diagrams provide a streamlined approach to creating and managing interactive diagrams within Calcs.com templates.

Overview

GitHub workflow diagrams enable:

Version-controlled diagram development
Collaborative diagram editing
Automated diagram updates
Integration with CI/CD pipelines
Standardized diagram workflows

Workflow Process

1. Diagram Creation

Create diagrams using standard tools (draw.io, etc.)
Store diagram source files in GitHub repository
Use consistent naming conventions
Include metadata and documentation

2. Version Control

Commit diagram changes to Git
Use descriptive commit messages
Tag releases for stable versions
Maintain diagram history

3. Integration

Automated diagram processing
Template integration
Real-time updates
Quality assurance checks

Best Practices

Use consistent file formats (SVG, PNG)
Maintain diagram source files
Document diagram purpose and usage
Regular review and updates
Automated testing and validation

Implementation

This section will be expanded with specific implementation details and examples.

Ensure proper version control practices when working with diagram files to maintain consistency across templates.

​Overview

​System Requirements

​First Time Setup

​1. Install Development Tools

​2. Clone Repository

​3. Navigate to Diagram Folder

​4. Install Dependencies

​Regular Development Workflow

​1. Update Repository

​2. Install Dependencies (if needed)

​3. Compile Diagram

​4. Locate Output Files

​5. Upload to Template Builder

​Repository Structure Examples

​Single Diagram Repository

​Multi-Diagram Repository

​Development Best Practices

​Version Control

​Testing Workflow

​Dependency Management

​Troubleshooting

​Common Issues

​Debug Mode

​Video Tutorial

​Next Steps

​GitHub workflow diagrams

​Overview

​Workflow Process

​1. Diagram Creation

​2. Version Control

​3. Integration

​Best Practices

​Implementation

Overview

System Requirements

First Time Setup

1. Install Development Tools

2. Clone Repository

3. Navigate to Diagram Folder

4. Install Dependencies

Regular Development Workflow

1. Update Repository

2. Install Dependencies (if needed)

3. Compile Diagram

4. Locate Output Files

5. Upload to Template Builder

Repository Structure Examples

Single Diagram Repository

Multi-Diagram Repository

Development Best Practices

Version Control

Testing Workflow

Dependency Management

Troubleshooting

Common Issues

Debug Mode

Video Tutorial

Next Steps

GitHub workflow diagrams

Overview

Workflow Process

1. Diagram Creation

2. Version Control

3. Integration

Best Practices

Implementation