rela

Rela

A database layer on top of markdown. Define entities, link them together, and query their relationships—all stored as human-readable, version-controllable markdown files.

Rela is a schema-driven entity-graph platform. You define the shape of your domain in a YAML metamodel; rela gives you typed entities, typed relations between them, and a set of tools for querying, validating, analyzing, and presenting the resulting graph.

Common domains:

• Architecture & design — Link requirements to decisions to components
• Compliance & ISMS — Connect controls to evidence and audit findings
• Risk management — Trace risks through mitigations to controls
• Product development — Map features to user stories to tasks
• Knowledge bases — Relate concepts, documents, and references
• Project governance — Track goals through milestones to deliverables
• Issue tracking — Bugs, features, and tickets with their lifecycle

Traceability is one use case, not the identity. Anything with typed entities and typed relations fits. Rela handles the rest: ID generation, bidirectional linking, orphan detection, coverage analysis, validation rules, and graph export.

Quick Start

# Initialize a project
rela init

# Create entities
rela create requirement --title "System must support 1000 users"
rela create decision --title "Use PostgreSQL for persistence"

# Link them together
rela link DEC-001 addresses REQ-001

# View the relationship
rela show REQ-001

# Launch the interactive TUI
rela tui

# Work with a project in a different directory
rela -p /path/to/project list
export RELA_PROJECT=/path/to/project && rela list

Features

• Entity Management - Create, update, delete entities
• Relationship Tracing - Link entities and trace dependencies
• Quality Analysis - Find orphans, check coverage, detect gaps
• Graph Export - Export to Graphviz DOT format
• Interactive TUI - Full-featured terminal interface
• MCP Server - Expose rela to AI assistants via Model Context Protocol
• Markdown Storage - Human-readable, version-controllable files

Installation

go install github.com/Sourcehaven-BV/rela/cmd/rela@latest

Or build from source:

git clone https://github.com/Sourcehaven-BV/rela.git
cd rela
go build -o rela ./cmd/rela

Documentation

Tutorials

Scenarios

Project Structure

After running rela init:

your-project/
├── metamodel.yaml       # Entity types and relations config
├── entities/            # Markdown entity files (by type)
│   ├── requirements/
│   ├── decisions/
│   └── ...
├── relations/           # Markdown relation files
├── templates/           # Optional: templates for new entities/relations
│   ├── entities/        # One template per entity type
│   └── relations/       # One template per relation type
└── .rela/               # Cache (gitignored)

Core Traceability Chain

Requirement ──addresses──> Decision ──implements──> Solution ──realizes──> Component

Use rela analyze coverage to check for gaps in this chain.

License

AGPL-3.0 - See LICENSE for details.