Schematics

Schematics are interactive relationship diagrams that capture how assets connect to each other — not just where they are on the map. Use them to model electrical circuits, fiber splice paths, conduit fill, wastewater flow stages, or any other logical relationship that is difficult to see in a geographic view alone. Schematics are version-controlled and can be linked directly to map features.

What Are Schematics?

Schematics vs. Map Features:

Map Features show where things are (spatial relationships, geography)
Schematics show how things connect (logical relationships, dependencies)

Use Cases:

Utility Networks

Model electrical circuits (poles → transformers → service points)
Show cable routes through conduits
Visualize capacity flows through network segments

Process Flows

Wastewater treatment plant stages
Manufacturing process dependencies
Supply chain routing

Organizational Hierarchies

Equipment maintenance dependencies
Asset ownership chains
Service delivery paths

Physical Connections

Fiber optic splicing diagrams
Plumbing network topology
HVAC duct connections

Schematic Editor Interface

The Schematic Editor appears in a popout window from the map page toolbar. It provides a full-featured diagram editor with automatic layout algorithms and manual positioning.

Main Components

Diagram Canvas (center)

Interactive node-and-edge visualization
Drag nodes to reposition manually
Click elements to select and edit
Drop zone for adding features from map

Toolbar (bottom)

Add Node - Create diagram nodes (custom or linked to map features)
Add Edge - Create connections between nodes
Layout Selector - Choose automatic layout algorithm
Auto Layout - Apply selected layout to clear all manual positions
Refresh - Reinitialize diagram from data

Element Editor (bottom panel)

Edit selected node or edge properties
Code editor for advanced JSON manipulation
Visual form for common properties
Delete with confirmation (undoable via versions)

Metadata Panel (top)

Schematic name (editable inline)
Custom properties (key-value pairs)
Version management integration

Creating Schematics

Step 1: Create a Schematic

Open map page (https://demo.aptli.io/map)
Click Map Toolbar → Schematics button
Schematic Editor opens in popout window
Empty diagram canvas appears

Step 2: Add Nodes

Option A: Custom Nodes (not linked to map)

Click Add Node button
Select Custom mode (default)
Enter node name (e.g., "Transformer A")
Choose geometry type: Point, LineString, or Polygon
Click Confirm

Option B: From Existing Map Features

Click Add Node button
Switch to From Feature mode
Select feature from dropdown (shows all map features)
Click Confirm (node links to feature via featureId)

Option C: Drag from Map

Find feature card in map interface
Drag feature card to Schematic Editor
Drop on canvas (inside dashed border area)
Node created automatically with geometry type detected

Step 3: Add Connections (Edges)

Click Add Edge button
Select Source node from dropdown
Select Target node from dropdown
Optionally enter edge label (e.g., "feeds", "capacity: 100A")
Click Confirm

Multiple Edges:

Same two nodes can have multiple edges (no limit)
Useful for bidirectional flows or different relationship types
Example: Node A → Node B (supply), Node B → Node A (return)

Step 4: Arrange Layout

Automatic Layouts (from dropdown):

Grid 2×2, 3×3, 4×4, 5×5 - Fixed grid arrangements
Circle - Nodes arranged in circle
Breadth First - Hierarchical tree layout (directed graphs)
Concentric - Rings based on connectivity
Random - Scatter nodes randomly

Manual Positioning:

Select layout preset or skip
Drag individual nodes to desired positions
Manual positions saved in version data
Manual positions take priority over layout algorithms

Reset Layout:

Click Auto Layout button → clears all manual positions
Reapplies selected layout algorithm from dropdown

Step 5: Edit Elements

Select Element:

Click any node or edge on canvas
Element Editor panel shows at bottom

Edit Node Properties:

Name - Display label (inline edit or code editor)
Geometry Type - Point, LineString, or Polygon
Feature Link - featureId connecting to map feature
Custom Properties - Add any key-value data

Edit Edge Properties:

Label - Connection description
Source - Starting node (change via code editor)
Target - Ending node (change via code editor)

Code Editor (Advanced):

Click Show Code in Element Editor
JSON representation appears in textarea
Edit directly (full element structure)
Click Format JSON to pretty-print
Click Apply Changes (validates with Zod schema)
Validation errors shown if invalid structure

Delete Element:

Select element
Click Delete button in Element Editor
Confirm deletion dialog appears
Element removed (change tracked in version history)

Layout Configuration

Each schematic saves its preferred layout algorithm in the database. When you reopen a schematic, it automatically applies the saved layout.

Persistent Layout:

Dropdown selection stored per-schematic
Default: Grid 3×3
Change persists across sessions

Manual vs. Automatic:

If ANY nodes have manual positions → uses "preset" layout (respects positions)
If NO manual positions → applies algorithm from dropdown
Click Auto Layout to clear positions and reapply algorithm

Switching Layouts:

Change dropdown selection
Layout immediately applied
All manual positions cleared
New layout committed to version history

Version Management

Schematics use the same version/commit system as map features.

Automatic Commits:

Every change creates version entry
Add/delete node → committed
Add/delete edge → committed
Edit element properties → committed
Change layout → committed

Version History:

Access via Versions Manager (map toolbar)
Review all diagram changes over time
Rollback to previous states
Merge offline edits from collaborators
Submit → Request Commit from the toolbar; non‑admins send drafts to the admin queue for approval (see Admin → Versions)

Offline Editing:

Create/edit schematics offline
Changes stored locally in browser storage
Sync when back online
Conflict detection for concurrent edits

Advanced Features

Drag-and-Drop Integration

Schematics integrate with Aptli's drag-and-drop system:

From Map to Schematic:

Drag feature cards from layer panels
Drag selected features list items
Drop in Schematic Editor canvas
Automatically creates node with featureId link

Geometry Type Detection:

Point features → Point icon
LineString features → Line icon
Polygon features → Polygon icon
Icons help identify node types at a glance

Live Code Editing

The Code Editor provides direct JSON manipulation for advanced users.

Validation:

All edits are validated before being applied
id is required (must be a non-empty string)
geometryType must be Point, LineString, or Polygon (if present)
Position coordinates must be numbers
Edges require source and target
Nodes cannot have source or target

Use Cases:

Bulk property changes (copy-paste JSON)
Add relationships without UI (manual source/target)
Debug data structure issues
Copy element to another schematic

Multiple Relationships

Unlike many diagramming tools, Aptli supports unlimited edges between same nodes:

Example - Bidirectional Flows:

Transformer A → Service Point B (power supply, 240V)
Service Point B → Transformer A (telemetry data)
Transformer A → Service Point B (fault notifications)

No Duplicate Protection:

Intentional design choice
Some relationships genuinely duplicated
User responsible for managing edge count
Code editor shows all edges for review

Custom Properties

Both nodes and edges support custom properties:

Schematic-Level Properties:

Edit in metadata panel (top of editor)
Key-value pairs stored as JSON
Use for diagram-wide metadata
Examples: "voltage: 240V", "network_segment: north"

Element-Level Properties:

Edit via code editor (data object)
Add any fields beyond the standard structure
Extra properties are preserved and stored alongside the element
Examples: capacity, status, install_date

Integration with Map Features

Feature Linking (featureId):

Nodes can reference map feature by ID
Bidirectional: click schematic node → highlight map feature
Useful for network diagrams matching real infrastructure

Independent Nodes:

Custom nodes don't require map features
Useful for abstract concepts (stages, processes, logical groupings)
Mix linked and independent nodes in same diagram

Sync Considerations:

Schematic doesn't auto-update if linked feature deleted
Orphaned featureId shows as missing (handle manually)
Future enhancement: auto-cleanup on feature delete

Best Practices

When to Use Schematics

Good Use Cases:

Network topology that's hard to see on map (dense areas)
Logical flows that don't match geography (service delivery paths)
Equipment dependencies across large distances
Multi-stage processes with clear sequence
Relationship modeling independent of location

When NOT to Use:

Simple spatial proximity (use map buffer tools instead)
One-off visualizations (export GeoJSON and use external tools)
Frequently changing connections (high maintenance overhead)
Public-facing diagrams (schematics are internal tools)

Naming Conventions

Schematic Names:

Be specific: "North District Fiber Splicing" not "Fiber 1"
Include date/version if temporal: "Q4 2025 Network Plan"
Use location references: "Downtown Transformer Circuit A"

Node Names:

Match map feature names when linked (auto-populated)
For custom nodes, use clear identifiers: "Stage 3: Filtration"
Avoid generic names: "Node 1", "Point A"

Edge Labels:

Describe relationship: "feeds", "reports to", "depends on"
Include capacity: "100A", "10 Gbps", "500 GPM"
Use consistent terminology across same schematic type

Version Management Tips

Commit Frequency:

Each change automatically committed (no manual commits needed)
Version history can get long for active diagrams
Use version compression to reduce storage (future feature)

Version Descriptions:

Not currently captured in UI (all commits auto-generated)
Use schematic properties to record major milestones
Example property: "last_audit: 2025-02-14, auditor: jdoe"

Rollback Safety:

Test rollback in non-production environment first
Verify all linked features still exist after rollback
Communicate with team before major rollbacks

Performance Considerations

Large Diagrams:

100+ nodes may slow down rendering
Consider splitting into multiple schematics
Use layout algorithms (faster than manual positioning)

Complex Edges:

Many edges between same nodes can overlap
Manual positioning helps separate overlapping edges
Future enhancement: edge routing/bundling

Mobile Usage:

Schematic Editor optimized for desktop
Mobile view works but limited by screen size
Recommend tablet minimum for editing

Keyboard Shortcuts

Note: Keyboard shortcuts not yet implemented. Future enhancement.

Planned:

Delete key to remove selected element
Ctrl+Z / Cmd+Z to undo (via version rollback)
Arrow keys to nudge selected node
Ctrl+C / Ctrl+V to copy-paste nodes

Current:

Schematics stored in database (not exportable as files)
Share via user permissions (all users with map access see schematics)
Version history provides audit trail

Future Enhancements:

Export as PNG/SVG image
Export as GraphML/Cypher for external tools
Export as JSON for backup/migration
Generate URL to share specific schematic view

Map Features - Create features to use in schematics
Layers - Layer schemas define available features
Versions - Version management system used by schematics
Popout Windows - Multi-window workflows
Drag and Drop - Drag features between components