Tessera
Plain-text engineering artifact management with full traceability
A CLI and desktop application for managing requirements, risks, tests, BOMs, tolerance analysis, manufacturing, and quality data as human-readable YAML files under git version control.
π Website: tessera-engineering.com
Table of Contents
- Features
- Installation
- Quick Start
- Short IDs
- Quick Start Workflows
- Project Structure
- Entity Types
- Output Formats
- Commands
- Project Management
- Configuration
- Global Search
- Requirements
- Risks (FMEA)
- Tests
- Test Results
- Components (BOM)
- Assemblies (BOM)
- Suppliers
- Quotes
- Features (Tolerances)
- Mates (Tolerances)
- Stackups (Tolerance Analysis)
- Manufacturing Processes
- Control Plan Items
- Work Instructions
- Non-Conformance Reports
- Corrective/Preventive Actions
- Link Management
- Traceability
- Where-Used Queries
- Reports
- Version Control
- Baselines
- Bulk Operations
- SysML v2 Interchange
- Example Workflows
- Manufacturing Quality Loop
- Tolerance Format
- Validation
- Status Workflow
- Priority Levels
- Risk Assessment (FMEA)
- Test Engineering
- Tolerance Analysis
- Best Practices
- License
- Disclaimer
Features
- Plain-text YAML files - Human-readable, git-friendly, diff-able
- Schema validation - JSON Schema validation with helpful error messages
- Traceability - Link entities together and generate traceability matrices
- ULID-based IDs - Unique, sortable identifiers for all entities
- Short ID aliases - Use
REQ@1,RISK@2, etc. instead of typing long IDs - Delete & Archive - Safe deletion with link checking, or archive entities for later reference
- Beautiful error messages - Line numbers, context, and actionable suggestions
- FMEA Risk Management - Built-in support for Failure Mode and Effects Analysis
- BOM Management - Components and assemblies with supplier tracking
- Tolerance Analysis - Features, mates, and stackups with worst-case, RSS, Monte Carlo, and 3D SDT analysis
- SysML v2 Interchange - Export and import SysML v2 textual notation for MBSE integration
- Desktop App (Beta) - Full-featured GUI for visual entity management
Installation
CLI Tool
The command-line tool is called tdt (Tessera Design Toolkit).
Pre-built Binaries (Recommended)
Download the latest release for your platform from GitHub Releases:
# Linux (x64)
|
# macOS (Apple Silicon)
|
# macOS (Intel)
|
# Windows - download tdt-windows-x64.zip and extract to your PATH
From crates.io
This installs the tdt binary. Note: compilation takes a few minutes due to dependencies.
From Source
# Binary will be at target/release/tdt
Desktop App (Beta)
Tessera Desktop provides a full-featured graphical interface for managing your engineering artifacts. The desktop app is currently in beta.
Download the latest desktop release for your platform from GitHub Releases:
| Platform | Download |
|---|---|
| Windows (x64) | tessera-desktop-windows-x64.msi or .exe |
| macOS (Apple Silicon) | tessera-desktop-macos-arm64.dmg |
| macOS (Intel) | tessera-desktop-macos-x64.dmg |
| Linux (x64) | tessera-desktop-linux-x64.AppImage or .deb |
Features:
- Visual entity management with forms and tables
- Risk analytics dashboard with FMEA worksheet
- Traceability matrix visualization
- BOM cost and mass rollup
- Git integration for version control
Note: The desktop app works with the same project structure as the CLI. You can use both interchangeably.
Quick Start
# Initialize a new project
# Create a requirement
# List all requirements (shows REQ@N short IDs)
# Show a specific requirement using short ID
# Create a risk
# Validate all project files
Short IDs
After running list commands, Tessera assigns entity-prefixed short IDs (REQ@1, RISK@1, etc.) to entities:
# Use prefixed short IDs instead of full IDs
Short IDs are persistent per entity type - the same entity keeps its short ID across list commands.
This enables cross-entity linking (e.g., linking REQ@1 to TEST@1).
Quick Start Workflows
Common multi-step tasks made easy:
Record a Test Result
Close an NCR
Verify a CAPA
Analyze Component Interactions
Risk Assessment Review
Manufacturing Process Review
Project Structure
After tdt init, your project will have:
.tdt/
βββ config.yaml # Project configuration
βββ cache.db # SQLite cache (auto-generated on first query)
βββ schema/ # JSON schemas (auto-generated)
βββ archive/ # Archived entities (from `tdt <entity> archive`)
requirements/
βββ inputs/ # Design inputs (customer requirements)
βββ outputs/ # Design outputs (specifications)
risks/
βββ hazards/ # Hazard definitions
βββ design/ # Design risks
βββ process/ # Process risks
βββ use/ # Use risks
βββ software/ # Software risks
bom/
βββ assemblies/ # Assembly definitions
βββ components/ # Component definitions
βββ suppliers/ # Approved supplier list
βββ quotes/ # Supplier quotes
tolerances/
βββ features/ # Feature tolerances
βββ mates/ # Mating features
βββ stackups/ # Tolerance stackups
verification/
βββ protocols/ # Verification test protocols
βββ results/ # Test results
validation/
βββ protocols/ # Validation protocols
βββ results/ # Validation results
manufacturing/
βββ processes/ # Manufacturing process definitions
βββ controls/ # Control plan items (SPC, inspection)
βββ work_instructions/ # Operator procedures
βββ lots/ # Production lots/batches
βββ deviations/ # Process deviations
βββ ncrs/ # Non-conformance reports
βββ capas/ # Corrective/preventive actions
Entity Types
| Prefix | Entity | Description |
|---|---|---|
| REQ | Requirement | Design inputs and outputs |
| HAZ | Hazard | Hazard definition |
| RISK | Risk | Risk / FMEA item |
| TEST | Test | Verification or validation protocol |
| RSLT | Result | Test result / execution record |
| TOL | Tolerance | Tolerance stackup |
| MATE | Mate | Feature mate (for stackups) |
| ASM | Assembly | Assembly definition |
| CMP | Component | Component definition |
| FEAT | Feature | Feature (on a component) |
| PROC | Process | Manufacturing process definition |
| CTRL | Control | Control plan item (SPC, inspection) |
| WORK | Work Instruction | Operator procedures |
| LOT | Lot | Production lot / batch |
| DEV | Deviation | Process deviation |
| NCR | Non-Conformance | Non-conformance report |
| CAPA | CAPA | Corrective/preventive action |
| QUOT | Quote | Quote / cost record |
| SUP | Supplier | Approved supplier |
Output Formats
Use -o/--output to control output format:
Commands
Project Management
Configuration
Configuration is layered (highest priority first):
- Environment variables (
TDT_AUTHOR,TDT_EDITOR) - Project config (
.tdt/config.yaml) - Global user config (
~/.config/tdt/config.yaml)
Global Search
Recent Activity
Tags
Requirements
Risks (FMEA)
Tests (Verification/Validation)
Test Results
Components (BOM)
Assemblies (BOM)
Suppliers (Approved Vendors)
Quotes (Supplier Quotations)
Features (Tolerances)
Mates (Tolerances)
Stackups (Tolerance Analysis)
Manufacturing Processes
Process types: machining, assembly, inspection, test, finishing, packaging, handling, heat_treat, welding, coating
Control Plan Items (SPC, Inspection)
Control types: spc, inspection, poka-yoke, visual, functional-test, attribute
Work Instructions
Non-Conformance Reports (NCRs)
|
NCR types: internal, supplier, customer
Severity levels: minor, major, critical
Categories: dimensional, cosmetic, material, functional, documentation, process, packaging
Corrective/Preventive Actions (CAPAs)
CAPA types: corrective, preventive
Source types: ncr, audit, customer_complaint, trend_analysis, risk
Link Management
Traceability
| Where-Used Queries
Reports
Risk Summary
Project Status Dashboard
Version Control (Git Wrappers)
# History - view git history for an entity
# Blame - view git blame for an entity
# Diff - view git diff for an entity
Baselines (Git Tags)
Bulk Operations
# Set status on multiple entities
# Add/remove tags
# Set author
# Dry run (preview changes without modifying)
Unix Pipeline Support
Bulk commands read entity IDs from stdin, enabling Unix-style pipelines:
# Pipe from list commands
|
|
|
# Combine with standard Unix tools
| |
| |
# Chain multiple operations
|
This works with all entity types and all bulk commands (set-status, add-tag, remove-tag, set-author).
Cross-Entity Filtering (--linked-to)
Every list command supports --linked-to to filter entities by their links to other entities. Combine with - to read IDs from stdin for powerful pipe composition:
# Show all NCRs linked to a specific component
# Pipe component IDs to find all linked NCRs
|
# Find tests linked to approved requirements
|
# Show risks linked to components in an assembly's BOM
|
# Filter by link type with --via
# Pipe multiple IDs to trace commands
|
|
The --linked-to flag accepts comma-separated IDs, short IDs, or - for stdin. The optional --via flag filters by a specific link type (e.g., verified_by, satisfied_by, mitigated_by).
SysML v2 Interchange
Export project data to SysML v2 textual notation for use with MBSE tools, or import SysML v2 files to create Tessera entities.
# Export all requirements, tests, components, and results to SysML v2
# Import from a SysML v2 file
Export generates SysML v2 textual notation with:
requirement defblocks for requirements withdocand@TdtMetadataannotationsverification defblocks for tests with@VerificationMethodandobjectivelinkingpart defblocks for componentssatisfy requirement : X by Y;relationships fromsatisfied_bylinks- Test results as structured comments with verdict and execution date
Import parses SysML v2 and creates Tessera entity YAML files with:
- Round-trip ID preservation (TDT entity IDs in SysML short IDs are reused)
- Bidirectional link restoration (
verifies/verified_by,satisfied_by) - Metadata recovery from
@TdtMetadataannotations (status, author, category, tags)
Example Workflows
Tessera is more than requirements tracking. Here are some powerful workflows:
Tolerance Stackup Analysis
Define features on components, create mates, and run worst-case, RSS, and Monte Carlo analysis:
# Create a component
|
# Add features with tolerances
| |
# Create a mate to analyze fit
)
# Create a tolerance stackup
)
# Run Monte Carlo analysis
)
|
|
)
|
FMEA Risk Management
Track design and process risks with full FMEA methodology:
# Create a risk with FMEA ratings
)
# View risks sorted by RPN
)
Manufacturing Quality Loop
Define processes, controls, and track quality issues through to resolution:
# Define a manufacturing process
|
# Add an SPC control point
|
# Create work instructions
# Log a non-conformance
| |
# Create corrective action linked to NCR
|
Full Traceability
Link requirements to tests, risks to mitigations, and generate coverage reports:
# Link a requirement to a test
# Check verification coverage
# Find orphaned entities
)
)
)
Supply Chain Management
Track suppliers, quotes, and compare pricing:
# Create a supplier
# Add a quote for a component
|
|
# Compare quotes for a component
SysML v2 Round-Trip
Export your project to SysML v2 for review in MBSE tools, then import changes back:
# Export current project state
# Share with SysML tools, make edits, then re-import
# Verify imported entities
Note: For complete YAML schema documentation and field references, see the individual entity docs in the docs/ directory.
Manufacturing Quality Loop
Tessera supports the complete manufacturing quality loop:
ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ
β PROC ββββββΆβ CTRL ββββββΆβ WORK β
β (Process) β β (Control) β β (Work Inst) β
ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ
β β β
β βΌ β
β ββββββββββββββββ β
β β NCR ββββββββββββββ
β β (Non-Conf) β
β ββββββββββββββββ
β β
β βΌ
β ββββββββββββββββ
ββββββββββββββΆβ CAPA β
β (Corrective)β
ββββββββββββββββ
- PROC defines what manufacturing operations to perform
- CTRL defines how to monitor/control the process (SPC, inspection)
- WORK provides step-by-step instructions for operators
- NCR captures quality issues found during manufacturing
- CAPA drives systematic improvement back to processes
Tolerance Format
Tessera uses plus_tol and minus_tol fields instead of the Β± symbol (which is hard to type):
# Correct: 10.0 +0.1/-0.05
dimensions:
- name: "diameter"
nominal: 10.0
plus_tol: 0.1 # Positive deviation allowed
minus_tol: 0.05 # Negative deviation allowed (stored as positive number)
Both values are stored as positive numbers. The actual tolerance range is:
- Maximum:
nominal + plus_tol= 10.1 - Minimum:
nominal - minus_tol= 9.95
Validation
Tessera validates files against JSON Schema with detailed error messages:
error[tessera::schema::validation]: Schema validation failed
--> requirements/inputs/REQ-01HC2.tdt.yaml:8:1
|
8 | status: pending
| ^^^^^^^^^^^^^^^ Invalid enum value
|
help: Valid values: draft, review, approved, released, obsolete
Status Workflow
draft β review β approved β released
β β
obsolete β β β β
| Status | Description |
|---|---|
| draft | Initial creation, still being written |
| review | Ready for stakeholder review |
| approved | Signed off and baselined |
| released | Released to production/manufacturing |
| obsolete | No longer applicable |
Priority Levels
| Priority | Use For |
|---|---|
| critical | Safety, regulatory, blocking requirements |
| high | Core functionality, key differentiators |
| medium | Standard features, quality of life |
| low | Nice to have, future considerations |
Risk Assessment (FMEA)
Tessera uses FMEA (Failure Mode and Effects Analysis) methodology:
FMEA Ratings (1-10 scale)
| Factor | 1 | 10 |
|---|---|---|
| Severity | Minimal impact | Catastrophic, safety hazard |
| Occurrence | Very unlikely | Almost certain |
| Detection | Always detected | Cannot be detected |
Risk Priority Number (RPN)
RPN = Severity x Occurrence x Detection (range: 1-1000)
| RPN Range | Risk Level | Action |
|---|---|---|
| 1-50 | Low | Monitor, no immediate action needed |
| 51-150 | Medium | Plan mitigations, track progress |
| 151-400 | High | Prioritize mitigations, escalate |
| 401+ | Critical | Immediate action required |
Mitigation Types
| Type | Purpose |
|---|---|
| prevention | Reduces occurrence probability |
| detection | Improves ability to detect before failure |
Test Engineering
Verification vs Validation
| Type | Purpose | Question |
|---|---|---|
| Verification | Did we build it right? | Confirms design outputs meet inputs |
| Validation | Did we build the right thing? | Confirms product meets user needs |
V-Model Test Levels
| Level | Tests Against | Scope |
|---|---|---|
| Unit | Detailed design | Individual components |
| Integration | Architecture design | Component interactions |
| System | System requirements | Complete system |
| Acceptance | User needs | End-user scenarios |
IADT Methods
Tests can use different verification methods (Inspection, Analysis, Demonstration, Test):
| Method | Description | When to Use |
|---|---|---|
| Inspection | Visual examination | Workmanship, labeling, documentation |
| Analysis | Calculation/simulation | Complex systems, safety-critical |
| Demonstration | Show functionality | User interface, simple operations |
| Test | Measured execution | Performance, environmental, stress |
Tolerance Analysis
Tessera supports four analysis methods for tolerance stackups:
Worst-Case Analysis
Assumes all dimensions are at their worst-case limits simultaneously:
- Min result: All positive contributors at minimum, all negative at maximum
- Max result: All positive contributors at maximum, all negative at minimum
- Conservative but often overly pessimistic
RSS (Root Sum Square) Analysis
Statistical analysis assuming normal distributions:
- Calculates mean and 3Ο spread
- Computes Cpk (process capability index)
- Estimates yield percentage
- More realistic than worst-case for multi-contributor stacks
| Cpk | Yield | Quality Level |
|---|---|---|
| 0.33 | 68.27% | Poor |
| 0.67 | 95.45% | Marginal |
| 1.0 | 99.73% | Capable |
| 1.33 | 99.99% | Good |
| 1.67 | 99.9997% | Excellent |
| 2.0 | 99.9999% | Six Sigma |
Monte Carlo Simulation
Runs thousands of random samples:
- Supports normal, uniform, and triangular distributions
- Provides actual yield percentage
- Reports 95% confidence interval (2.5th to 97.5th percentile)
- Default: 10,000 iterations
3D SDT Analysis (Small Displacement Torsor)
Full 3D tolerance analysis using torsor theory:
- 6-DOF Torsors: 3 translations (u, v, w) + 3 rotations (Ξ±, Ξ², Ξ³) per feature
- Jacobian Propagation: Transform deviations through kinematic chains with 6Γ6 matrices
- Geometry Classes: Plane, Cylinder, Sphere, Cone - each with invariance constraints
- ASME Y14.5 Integration: Works with standard GD&T controls (position, perpendicularity, etc.)
- Datum Reference Frames: Supports A, B, C datum hierarchy
- Braille Visualization: Terminal-based chain schematics and deviation ellipses
# Run 1D analysis with default iterations
# Run with more iterations for higher confidence
# Run 3D SDT analysis (requires features with geometry_3d)
# 3D analysis with braille visualization
# 3D Monte Carlo simulation
Test Verdicts
| Verdict | Meaning | Follow-up |
|---|---|---|
| pass | All criteria met | None required |
| fail | One or more criteria not met | Action items required |
| conditional | Passed with deviations | Document justification |
| incomplete | Could not complete test | Reschedule |
| not_applicable | Test not applicable | Document rationale |
Best Practices
Writing Requirements
- Use "shall" for mandatory requirements
- Use "should" for recommended requirements
- Use "may" for optional requirements
- Be specific and testable
- One requirement per file
Organizing Requirements
- Use categories to group related requirements
- Use tags for cross-cutting concerns
- Separate inputs from outputs in different directories
- Link related requirements with
satisfied_byrelationships
License
MIT License
Copyright (c) 2024 Tessera Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Disclaimer
This software is provided for informational and educational purposes. While Tessera can help organize engineering documentation, it is not a substitute for professional engineering judgment, certified quality management systems, or regulatory compliance tools.
Users are responsible for:
- Validating that outputs meet their specific requirements
- Ensuring compliance with applicable regulations and standards
- Maintaining appropriate backup and version control practices
- Performing independent verification of safety-critical calculations
Tessera is not certified for use in regulated industries (medical devices, aerospace, automotive safety systems, etc.) without independent validation by qualified professionals.