Kotar (pronounced KOH-tar) is a serverless web application that runs locally in your browser. NO DATA IS STORED ON SERVER SIDE when using Kotar unless explicitly connecting to remote git or a remote Flexo.

Model processing and normal file operations happen locally. There is no "backend" server with which Kotar exchanges data. All features that help you edit, parse, validate, visualize, or otherwise work with your models happens locally on your machine.

The following diagram shows the deployment architecture. Components inside the Kotar boundary are what you receive when you open Kotar; all of them execute locally within your browser. Connections to the local file system and services, such as a remote Flexo repository or remote git repository, are optional.

The SysML service pattern here illustrates a common way of connecting models to other services. Kotar running locally in the browser gives the user access to a local model that can be used to develop connections to other tools if desired.

Kotar also supports direct access to files on your machine through the browser's File System Access capabilities.

This is different from web applications where the browser primarily acts as a front end and sends your content to a remote server for processing.

Remote communication only occurs when you explicitly use functionality configured to communicate with an external or shared service, such as a remote enterprise Flexo instance.

It is highly recommended to save you models in your local file system or a remote repository.

Kotar is an integrated engineering environment for working with SysML v2 and KerML models.

It combines familiar software-development IDE capabilities with model-based systems engineering functionality. Users can author textual SysML v2, work with graphical representations, validate and analyze models, manage engineering files and data, execute scripts and command-line tools, transform external data into model content, and maintain model and workspace revision history.

The Kotar workspace can contain more than the SysML model itself. It can also contain supporting engineering information such as:

• SysML v2 and KerML files;
• Python or TypeScript scripts;
• CSV files;
• configuration files;
• database content;
• transformation scripts;
• generated artifacts;
• other files used as part of the engineering workflow.

This allows Kotar to manage an engineering workspace, rather than treating the SysML model as an isolated artifact.

A workspace is the primary working context in Kotar.

A workspace contains the files, models, scripts, data, and other engineering artifacts associated with a project or activity.

To protect the privacy of your data by default Kotar does not save any data to the cloud, external servers or local files until you explicitly choose to do so. All files are stored in a virtual file system local to the browser running Kotar. The virtual file system is not intended to store data long term nor make it available on other devices. If you want to save your work or transfer it to other devices you have the options below:

• save work to a local file directory on the device running Kotar
• commit to an existing Git repository
• commit to a project retrieved from a remote SysML v2 service
• download your project files

IMPORTANT: If you do not opt for one of these options any data stored in Kotar will not persist after the browser clears its cache and will not be accessible on any other device.

A workspace may contain:

project/
  model/
    system.sysml
    requirements.sysml

  data/
    requirements.csv

  scripts/
    transform.ts

  analysis/
    analysis.py

  .git/

To setup a workspace that connects to the host device file system follow the steps below:

Workspaces > Open local folder > Allow Edits > Edit the Model > File/Save > Open from your local file system

To configure a remote git repository or a remote SysML v2/Flexo service refer to the sections later in this guide.

See the step-by-step guide: Create a temporary workspace

See the step-by-step guide: Create a workspace linked to a local folder

The interface follows the general layout of a modern development IDE. See the diagram below for a quick tour:

1. Workspace / File Explorer
2. Textual Model Editor
3. Graphical Model Editor
4. Helpful Tools
   • Problems panel
   • Output panel
   • Terminal
   • REPL
   • Version-control tools
   • Tables and data tools
   • Model repository tools
5. Model Browser

You can easily control the panels that are displayed with the quick layout buttons:

Figure 1: Kotar Overview Diagram

Some advanced functionality may be hidden by default so that normal model-authoring workflows remain uncluttered.

Open a ".sysml" or other supported model file from the workspace explorer. Files can be created within the workspace, uploaded from the desktop by dragging and dropping, and/or retrieved from a remote git or remote Model Management System, such as OpenMBEE Flexo.

The textual editor provides language-aware functionality backed by the SysML v2 language tooling.

As the model is edited, Kotar analyzes its syntax and semantics.

Problems discovered in the model are displayed using standard IDE-style severity levels.

See Getting Started for examples.

These include:

• Hint
• Warning
• Error

Problems may originate from:

• syntax errors;
• semantic errors;
• validation rules;
• lint rules;
• transformation state;
• other model analysis.

Use the Problems panel to review detected issues.

Selecting a problem highlights the relevant model location.

Linting identifies modeling constructs that may technically be valid SysML but do not follow recommended modeling practices or project conventions.

See Getting Started for examples.

When a lint problem provides a quick fix:

1. Open the problem or the affected model element.
2. Select the available quick-fix action.
3. Choose the desired scope.

Depending on the rule, Kotar may allow you to:

• fix the selected occurrence;
• fix all occurrences of the same lint rule in the file;
• apply all available automatic lint fixes in the file.

Example

A naming rule may identify:

part def drone_system

and recommend changing it to the naming convention required by the project, in this case would be camel case of "DroneSystem".

The exact conventions depend on the configured lint rules. Lint rules can be configured in the SysML tab under the "Lint rules" option.

Kotar includes a SysML v2 formatter. This formatter can be used to normalize textual SysML according to the formatting rules configured for the workspace. Formatting is also automatically used by some generated-content workflows, including model transformations. It can be applied to a textual model by right-clicking in he Editor and selecting "Format Document"

See Getting Started for an example.

Kotar includes a graphical editor for navigating and modifying the SysML model. Graphical and textual representations operate on the same underlying semantic model. This means that there is no "syncing" happening between the representations - both are showing the same model. Users can therefore work with the representation that is most appropriate for the task.

See Getting Started for examples.

Changes made through one representation can be reflected in the other.

The following steps are provided as an example to show these capabilities:

1. Modify an element in the graphical editor;
2. The corresponding model content changes;
3. The textual representation is updated.

The reverse workflow is also supported:

1. Modify the SysML text;
2. The model is re-evaluated;
3. The graphical representation reflects the changed model.

The following are current limitations of Kotar.

1. Preserving graphical identity and layout across certain textual operations remains an area under development.

• Moving, cutting, pasting, or restructuring textual model elements can make it difficult to determine whether an element is: -- the same semantic element moved to another location; or -- a newly created element. -This may affect graphical layout.

2. Users should take care with unnamed elements created graphically.

The semantic model can contain elements with identities that cannot always be represented unambiguously in the textual notation. This is particularly relevant to graphical relationships involving unnamed model elements.

Recommendation: Prefer named model elements where practical when the model must be edited interchangeably through graphical and textual representations.

See Known Issues for more information.

Kotar has access to the standard libraries for units and quantities and will automatically import the unit or quantity needed as you model. To add units to a value, simply type the unit as you would in SysML v2 (example below), and Kotar will offer the option to import the quantity and units. It also supports compound units defined with mathematical expressions of existing units.

package Example {
  
    part vehicle : Vehicle{
        attribute gauge : ISQBase::LengthValue = 0.8 [m];
    }
 
}

Kotar also evaluates expression and displays the result inline. It is capable of performing calculation on both literal and quantities with units and handles unit conversions automatically.

Kotar provides model-aware engineering analysis rather than limiting model checking to syntax, including the important capability of constraint propagation. Constraint propagation determines information that follows logically from the constraints in the model.

For example, suppose a model constrains:

airframeMass + batteryMass < 1.8 kg

Even if "airframeMass" does not yet have one fixed value, Kotar may be able to infer a range within which it must fall. Such an inferred range is not the same as assigning a value. It represents something that must be true for models satisfying the applicable constraints.

Kotar evaluates constraints in real-time and displays the results in-line.

Depending on the analysis, a condition may be:

• satisfied;
• violated;
• undecided;
• constrained to an inferred range.

Where available, the UI will also expose the reasoning or constraint responsible for a result.

A blank or undecided result should not automatically be interpreted as success.

Some constraints require more advanced mathematical reasoning.

The Kotar architecture supports use of an SMT solver such as Z3 for these cases.

An SMT solver can determine whether a collection of constraints is:

• satisfiable;
• unsatisfiable;

and may provide a witness assignment showing a set of values that satisfies the constraints.

Example

A result might state that a model is satisfiable when:

duty = 0

Such a value is a witness demonstrating one solution; it does not necessarily mean that it is the only possible solution.

Availability

Z3 is not available in the running build.

Kotar contains an interactive REPL for evaluating expressions.

The REPL can be used to evaluate KerML/SysML expressions without creating a separate script.

The result is printed interactively.

The REPL is useful for:

• exploring model expressions;
• testing calculations;
• experimenting with model queries;
• investigating model behavior.

Kotar includes a browser-based terminal.

The terminal is intended primarily for advanced users, developers, automation authors, and scripted workflows.

It provides a shell-like environment that supports Bash-style expressions and scripts.

Capabilities demonstrated or discussed include:

• Bash scripting;
• filesystem operations;
• "curl"-style HTTP requests;
• JSON processing;
• compression utilities;
• encoding/decoding utilities;
• SysML v2 command-line tools.

Use the terminal's "help" command to see the command-line programs available in the current distribution.

The Kotar terminal provides access to the SysML v2 CLI.

Because the current workspace is normally automatically selected as the model context, CLI commands can work against the loaded model without requiring every source file to be provided manually.

The CLI capabilities shown during the demo included:

The CLI is primarily an advanced-user capability. Most normal model-authoring workflows can be performed directly through the graphical or textual Kotar interfaces.

Under the hood Kotar runs several engineering services locally including:

• SysML v2 service
• Flexo/MMS
• RDF Quad Store
• SQLite3

The Services panel can be used to check on the running services but is considered an advanced feature that most users will not interact with.

Open the Services panel to inspect logs from the local services.

This can be useful for:

• development;
• debugging;
• investigating API interactions;
• diagnosing repository or model-service problems.

The Services interface also allows HTTP requests to be sent directly to the services. This is similar to using a Swagger/OpenAPI interface.

This feature is intended primarily for developers and advanced users. Normal users are recommended to access model functionality through the higher-level Kotar interface rather than interacting directly with MMS.

Kotar integrates with Flexo/MMS for model persistence and model revision management. As you work changes are automatically committed to the locally running flexo (not an external server).

The Flexo interface can be used to inspect model repository information such as:

• projects;
• commits;
• model revisions;
• model deltas.

Remote Flexo instances can also be configured through this interface.

A remote Flexo/SysML v2 service can be connected to Kotar.

Once connected, available projects can be enumerated and a remote project can be checked out as a local workspace.

A typical workflow is:

1. configure the remote service;
2. select a remote project;
3. check out the project;
4. work locally in a Kotar workspace;
5. synchronize or commit model changes according to the configured workflow.

From the Flexo tab select the current flexo instance (default is Mesh SysMLv2)

Then select Manage Connections

Select the + Add connection button. Configure the fields: Name, Kind (MMS or SysMLv2), URL, Token. You can test the connection first with the "Test Connection" button. Then select "Add Connection"

1. Open settings.json. Click Open settings.json in the top right of the Connections view. This opens your User settings file in the editor.

2. Add a sysmlv2.flexo.connections block. It accepts MMS and SysMLv2 connections in the following format.

   "sysmlv2.flexo.connections": [
     {
       "name": "<connection-name>",
       "kind": "mms",
       "url": "<mms-url>",
       "token": "<your-token>",
       "readOnly": true
     },
     {
       "name": "<connection-name>",
       "kind": "sysmlv2",
       "url": "<sysmlv2-url>",
       "token": "<your-token>",
       "mms": "<mms-connection-name>"
     }
   ]

Do not include the "Bearer " prefix with your token.

3. Save the file.

4. Select the new connection. Go back to the Flexo tab, pick your connection from the dropdown, and confirm your projects load.

5. Right click a project and select "Clone"

Check out this page from OpenMBEE if you are interesting in using the public remote flexo.

Once connected to a remote, the Flexo tab in Kotar shows the list of projects on that remote. Right click on a project and select Clone to local. The local workspace is now linked to the remote and you can fetch, push, pull and resolve conflict from the Model Remotes menu in the Version Control panel.

Model Remotes menu in the Version Control panel you can see the status of the remote relative to the local workspace. It can show the following:

• Up to date - both local and remote are in sync
• Ahead - the local model has changes not present in the remote
• Behind - the remote has changes not present in the local
• Diverged - both the local and remote have changes that are conflicting

The example below shows a workspace that has diverged. By selecting the diverged chip the user can choose how to resolve the conflict.

The workspace can also be managed as a Git repository. The settings for local and remote git can be found in the Source Control panel.

A typical workflow is:

1. initialize Git for the workspace
2. create an initial commit
3. continue working normally - Kotar will maintain fine-grained automatic revisions
4. create intentional Git commits as meaningful checkpoints

Kotar includes a graphical Tables interface backed by SQLite.

The table database is a general engineering-data capability. It is not itself the SysML model.

Users can:

• create a database
• create a table
• inspect data
• edit cells
• run SQL

This allows users to develop complex engineering workflows.

CSV files can be viewed through a table-oriented user interface.

This is useful when engineering source information is naturally represented in tabular form, such as:

• requirements
• parameter sets
• interface data
• test data
• engineering inventories

Kotar can load the selected tabular data in the local SQLite database and can assist in creating filters.

For example: in a requirements CSV, Kotar can recognize repeated category values and present them as enum-like choices.

Selecting a value generates the corresponding textual filter expression interactively.

After filtering a data set, the resulting view can be used for additional operations such as:

• export to other formats
• loading the filtered data into a new SQL table

Current limitation

Some advanced table operations are still in development.

Kotar supports transformation of external engineering data into SysML v2 model content.

For example: requirements contained in a CSV file can be turned into SysML requirement elements

Transformations are useful when authoritative engineering information originates outside the SysML model.

Possible source information includes:

• CSV
• SQL tables
• other structured engineering data sources

Transformations can be implemented using TypeScript or Python

A transformation can specify information such as:

• transformation source
• target package
• generated model content
• optional templates

When working with a TypeScript transformation, Kotar provides a model-aware TypeScript environment.

A global "transform" object is made available to transformation scripts.

Kotar also creates contextual TypeScript configuration and virtual type-definition files.

These include:

"model.d.ts"

Provides type information representing the current model.

Transform definitions

Provide typed representations of available engineering data sources.

As a result, TypeScript autocomplete and type checking can understand both the model and the source engineering data.

The TypeScript transformation used a recognized transformer file and default export.

When the transformer is run, Kotar:

1. opens the debug/output environment
2. executes the transformation
3. generates a summary
4. generates SysML model content
5. applies the workspace formatter
6. applies lint rules
7. reports any lint warnings
8. stages the resulting model changes as a diff

This allows generated changes to be inspected before becoming part of the accepted model.

Generated model changes are presented for review.

Before applying a transformation result:

1. inspect the generated summary
2. review the model diff
3. review validation/lint findings
4. verify that the generated elements are appropriate
5. accept or reject the proposed changes

Use transformations with care.

Elements created through a transformation are visually distinguished from manually authored model content.

For example: generated requirements are displayed using different coloring.

Hovering over a generated element displays information equivalent to:

«Generated from "requirements.csv" by the transformation script. Edit the data, not the model.»

This is intended to prevent divergence between the authoritative source data and generated SysML model content.

Kotar records traceability and relationship information for generated model elements. Allowing users to author digital threads.

This information links generated model content to:

• the transformation
• the source file
• a digest/version of that source
• the generated model elements

This allows Kotar to identify where generated content came from and whether the source or transformer has changed.

When authoritative source data changes:

1. edit the source data, for example "requirements.csv"
2. rerun the transformer
3. review the generated summary and diff
4. accept the appropriate model changes

Do not manually modify generated model content when the source data should remain authoritative.

Kotar can detect when a transformation has changed since model content was generated.

This condition appears in the Problems interface.

This helps prevent users from assuming that generated model content is up to date when:

• its source has changed
• the transformation logic has changed

Kotar maintains automatic revision history.

Changes to workspace files generate revisions without requiring the user to explicitly create a commit every time.

The revision system tracks the engineering workspace, not only SysML files.

It may therefore include:

• model files
• scripts
• CSV files
• configuration
• other workspace artifacts

Text files are represented using textual changes.

When both Git and Flexo are used, a Git commit can be associated with the corresponding flexo commit.

This creates traceability between the complete engineering workspace in Git and the corresponding SysML model state in Flexo.

The revision system and Git solve different problems.

Automatic revisions

Provide fine-grained history while you work.

Git commits

Represent deliberate checkpoints with commit messages and support normal Git workflows.

Flexo commits

Represent model repository states and can be associated with Git checkpoints.

Users therefore do not need to create a Git commit for every small edit.

Normal editor Undo is separate from the workspace revision-history system.

Using "Ctrl+Z", for example, performs an editor undo operation.

Revision history records workspace states and deltas separately.

Use:

• Undo for immediate local editing mistakes
• Revision History when you need to inspect or restore an earlier workspace state

Kotar uses a non-destructive recovery mechanism.

When you restore an earlier state:

1. the current state is preserved
2. Kotar computes the difference between the current state and the selected previous revision
3. that change is applied
4. the restoration becomes a new revision

Nothing later in the history is deleted.

This approach is referred to as “always forward.”

Fine-grained Kotar revisions can also be represented in a private shadow tree in Git.

It can optionally be pushed to a remote Git repository using a separate name, allowing the automatic Kotar revision history to be persisted remotely as well.

This is an advanced capability.

Most users can simply work with the normal revision-history interface.

Git can contain intermediate engineering work, including incomplete model states.

Flexo can be configured or used more conservatively as the location for valid or authoritative model states.

The current implementation already commits automatic model revisions to Flexo only when the model is valid.

This allows users to continue version-controlling incomplete work in Git while keeping the authoritative model repository healthy.

Kotar is intended to support users who need to combine modeling with engineering automation.

An advanced workflow might therefore include:

External engineering data
        ↓
CSV / SQL
        ↓
TypeScript or Python analysis/transformation
        ↓
Generated SysML
        ↓
Validation / linting
        ↓
Review generated diff
        ↓
Accept model changes
        ↓
Commit workspace to Git
        ↓
Commit valid model state to Flexo

Kotar provides these capabilities within one workspace so that the associated artifacts can remain traceable.

For normal engineering work, the following workflow is recommended.

Step 1 — Open or create a workspace

Create a project in local file system, clone a Git repository, or check out a project from the SysML v2 service.

Step 2 — Edit the model

Use the textual and graphical editors to build a model.

Step 3 — Resolve problems

Review:

• errors;
• warnings;
• hints;
• lint findings.

Apply quick fixes where appropriate.

Step 4 — Review analysis

Where relevant, review:

• requirement verification
• constraint results
• inferred ranges
• solver findings

Step 5 — Integrate engineering data

If model information originates in CSV, SQL, or another structured source, use a transformation rather than manually duplicating the information.

Step 6 — Review generated changes

Inspect:

• transformation summary
• model diff
• validation
• lint results
• traceability

Step 7 — Create a Git checkpoint

When the workspace reaches a meaningful state, create a Git commit.

Step 8 — Promote valid model states

Synchronize valid model states with Flexo. Push results to a remote if configured.

Preserve the complete engineering workspace

Do not version only the SysML model if scripts, CSV files, or transformations are necessary to understand or reproduce it.

Git should normally contain the entire engineering workspace.

Keep authoritative source information authoritative

If a model element is generated from another source, modify the source and regenerate the model rather than editing the generated element manually.

Use meaningful Git checkpoints

Allow automatic revisions to capture small changes.

Use Git commits for intentional engineering milestones.

Review generated content

Transformation output should be treated like generated code:

• inspect it
• validate it
• review its diff
• confirm its provenance

Name model elements when practical

Named elements provide more reliable synchronization between textual and graphical representations than unnamed elements.

Do not rely solely on browser storage

Use local files, Git, Flexo, or another persistent repository for important projects.

Understand verification results

Distinguish between:

• a concrete evaluated value
• an inferred constraint or range
• satisfiability
• a witness value
• an undecided result

The following features are intended primarily for advanced users:

Most everyday SysML modeling does not require direct interaction with these capabilities.

See the Known Issues for more information.

See the Features

Workspace The complete set of model files, data, scripts, and other files associated with an engineering project.

Revision A fine-grained automatically recorded change to the workspace.

Git Commit A deliberate workspace checkpoint stored through Git.

Flexo Commit A model repository revision representing a SysML model state.

Model Context The SysML model currently loaded and used implicitly by Kotar tooling.

Lint A model quality rule that flags syntactically correct code that violates best practices.

Constraint Propagation Inference of values or ranges that follow from the model's constraints.

Transformation A programmatic process for converting external engineering information into SysML model content.

Provenance Metadata identifying the source and transformation responsible for generated model content.

Generated Element A SysML model element produced from another engineering source rather than manually authored.

MMS The model-management layer beneath the SysML v2 service responsible for storing semantic models.

Shadow History A Git-backed representation of Kotar's fine-grained automatic revision history.

Kotar provides modeling, validation, transformation, and analysis capabilities intended to assist systems engineering work.

Users remain responsible for reviewing model content and analysis results and for applying the engineering verification, validation, review, and certification processes appropriate to their project.

A successful parse, validation, transformation, or constraint result should not by itself be interpreted as certification that an engineered system is correct, complete, safe, or suitable for a particular application.