Architecture Overview

Orvienm is a command-line engine that operates on a workspace. There are two artefacts and one program.

• The specification — a YAML file declaring a structure name and the directories it should contain. You author and version this.
• The workspace — the directory tree the engine creates and inspects, plus the .orv.lock file recording the specification it was built from.

The engine reads the first, reconciles the second toward it, and exits. Nothing runs in the background.

you ── author ──▶ .orvienm.yaml
                       │
                       ▼
                 orvienm CLI
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
     validate        plan          apply
   (file only)   (read-only)   (creates dirs)
                       │              │
                       ▼              ▼
                  workspace  ◀──  .orv.lock
                       │
                       ▼
        verify · status · doctor

• Engine — the Python package and its orvienm command. This is the product: parsing, validation, planning, application, verification and fingerprinting all live here. Distributed as an Alpha from source.
• Platform — this website. It documents the engine and holds no product logic.
• Studio — a separate interactive surface under active Alpha development. It is not publicly available and is not required to use the engine.

The surfaces are independent. Everything documented under Resources is engine behaviour, reachable from the CLI alone.

• The specification owns intent — which directories should exist, and under what name.
• The engine owns creation and comparison. It writes only directories it was told to create.
• The lock file owns the record of which specification a workspace was built from, and nothing else.
• You own everything the specification does not mention. The engine reports undeclared directories but never removes them.

The engine manages directories. It does not manage file contents, permissions or ownership; it does not run builds; it does not watch the filesystem; and it keeps no history beyond the single lock file.

For the module-level view of the engine itself, see Engine Design.