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 -P title="System must support 1000 users"
rela create decision -P 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

Document	Description
Getting Started	Installation, first project, core workflow
Concepts	Architecture traceability fundamentals
CLI Reference	Complete command reference
Metamodel Reference	Configure entity types and relations
Export Guide	Export, import, and data integration
Best Practices	Maintenance tips and team workflows
MCP Server	AI assistant integration via MCP
Data Entry Web App	Config-driven web UI for entity management
Lua Scripting	Programmable automation with embedded Lua
Encrypting a rela repo with git-crypt	Use git-crypt for confidentiality when pushing to untrusted git hosts
Scheduled Tasks	Run Lua scripts on recurring schedules
Audit Log	Forensic JSONL log of every entity / relation write
PostgreSQL Backend	Run rela-server and the CLI against PostgreSQL instead of markdown files
Attachment Security: Scanning, MIME Allowlist & Transforms	Virus scanning, a sniffed MIME allowlist, and byte transforms for uploaded attachments
Sync	Two-way sync between a local fsstore project and a remote pgstore rela-server
Security model for rela-server	Threat model, HTTP defenses, audit attribution, and residual risks for the rela-server data-entry app; how its read-side ACL coverage stands today.
ACL: Authorization Overview	How rela's role-based authorization works end-to-end: from acl.yaml + the graph to a write decision and its audit attribution
ACL: Security Hardening	Operator's hardening guide for rela's ACL system: group membership trust, fail-loud boot, audit-isolation invariants
Generated documentation: the rela docs language	Author a deployment manual in Markdown with embedded Lua islands that pull reference fragments (field tables, enum meanings, mermaid lifecycles, relation graphs, role matrices) straight from the schema.

Tutorials

Tutorial	Description
Tutorial: Building an ISO 27001 ISMS with Rela	Build a complete Information Security Management System
Tutorial: Hybrid Project Management with Rela	Build a hybrid project management system

Scenarios

Scenario	Description
Scenario: DevOps/SRE Runbooks & Infrastructure Operations	DevOps/SRE runbooks and infrastructure operations
Scenario: ISO 27001 Information Security Management System	ISO 27001 Information Security Management System
Scenario: Hybrid Project Management	Hybrid project management documentation

Examples

Example	Description
Ticket tracker — operator handbook	A generated operator handbook for the demo ticket tracker, built by rela-docs — field tables, a mermaid lifecycle, a role matrix, and an annotated screenshot, all derived from the project's schema so they can't drift.

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.