katalyst-taxonomy 1.4.1

A taxonomy management system for software architecture

Katalyst Taxonomy

Define, organize, and manage your software architecture as code.

Katalyst Taxonomy is a declarative framework for modeling your infrastructure and organization as a hierarchical tree. The System Wing organizes systems (which can nest), stacks, and layers; the Org Wing tracks organizations, programs, projects, teams, and team members. It brings structure to complex architectures, enabling consistent scaffolding, automated discovery, and seamless CI/CD integration.

---

Why Katalyst?

Modern software architectures sprawl across hundreds of services, each with their own conventions, configurations, and tribal knowledge. Teams struggle with:

• Inconsistent naming - Every service structured differently
• Lost knowledge - New team members can't discover what exists
• Manual scaffolding - Copy-paste leads to drift and errors
• Fragile automation - CI/CD pipelines hardcode paths and assumptions

Katalyst solves these problems by providing a single source of truth for your architecture, expressed as simple YAML files that both humans and tools can understand.

Learn more about why Katalyst

---

Key Features

Feature	Description
Hierarchical Modeling	Technical (System > Stack > Layer), Portfolio (Organization > Program > Project), and Organizational (Organization > Team > Team Member) hierarchies
Declarative YAML	Simple, version-controlled architecture definitions
Schema Validation	Catch errors early with JSON Schema validation
Scaffolding Templates	Generate consistent project structures from layer types
Interactive TUI	Browse and manage your taxonomy visually
Environment-Aware	First-class support for dev/staging/prod environments
Extensible Plugins	57 bundled actions, 12 tools, 4 layer types — extend with your own
Git Hook Integration	Map kata actions to pre-commit, Husky, or Lefthook hooks
AI Agents & Skills	Bundled AI coding assistants with taxonomy-aware context
Graph Database Export	Export taxonomy to Neo4j for visualization, impact analysis, and dependency queries (kata tax export neo4j)
PostgreSQL Export	Export taxonomy to PostgreSQL for SQL analytics, BI dashboards, and recursive CTE queries (kata tax export postgres)
Unified Backend Protocol	Pluggable storage backends (filesystem, Neo4j, PostgreSQL) with kata tax sync for multi-backend mirroring
MCP Server	Model Context Protocol server for AI assistant integration (30 tools, 6 resources, 3 prompts)
Template Registry	Register organization template repos; discover and merge remote templates alongside bundled ones (kata tax registry)

---

Storage Backends

Katalyst is designed to meet teams where they are. Not every team needs a database — many just need architecture-as-code in git.

Filesystem (default, zero infrastructure)

Taxonomy nodes are YAML files checked into git. No database required. Every change is a commit, every review is a PR, and the taxonomy is readable directly on GitHub or GitLab. This is the recommended starting point and works for most teams.

pip install katalyst-taxonomy
kata tax init --yes
kata tax tree

Neo4j (graph visualization, impact analysis)

When a taxonomy grows beyond what's easy to reason about in flat files, sync it to Neo4j for interactive graph exploration, impact analysis ("what breaks if I remove this stack?"), and cross-wing queries across 15 semantic relationship types.

pip install katalyst-taxonomy[neo4j]
kata tax export neo4j --full --uri neo4j://localhost:7687 --password secret --path .

PostgreSQL (SQL analytics, BI integration)

For organizations that need taxonomy data in dashboards, reports, or backing an API layer. Standard SQL access, recursive CTEs for hierarchy queries, JSONB filtering on metadata, and compatibility with any BI tool.

pip install katalyst-taxonomy[postgres]
kata tax export postgres --dsn postgresql://user:pass@localhost:5432/katalyst --path .

Using Multiple Backends Together

The filesystem stays the source of truth. Databases are synced mirrors. Edit YAML in git, sync periodically:

kata tax sync --full     # Push filesystem -> all configured backends
kata tax sync --target neo4j  # Sync to specific backend

---

Quick Start

Install in Your Repository

# Install Katalyst (requires Python 3.12+)
pip install katalyst-taxonomy

# Initialize a new taxonomy in your repo
kata tax init --yes

# See what was created
kata tax tree

Create Your First Architecture

# Create a system (root of your architecture)
kata tax create system my-platform \
  -d "My application platform" \
  -O [e-mail] \
  -e dev -e prod

# Create a nested system (logical grouping)
kata tax create system backend \
  --parent my-platform \
  -d "Backend services" \
  -O [e-mail] \
  -e dev -e prod

# Create a stack (deployable component)
kata tax create stack api \
  --parent backend \
  -d "REST API service" \
  -O [e-mail] \
  -e dev -e prod

# Create a layer with scaffolding
kata tax create layer app \
  --parent api \
  --parent-system backend \
  --parent-system my-platform \
  --layer-type app-docker \
  -d "API application container" \
  -O [e-mail] \
  -e dev -e prod

# View your taxonomy
kata tax tree

Output:

my-platform [system]
 backend [system]
    api [stack]
       app [layer]

Explore Interactively

# Launch the terminal UI
uv run python -m katalyst_taxonomy.tui

# Keyboard: arrows to navigate, 'n' to create, 'c' to clone, 'q' to quit

---

Documentation

Guide	Description
Why Katalyst	Value proposition and use cases
Getting Started	Installation and first taxonomy
Core Concepts	Hierarchy, FQTNs, environments
CLI Reference	Complete command documentation
TUI Guide	Interactive terminal interface
Agents & Skills	AI coding assistants for your taxonomy
Layer Types	Built-in scaffolding templates

For Plugin Developers

Guide	Description
Plugin Architecture	How plugins work
Creating Layer Types	Custom scaffolding templates
Creating Actions	Executable layer commands

For Contributors

Guide	Description
Contributing Guide	How to contribute
Architecture	Codebase design
Development Setup	Local environment

---

CLI Commands

# View commands
kata tax tree                    # Hierarchical tree view
kata tax list                    # Detailed list by type
kata tax json                    # Export as JSON
kata tax get <name>              # Get specific node

# Management
kata tax init                    # Initialize taxonomy in repo
kata tax create <type> <name>    # Create new node
kata tax add --layer-type <name> # Add layer type templates
kata tax remove --layer-type <n> # Remove layer type
kata tax upgrade                 # Upgrade installed components
kata tax upgrade --item <name>   # Upgrade a specific item

# Validation
kata tax lint                    # Validate against schemas
kata tax status                  # Show installed components

# AI Agents
kata tax agents init             # Initialize .agents/ and seed bundled agents/skills
kata tax agents list             # List agents and skills (local + bundled)
kata tax agents create <name>    # Create new agent
kata tax agents generate         # Generate from templates
kata tax agents sync             # Sync bundled content after upgrades
kata tax agents validate         # Validate definitions

# File Resolution
kata tax resolve --files <path>...  # Map files to layer FQTNs

# Git Hooks
kata tax hooks detect-tool           # Show configured hook tool
kata tax hooks generate --tool <t>   # Generate native hook config
kata tax hooks run                   # Run actions on affected layers
kata tax hooks validate              # Validate hook config

# Graph Export
kata tax export neo4j                    # Incremental sync to Neo4j
kata tax export neo4j --full             # Full export (clear + recreate)
kata tax export neo4j --dry-run          # Preview what would be exported
kata tax export postgres                 # Export to PostgreSQL
kata tax export postgres --full          # Full export (truncate + recreate)
kata tax export postgres --dry-run       # Preview what would be exported

# Backend Sync
kata tax sync                            # Sync taxonomy to backend mirrors
kata tax sync --dry-run                  # Preview sync operations
kata tax sync --full                     # Full sync (clear + recreate)

# Template Registry
kata tax registry add <uri>              # Register a template source
kata tax registry list                   # List registered sources
kata tax registry list --packages        # Show available packages
kata tax registry remove <uri>           # Unregister a source
kata tax registry sync                   # Force refresh cached manifests
kata tax registry show <uri>             # Show source details

---

Built-in Layer Types

Type	Description
app-docker	Docker container application with multi-stage build
k8s-kustomize	Kubernetes manifests with Kustomize overlays
k8s-argocd	Argo CD application with GitOps workflow
iac-terragrunt	Terraform modules with Terragrunt wrapper

Add more with kata tax add --layer-type <name> or create your own.

---

Project Structure

After kata tax init, your repository will have:

your-repo/
 .global/
    taxonomy/
       taxonomy.lock    # Tracks installed components
       layer_types/           # Layer type templates
          app-docker/
          k8s-kustomize/
          ...
       actions/               # Action definitions + Just recipes
        extensions/            # Extension plugins
       capabilities/          # Capability declarations
       cicd/                  # CI/CD templates
 .agents/                        # AI agent definitions
    agents.yaml                 # Configuration
    agents/                     # Agent .md files
    skills/                     # Skill packages
 .taxignore                   # Paths to exclude from discovery

Your taxonomy nodes live alongside your code:

your-repo/
 system.yaml                  # System definition
 backend/
    system.yaml              # Nested system definition
    api/
       stack.yaml            # Stack definition
       app/
          layer.yaml         # Layer definition
          Dockerfile         # Scaffolded from layer type
          base/
          dev/

---

Development

# Clone and install
git clone https://github.com/esimplicityinc/katalyst-taxonomy.git
cd katalyst-taxonomy
uv sync

pip install katalyst-taxonomy[neo4j]  # Enable Neo4j graph export
pip install katalyst-taxonomy[postgres]  # Enable PostgreSQL export
pip install katalyst-taxonomy[export]    # Enable all export backends

# Run tests
uv run pytest

# Run linters
uv run ruff check
uv run pyright

# Run CLI
uv run kata --help

# Run TUI
uv run python -m katalyst_taxonomy.tui --path .

# Rebuild type registry (after editing node_types/)
uv run kata tax build-types

---

License

MIT License

---

Links

• Documentation
• GitHub Issues
• Schema Reference