> ## Documentation Index
> Fetch the complete documentation index at: https://calcs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Atlas Tube Custom Diagrams

> Deep dive into the Atlas Tube custom diagrams implementation and architecture

This document provides insights into the development and architecture of the Atlas Tube custom diagrams, serving as a case study for advanced interactive diagram implementation.

<Note>
  This documentation is based on development learnings and may be updated as the implementation evolves.
</Note>

## Repository Information

**Repository**: [custom-diagrams-library](https://github.com/ClearCalcs/custom-diagrams-library)

While named generically as "library," this repository is specifically focused on Atlas Tube diagrams and serves as the primary example of complex custom diagram implementation.

## Architecture Overview

### Diagram Type Parameter

A key innovation in the Atlas Tube implementation is the introduction of a `diagramType` parameter, which allows one compiled ES module to include multiple diagram variations.

<CodeBlock title="Diagram Type Selection">
  ```javascript theme={null}
  // Different diagram types within the same module
  {
      diagramType: "splice_atlas",     // For tube splicing diagrams
      // ... splice-specific parameters
  }

  {
      diagramType: "bracket_atlas",    // For bracket connection diagrams  
      // ... bracket-specific parameters
  }
  ```
</CodeBlock>

## Data Flow Architecture

The data flow is consistent for both `interactive` and `static` diagrams, and across all Atlas Tube diagram types:

<Accordion title="Detailed Data Flow">
  ### 1. Initialize Phase

  **File**: `src/interactive/interface.ts : initialize()`

  * Sets up basic framework
  * Does minimal work but still required

  ### 2. Client Initialize Phase

  **File**: `src/interactive/interface.ts : clientInitialize()`

  * Creates blank canvas
  * Switches to appropriate diagram type
  * **Calls**: `src/spliceAtlas/ParamsInterface.ts : defaultParams`
    * Loads default parameters for the diagram
  * **Calls**: `src/spliceAtlas/render.ts : update()`
    * Resizes canvas to fit
    * Renders elements with default parameters
    * **Calls**: `src/spliceAtlas/getTransformations.ts: getTransformations()`
      * Reformats original parameters into positioning data
      * Calculates anchor points for diagram elements
  * **Returns to**: `src/spliceAtlas/render.ts : update()`
    * Transforms the calculated elements
    * Draws text and leader lines

  ### 3. Render Phase

  **File**: `src/interactive/interface.ts : render()`

  * Clears existing canvas
  * Switches to appropriate diagram type
  * Similar steps to `clientInitialize()` but with actual sheet parameters
  * Renders final diagram with real calculation data
</Accordion>

## Component Architecture

### Shared Components

<Accordion title="Shared Component Structure">
  **SVG Extensions** (`/src/shared/svgjsExtensions/*.ts`)

  * Custom Calcs.com SVG library elements
  * Reusable across any diagram implementation
  * Defined types in `/src/svgjsExtensions.d.ts`

  **Utility Functions** (`/src/shared/utils/*.ts`)

  * Helper functions used by SVG extensions
  * Mathematical calculations and transformations
  * Data formatting and validation

  **Asset Library** (`/src/shared/assets/*.svg`)

  * Complete SVG images for diagram sub-components
  * Standardized symbols and representations
  * Material and connection detail drawings
</Accordion>

## Testing and Development

### Local Testing Setup

<Warning>
  **Critical Testing Requirements:**

  The testing environment requires both processes running simultaneously:

  1. **Development Server**: `npm start`
  2. **Test Runner**: `npm test`

  Both must be active for the tester to function properly.
</Warning>

### Testing Configuration

<CodeBlock title="Test Parameter Example">
  ```javascript theme={null}
  // When testing, you must:
  // 1. Select diagram type in dropdown
  // 2. Pass diagramType in render call parameters

  render({
      diagramType: "splice_atlas",
      tubeSize: "100x100x5",
      spliceLength: 500,
      // ... other parameters
  })
  ```
</CodeBlock>

<Note>
  It can take significant time to understand the testing setup requirements. The dual-process requirement and parameter passing are not immediately obvious from the documentation.
</Note>

## Alternative Approaches Discussion

### Current Limitations

The current implementation raises questions about whether there might be more efficient approaches:

<Accordion title="Potential Alternative Technologies">
  **Native SVG with Parameters**

  * SVG has native support for parametric variables
  * Could potentially eliminate JavaScript entirely
  * May become complex with arbitrary numbers of elements

  **Higher-Level Libraries**

  * Current implementation uses low-level SVG.js and svgdom
  * Alternative libraries like [Snap.svg](https://github.com/adobe-webplatform/Snap.svg) or Maker.js might provide better abstractions
  * Could improve development speed and maintainability

  **CAD Integration**

  * Engineers are already familiar with parametric drafting tools
  * DXF is a vector format that can convert to/from SVG
  * Might enable direct CAD-to-diagram workflows
</Accordion>

### Design Philosophy

<Note>
  **Core Question**: What are we actually doing?

  At its essence, we're creating parametric technical drawings:

  * Copying shared components into project-specific details
  * Parameterizing placement of lines and labels
  * Generating vector drawings for web display

  This is similar to existing CAD workflows that engineers already understand.
</Note>

## Implementation Best Practices

### Parameter Management

<CodeBlock title="Parameter Structure">
  ```typescript theme={null}
  interface DiagramParams {
      diagramType: string;
      // Geometric parameters
      dimensions: {
          length: number;
          width: number;
          thickness: number;
      };
      // Display parameters
      showDimensions: boolean;
      showLabels: boolean;
      // Material parameters
      material: string;
      finish: string;
  }
  ```
</CodeBlock>

### Error Handling

<CodeBlock title="Robust Error Handling">
  ```typescript theme={null}
  function validateParams(params: DiagramParams): boolean {
      // Validate required parameters
      if (!params.diagramType) {
          console.error('diagramType is required');
          return false;
      }
      
      // Validate numeric ranges
      if (params.dimensions.length <= 0) {
          console.error('Length must be positive');
          return false;
      }
      
      return true;
  }
  ```
</CodeBlock>

### Performance Optimization

<CodeBlock title="Performance Considerations">
  ```typescript theme={null}
  // Optimize rendering for complex diagrams
  function optimizedRender(elements: DiagramElement[]) {
      // Batch DOM updates
      const fragment = document.createDocumentFragment();
      
      // Render only visible elements
      const visibleElements = elements.filter(el => el.isVisible);
      
      // Use efficient SVG manipulation
      visibleElements.forEach(element => {
          const svgEl = createSVGElement(element);
          fragment.appendChild(svgEl);
      });
      
      // Single DOM update
      canvas.appendChild(fragment);
  }
  ```
</CodeBlock>

## Future Considerations

### Scalability

As more custom diagrams are developed, consider:

* **Shared Component Library**: Expand reusable components
* **Template System**: Create diagram templates for common patterns
* **Configuration Tools**: GUI tools for non-developers to create diagrams
* **Performance Monitoring**: Track rendering performance across diagram types

### Integration Improvements

* **Real-time Preview**: Live parameter updates during template editing
* **Validation Tools**: Automatic parameter validation and error reporting
* **Documentation Generation**: Auto-generate parameter documentation
* **Testing Automation**: Automated visual regression testing

<Tip>
  The Atlas Tube diagrams represent a sophisticated implementation of custom visualization. While complex, they demonstrate the power and flexibility available for specialized engineering diagrams.
</Tip>

<Warning>
  Custom diagram development requires significant JavaScript/TypeScript expertise and ongoing maintenance commitment. Evaluate complexity against business requirements before undertaking similar implementations.
</Warning>