Systems and Subsystems

A System is the Istari Digital Platform's primitive for grouping related Resources so they can be versioned, shared, and composed together. A System can include other Systems as Subsystems to mirror real-world decomposition. Inside a System, you can optionally arrange Resources into folders — a layout for browsing, not a substitute for the System itself.

Note: A Resource is any registered file in the platform — uploaded or connected, model or artifact. See Resources for how a file becomes a Resource. Resources keep their identity and revision history regardless of which Systems reference them.

Why does it matter?

Resources do useful work on their own. Most engineering deliverables are made of many Resources tied together by facts that are not visible on any single one of them:

• Same audience. A wing model, its FEA results, the manufacturer's drawings, and the test report are all relevant to the same group of people. Sharing them as a unit, with consistent permissions, beats hand-managing access on each Resource.
• Same logic. Parts of one product belong together. The avionics module, its harness, its firmware, and its bench-test results describe one assembly. Treating them as a group preserves the engineering relationships that connect them.
• Same lifecycle. Resources move through review, validation, simulation, certification, and release together. When a System is committed for PDR or release, every Resource in that composition is recorded at a known version.

A System makes those facts explicit. Ownership, sharing, and version tracking apply to the group, not to each Resource individually.

A System is not a folder

It's tempting to picture a System as a folder of files — and at first glance it works that way. You give it a name, add Resources, and share the whole thing.

A System captures what a directory cannot:

• A Resource can belong to many Systems at once. A common hydraulic actuator model can sit in landing gear, hydraulics, and flight controls simultaneously. Each System sees the same Resource identity and the same revision history — there's no copy.
• Systems compose into other Systems. A Subsystem is itself a System, with its own owner, lifecycle, and access — but referenced into a parent. Aircraft can include Propulsion, which can include Engine, recursively.
• Versioning is built in. When a Resource updates, Systems that track it see the new version. System version control — branches, commits, and change requests — records exactly which Resources and Subsystems belonged together at each saved state.

The result is closer to a graph of relationships between coherent groups of Resources than a directory tree: the same Resource can appear in several engineering contexts, Systems compose into one another, and revision state is meaningful and inspectable along every edge of the graph.

Folders inside a System

Folders organize the Resources already in a System into a hierarchy so a large System reads like a familiar directory tree (for example engineering/aero/ and scratch/). They answer where does this Resource sit in this System's tree? — not what is this engineering group?

That distinction matters:

	System	Folder
Purpose	Group, share, version, and compose related work	Browse and arrange Resources inside one System
Identity	First-class platform object with owner, roles, branches	Path-derived layout — a folder exists because Resources live in it
Membership	A Resource can belong to many Systems	A folder path is local to one System (and one branch)
Access	Sharing and roles live on the System (and cascade to tracked Resources)	Folders do not grant or restrict access

Key behaviors:

• Path-based. There is no standalone folder object. Empty folders disappear when the last Resource leaves them; you create a folder by placing a Resource in it.
• Per branch. The layout belongs to the branch you are editing. Earlier commits keep the layout they were captured with.
• Saved as commits. Creating folders and moving Resources are System edits. Saving produces a new commit on the branch.

Use folders when a System's Resource list is hard to scan and you want a tree by discipline, work package, or team convention. Use Subsystems when the child is its own System — with its own lifecycle, sharing, and version history — referenced into a parent.

Systems and Subsystems

A System is the named group of Resources (and optional Subsystems) you treat as one engineering unit — share it, version it, and compose it as a whole. Typical examples are a vehicle, an assembly, an analysis package, or a deliverable: each has a name, an owner, and zero or more Subsystems. References to Resources can be:

• Tracked — the System follows the Resource's latest version automatically.
• Pinned — the System is locked to a specific version until you change it explicitly.

Every System starts with a baseline branch. Commits on a branch record the composition over time; other Systems that reference this one as a Subsystem default to the baseline. For Resource versions versus System branches, see Version control.

A Subsystem is another System linked into a parent so the parent can pin a known version of that unit. The parent typically pins the child's baseline branch, so the parent's recorded state deterministically resolves which version of the child it captured.

Subsystems compose. An aircraft System can include Propulsion as a Subsystem, which can itself include Engine as a Subsystem. Each level is a stand-alone System with its own owner, Resources, and lifecycle — composed into the parent only when needed.

Map a System to your way of working

The platform does not prescribe a methodology. The same primitives map cleanly to several patterns; pick what matches your program and adapt as you go.

Mirror your product breakdown

The natural starting point is to mirror your product's decomposition. One top-level System per product, with Subsystems for each major assembly. The hierarchy is durable — once established it should rarely change.

For an aircraft program that might look like:

• Aircraft (top-level System)
  • Airframe (Subsystem) — fuselage, wings, empennage
  • Propulsion (Subsystem) — engine, fuel system, thrust reverser
  • Avionics (Subsystem) — nav, comms, flight management
  • Flight Controls, Electrical, Hydraulics, Landing Gear, ECS, Payload — each its own Subsystem.

Each Subsystem can decompose further or stay flat. Depth is your call; the platform does not impose a level. Within any one System, folders can further arrange Resources in the tree without creating new Systems.

Map the RFLP layers into one System

For programs running an MBSE methodology like RFLP — Requirements, Functional, Logical, Physical — keep all four views as Resources inside the same System rather than scattered across separate tools:

RFLP layer	How it lives in a System
Requirements	A Resource — an .xlsx requirements sheet, a ReqIF export, a Cameo requirements package. Versioned, shared, and reviewed alongside everything else.
Functional	A Resource — Cameo, Simulink, IDEF model. The function tree lives inside the model file; the System versions the file.
Logical	The Subsystem tree itself, plus interface-definition Resources. Decomposing your product into Subsystems is the logical view.
Physical	CAD, FEA, software, and test-data Resources tied to the Subsystem they describe. The native strength of the digital thread.

Because requirements, functional models, logical decomposition, and physical artifacts all live in one Istari Digital System, traceability across them becomes a first-class platform concern — visible, versioned, and shareable as a single unit.

Pick a granularity that matches your reuse

• Folder when you only need a browsing hierarchy inside one System (for example grouping drawings under drawings/).
• Subsystem when the child is part of the parent and follows its lifecycle, but is still its own System — with its own owner and life — referenced, not duplicated.
• Separate System when the child has independent significance: shared across many parents (a common component library), used by many programs, or running a distinct lifecycle (a long-lived variant program in production while the main program continues to evolve).

A Resource referenced from multiple Systems is normal. A Subsystem referenced from multiple parent Systems is normal. The platform treats both as relationships, not copies.

Key details

• Data sovereignty. File contents stay in your data plane (e.g. S3, Azure) or in their connected third-party source. The platform's control plane holds only metadata — Resource identity, revisions, System membership, sharing.
• Permission inheritance. Granting a role on a System cascades to the Resources it tracks — see System permission inheritance below.
• Baseline branch. Every System starts with a baseline branch. Other Systems that reference this one default to it. See Version control.
• One Resource, many Systems. A registered Resource is one identity. If the same Resource is tracked by multiple Systems, a user with access to any of those Systems can reach it.
• Folders are layout, not identity. Moving a Resource between folders does not change its UUID, revision history, or which Systems track it. Folder changes are commits on a branch.

System permission inheritance

When you share a System with a user, their role on the System automatically cascades to the Resources tracked by the System. You don't need to share each one individually.

System role	Tracked Resources	Archive permission
Viewer	Can view	No
Editor	Can view and edit	No
Administrator	Can view and edit	No
Owner	Can view and edit	No

• Archive does not cascade. Only users with direct Owner or Administrator access on a Resource can archive it.
• Cascade applies to all tracked Resources. Including artifacts tracked without their parent model.
• Multiple Systems, broader access. If a Resource is tracked by more than one System, a user with access to any one of those Systems can reach it.
• Removing a System role removes the cascaded access along with it. Direct access granted on individual Resources is preserved.
• Subsystem contents do not inherit. Permissions stop at the parent. To view a Subsystem's Resources, a user must be granted access to the Subsystem itself.
• Folders do not change access. Organizing Resources into folders does not grant or restrict permissions.

For the bigger picture on sharing and roles, see Sharing, security, and access control.

How to work with Systems

User guide (UI):

• Systems guide — Create a System, add Resources and Subsystems, organize folders, and share.
• Branches — Create, switch, and edit System branches; commits and change requests in the web app.

Python client (SDK):

• SDK setup — Install and configure the istari-digital-client package.
• Branching and change requests — Create branches, commit Resources, and merge change requests.
• Systems — create_system, plus the System composition section for nesting Subsystems.

Related terms

Artifact, Baseline, Branch, Model, System