Universal Infrastructure Documentation

A comprehensive monorepo for generating topology documentation across multiple infrastructure domains, with seamless Obsidian vault integration.

Overview

This repository contains specialized documentation generators for different infrastructure types:

• Audio Systems - Signal flow, devices, and audio routing topology
• Video Systems - Video routing, displays, and distribution infrastructure
• Lighting Systems - DMX/RDM networks, fixtures, and control topology
• Network Infrastructure - Switches, routers, access points, and network connectivity

All packages share a common core library that provides:

• YAML-based input parsing and validation
• Mermaid diagram generation
• Obsidian vault integration
• Standardized topology modeling

Architecture

infra-docs/
├── packages/
│   ├── core/          # Shared infrastructure documentation core
│   ├── audio/         # Audio topology documentation (51 tests)
│   ├── video/         # Video topology documentation (81 tests)
│   ├── lighting/      # Lighting/DMX topology documentation (99 tests)
│   └── network/       # Network topology documentation (7 tests)
└── package.json       # Workspace root configuration

Package Details

@infra-docs/core

Core library providing shared functionality for all domain-specific packages:

• Type-safe input validation with Zod
• YAML parsing and processing
• Mermaid diagram generation
• Obsidian vault integration
• Extensible topology modeling

@infra-docs/audio

Audio system topology documentation generator supporting:

• Audio devices (mixers, interfaces, speakers, etc.)
• Signal flow and routing
• Connection types (XLR, TRS, Dante, etc.)
• Group and room organization

@infra-docs/video

Video system topology documentation generator supporting:

• Video devices (cameras, displays, switchers, etc.)
• Video routing and distribution
• Connection types (HDMI, SDI, NDI, etc.)
• Multi-source and multi-display configurations

@infra-docs/lighting

DMX/lighting system topology documentation generator supporting:

• Lighting fixtures and controllers
• DMX universes and addressing
• Control protocols (sACN, Art-Net)
• Fixture groups and zones

@infra-docs/network

Network infrastructure topology documentation generator supporting:

• Network devices (switches, routers, APs, etc.)
• Port connections and VLANs
• IP addressing and subnets
• UniFi integration

Installation

This project uses Bun as the package manager and runtime.

# Install Bun if you haven't already
curl -fsSL https://bun.sh/install | bash

# Clone the repository
git clone <repository-url>
cd infra-docs

# Install all dependencies
bun install

Development

Running Tests

# Run all tests across all packages
bun test

# Run tests for a specific package
cd packages/audio && bun test

# Watch mode
bun test:watch

Type Checking

# Type check all packages
bun run type-check

# Type check specific package
cd packages/core && bun run type-check

Building

# Build all packages
bun run build

# Build specific package
cd packages/lighting && bun run build

Usage

Each package provides a CLI tool for generating documentation:

Audio Documentation

cd packages/audio
bun cli/index.ts --input path/to/audio.yaml --output path/to/output

Video Documentation

cd packages/video
bun cli/index.ts --input path/to/video.yaml --output path/to/output

Lighting Documentation

cd packages/lighting
bun cli/index.ts --input path/to/lighting.yaml --output path/to/output

Network Documentation

cd packages/network
bun cli/index.ts --input path/to/network.yaml --output path/to/output

Input Format

Each domain uses YAML input files with domain-specific schemas. All packages support:

• Device definitions with metadata
• Connection and routing information
• Grouping and organization
• Obsidian vault integration settings

Example input files and schemas are available in each package's documentation.

Output Formats

All generators produce:

• Mermaid Diagrams - Visual topology representations
• Markdown Documentation - Detailed device and connection information
• Obsidian Notes - Optional vault integration with proper linking

Workspace Commands

# Install all dependencies
bun install

# Run tests across all packages
bun test

# Type check all packages
bun run type-check

# Build all packages
bun run build

# Clean all build artifacts and node_modules
bun run clean

Test Coverage

Current test coverage by package:

• Core: Comprehensive validation and diagram generation tests
• Audio: 51 test cases covering signal flow and routing
• Video: 81 test cases covering video routing scenarios
• Lighting: 99 test cases covering DMX and fixture configurations
• Network: 7 test cases covering basic connectivity

Contributing

1. Create a feature branch from main
2. Make your changes in the appropriate package
3. Add or update tests as needed
4. Ensure all tests pass: bun test
5. Ensure type checking passes: bun run type-check
6. Submit a pull request

License

MIT

Author

BAIB