Skip to main content

​
Projects and Files

Projects and files organize your Cerulion work. A project is a container for related graphs, schemas, and node code. Understanding the project structure helps you organize your work and collaborate effectively.

​
What is a Project?

A project is a workspace that contains:
  • Graphs - Visual designs of your data pipelines
  • Schemas - Data type definitions
  • Node Code - Implementation files (Rust, Python, C++)
  • Configuration - Build and runtime settings
Think of a project as a folder on your computer that contains everything needed for one application or system. You can have multiple projects, each with its own graphs and code.
Projects are self-contained. Each project has its own schemas, nodes, and graphs. You can share projects by copying the project folder.

​
Why Organize with Projects?

Separation of Concerns

Keep different systems in separate projects. Each project is independent.

Reusability

Share schemas and nodes across graphs within a project. Reuse components easily.

Version Control

Each project is a natural unit for version control. Track changes per project.

Collaboration

Share entire projects with team members. Everything needed is in one place.

​
Project Structure

A typical project has this structure: 
my-project/
  schemas/
    sensors.yaml
    geometry.yaml
    common.yaml
  nodes/
    temperature_reader.rs
    data_processor.py
    logger.cpp
  graphs/
    main.graph
    test.graph
  config/
    build.yaml
    runtime.yaml
  README.md

​
Schemas Directory

Contains schema definition files (.yaml):
  • One file per domain - Group related schemas together
  • Reusable across graphs - All graphs in the project can use these schemas
  • Version controlled - Track schema changes over time

​
Nodes Directory

Contains node implementation files:
  • Rust files (.rs) - Rust node implementations
  • Python files (.py) - Python node implementations
  • C++ files (.cpp, .hpp) - C++ node implementations
  • One file per node - Each node has its own implementation file

​
Graphs Directory

Contains graph definition files (.graph):
  • Visual designs - Saved graph layouts and connections
  • Multiple graphs - One project can have many graphs
  • Independent - Each graph can run separately

​
Config Directory

Contains configuration files:
  • Build settings - Compiler flags, dependencies
  • Runtime settings - Execution parameters
  • Environment configs - Different configs for dev/staging/prod

​
Creating a Project

1

Open Graph Editor

Launch Cerulion Graph Editor.
2

Create new project

Click File → New Project (or press Ctrl+N / Cmd+N).
3

Choose project location

Select where to create the project:
  • Default location - Projects folder in your home directory
  • Custom location - Choose any folder on your system
Use a location that’s easy to find and back up. Consider using a version control system (Git) for your projects.
4

Name your project

Enter a descriptive project name:
  • Use lowercase letters and underscores
  • Be descriptive: temperature-monitoring not project1
  • Avoid spaces and special characters
The project folder should be created with the basic structure (schemas/, nodes/, graphs/, config/).

​
Working with Files

​
Schema Files

Schema files are YAML files in the schemas/ directory: 
# schemas/sensors.yaml
schemas:
  TemperatureReading:
    fields:
      float32 temperature:
      uint64 timestamp:
Best practices:
  • One file per domain (e.g., sensors.yaml, geometry.yaml)
  • Use descriptive file names
  • Group related schemas together

​
Node Files

Node files contain your implementation code: Rust node: 
// nodes/temperature_reader.rs
fn main(output: &mut OutputPort<TemperatureReading>) {
    // Your code here
}
Python node: 
# nodes/data_processor.py
def main(input_port, output_port):
    # Your code here
C++ node: 
// nodes/logger.cpp
void main(InputPort<Data>& input) {
    // Your code here
}
Best practices:
  • One file per node
  • Use descriptive file names matching node names
  • Follow language-specific conventions

​
Graph Files

Graph files (.graph) are saved automatically when you save your project. They contain:
  • Node positions and connections
  • Port configurations
  • Trigger settings
  • Visual layout
Graph files are in a binary or JSON format. You typically don’t edit them manually—use the Graph Editor instead.

​
Opening Existing Projects

1

Open project dialog

Click File → Open Project (or press Ctrl+O / Cmd+O).
2

Navigate to project

Browse to the project folder and select it.
The editor should load the project, showing graphs in the left sidebar.
3

Select a graph

Click on a graph in the sidebar to open it on the canvas.

​
Project Best Practices

Descriptive Names

Use clear, descriptive project names. “robot-control-system” is better than “project1”.

Organize by Domain

Group related schemas in the same file. Keep nodes organized by functionality.

Version Control

Use Git (or similar) to track project changes. Commit schemas, nodes, and graphs.

Documentation

Add a README.md to explain what the project does and how to use it.

​
Sharing Projects

To share a project with others:
  1. Copy the project folder - All files are in one directory
  2. Share via Git - Push to a repository, others can clone
  3. Zip and send - Compress the folder and share
Projects are self-contained. As long as recipients have Cerulion Graph Editor installed, they can open and run your project.

​
Dependencies

If your project uses external dependencies:
  • Document them - List in README.md
  • Include versions - Specify exact versions for reproducibility
  • Provide setup instructions - Help others get dependencies installed

​
Project Templates

You can create project templates for common patterns:
  1. Create a project with common schemas and nodes
  2. Save it as a template
  3. Use it as a starting point for new projects
Templates save time when starting new projects. Create templates for common patterns in your domain.

​
Troubleshooting Projects

Problem: Can’t open an existing project.Solutions:
  • Verify the project folder exists and is accessible
  • Check file permissions (read access required)
  • Look for corrupted graph files (try opening individual graphs)
  • Check the console for error messages
Problem: Project opens but files are missing.Solutions:
  • Check that all project files are in the correct directories
  • Verify file names match what the project expects
  • Look for files in wrong locations (check all subdirectories)
  • Restore from backup or version control if available
Problem: Graph references a schema that doesn’t exist.Solutions:
  • Check that schema file exists in schemas/ directory
  • Verify schema name matches exactly (case-sensitive)
  • Ensure schema file is valid YAML
  • Reload the project to refresh schema cache

​
Next Steps

Now that you understand projects and files, learn more:

Quickstart

Create your first project and build a graph.

How-to Guides

Learn how to create schemas, nodes, and connect them.

Reference

See naming conventions and best practices for files.

Examples

Explore example projects to see structure in action.