Skip to content

madstone-tech/loko

BranchesTags

Repository files navigation

🪇 loko - Guardian of Architectural Wisdom

Transform complexity into clarity with C4 model documentation and LLM integration

loko (Papa Loko) is a modern architecture documentation tool that brings the C4 model to life through conversational design with LLMs, powerful CLI workflows, and beautiful documentation generation.

Go Version Release License CI Docker

✨ Features

🤖 LLM-First Design - 17 MCP tools for conversational architecture with Claude, GPT, or Gemini
📝 Direct Editing - Edit markdown and D2 diagrams in your favorite editor
⚡ Real-Time Feedback - Watch mode rebuilds in <500ms with hot reload
🎨 Beautiful Output - Generate HTML, Markdown, and TOON formats
🔧 Powerful CLI - Scaffold, build, validate, serve, and query — all from the terminal
🐳 Docker Ready - Official images with all dependencies included
🎯 Zero Config - Smart defaults with optional customization via TOML
💰 Token Efficient - 9.2% token savings with TOON format + progressive context loading
🔗 Relationship Graph - Live dependency graph from frontmatter + D2 arrow syntax (v0.2.0)
🧩 Smart Templates - Technology-aware component scaffolding (7 categories, v0.2.0)
🔍 Drift Detection - Catch inconsistencies between D2 diagrams and frontmatter (v0.2.0)

🚀 Quick Start

Installation

macOS / Linux (Homebrew)

brew tap madstone-tech/tap
brew install loko

Go Install

go install github.com/madstone-tech/loko@latest

Docker

docker pull ghcr.io/madstone-tech/loko:latest

Your First Architecture (2 minutes)

# Initialize a new project
loko init my-architecture
cd my-architecture

# Scaffold your first system
loko new system PaymentService

# Edit the generated files
vim src/PaymentService/system.md
vim src/PaymentService/system.d2

# Build and preview
loko serve
# Open http://localhost:8080

That's it! You now have a live-reloading documentation site.

🎯 Usage Modes

1️⃣ Conversational Design (LLM + MCP)

# Start MCP server
loko mcp

# In your LLM client (Claude, etc):
# "I'm building a payment processing system with an API and database"
# LLM uses loko to scaffold structure and create diagrams

2️⃣ Manual Editing (Developer Workflow)

# Watch for changes
loko watch &

# Edit files in your editor
vim src/PaymentService/system.d2

# Automatically rebuilds and refreshes browser

3️⃣ CI/CD Integration

# Validate architecture (with drift detection)
loko validate --strict --exit-code --check-drift

# Build documentation
loko build --format html,markdown,toon

See docs/guides/ci-cd-integration.md for GitHub Actions and GitLab CI examples.

🛠️ MCP Tools (17 Available)

loko provides 17 MCP tools for LLM-assisted architecture workflows:

Tool Description
query_project Get project metadata
query_architecture Token-efficient architecture queries (summary/structure/full)
search_elements Search by name, type, technology, or tags
find_relationships Find connections between elements
query_dependencies Find what a component depends on (direct + transitive)
query_related_components Find components related to a given component
analyze_coupling Measure coupling metrics across the architecture
create_system Scaffold new system
create_container Scaffold container
create_component Scaffold with technology-aware template + optional D2 preview
update_system Update system metadata
update_container Update container metadata
update_component Update component metadata
update_diagram Write D2 code to file
build_docs Generate HTML/Markdown/TOON docs (auto-populates component tables)
validate Check architecture consistency + optional drift detection
validate_diagram Verify D2 syntax

Note: find_relationships, query_dependencies, query_related_components, and analyze_coupling return live graph data as of v0.2.0.

Setup: See docs/guides/mcp-integration-guide.md for Claude Desktop configuration.

📚 Core Concepts

C4 Model Hierarchy

Context
  └── System
       └── Container
            └── Component

Project Structure

my-architecture/
├── loko.toml              # Configuration
├── src/                   # Source documentation
│   ├── context.md
│   ├── context.d2
│   └── SystemName/
│       ├── system.md
│       ├── system.d2
│       └── ContainerName/
│           ├── container.md
│           └── container.d2
└── dist/                  # Generated output
    └── index.html

Clean Architecture

loko follows Clean Architecture principles:

loko/
├── cmd/                        # CLI commands (thin layer)
│
├── internal/
│   ├── core/                   # THE HEART - zero external dependencies
│   │   ├── entities/           # Domain objects: Project, System, Container
│   │   ├── usecases/           # Application logic + port interfaces
│   │   └── errors/             # Domain-specific errors
│   │
│   ├── adapters/               # Infrastructure implementations
│   │   ├── config/             # TOML configuration
│   │   ├── filesystem/         # File operations
│   │   ├── d2/                 # Diagram rendering
│   │   ├── encoding/           # JSON + TOON encoders
│   │   └── html/               # Site builder
│   │
│   ├── mcp/                    # MCP server + tools
│   ├── api/                    # HTTP API server
│   └── ui/                     # Terminal UI (lipgloss)
│
├── templates/                  # Starter templates
└── docs/                       # Documentation + ADRs

💰 Token Efficiency

loko is designed to minimize LLM token consumption:

Progressive Context Loading

# Quick overview (~200 tokens)
query_architecture --detail summary

# System hierarchy (~500 tokens)
query_architecture --detail structure

# Full details for one system (variable)
query_architecture --detail full --target PaymentService

TOON Format

TOON v3.0 reduces tokens by 9.2% for structured data:

# Export architecture in token-efficient format
loko build --format toon

# Query with TOON format via MCP
query_architecture --format toon --detail summary

# Measured savings (5 systems, 15 containers):
# JSON: 4,550 tokens
# TOON: 4,131 tokens
# Savings: 9.2% (419 tokens)

See docs/guides/toon-format-guide.md for details.

🎨 Features Deep Dive

Technology-Aware Templates (v0.2.0)

loko new component auto-selects the best template based on the component's technology:

Category Example Technologies
compute AWS Lambda, Azure Functions, Cloud Run
datastore PostgreSQL, DynamoDB, Redis, MongoDB
messaging Kafka, SQS, RabbitMQ, SNS
api REST, GraphQL, gRPC, FastAPI
event EventBridge, Pub/Sub, Event Grid
storage S3, GCS, Azure Blob
generic (default fallback) 
# Auto-selected template based on technology
loko new component AuthService --parent api-service --technology "AWS Lambda"

# Preview the component's position in the container diagram
loko new component AuthService --parent api-service --preview

# Explicit override
loko new component AuthService --parent api-service --template datastore

See docs/guides/templates.md for the full mapping table and custom templates.

Relationship Graph (v0.2.0)

loko builds a live dependency graph by merging two sources:

# frontmatter (system.md or component.md)
relationships:
  - target: "DatabaseService"
    label: "Reads from"
    technology: "SQL"
# D2 arrow syntax (system.d2)
AuthService -> DatabaseService: Queries
# Query via CLI
loko query --relationships PaymentService

# Query via MCP
find_relationships --source "PaymentService/**"
query_dependencies --target "AuthService"

See docs/guides/relationships.md for frontmatter syntax and D2 conventions.

Drift Detection (v0.2.0)

Catch inconsistencies between your D2 diagrams and frontmatter metadata:

loko validate --check-drift
# WARNING  AuthService: D2 tooltip differs from frontmatter description
# ERROR    PaymentService: D2 arrow references non-existent component "OldService"
# Exit code 1 (errors found)

Severity levels: WARNING (description mismatches) and ERROR (orphaned references, missing components).

See docs/guides/data-model.md for the source-of-truth hierarchy.

Diagram Rendering

Powered by D2 with caching:

# src/System/system.d2
User -> API: Uses
API -> Database: Queries
loko render src/System/system.d2
# Generates: dist/diagrams/system.svg

Multi-Format Export

loko build --format html       # Static website
loko build --format markdown   # Single README.md
loko build --format toon       # Token-efficient TOON format

🛠️ Configuration

loko.toml (TOML format):

[project]
name = "my-architecture"
description = "System architecture documentation"

[paths]
source = "./src"
output = "./dist"

[d2]
theme = "neutral-default"
layout = "elk"
cache = true

[outputs.html]
enabled = true
navigation = "sidebar"
search = true

[build]
parallel = true
max_workers = 4

See docs/configuration.md for all options.

🌟 Examples

Check out examples/ for complete projects:

🐳 Docker

# Initialize project
docker run -v $(pwd):/workspace ghcr.io/madstone-tech/loko init my-arch

# Build documentation
docker run -v $(pwd):/workspace ghcr.io/madstone-tech/loko build

# Serve with hot reload
docker run -v $(pwd):/workspace -p 8080:8080 ghcr.io/madstone-tech/loko serve

🔧 Development

Prerequisites

  • Go 1.25+
  • d2 (required)
  • veve-cli (optional, for PDF)

Setup

git clone https://github.com/madstone-tech/loko
cd loko
go mod download
make test
go run main.go --help

See CONTRIBUTING.md for development guidelines.

📖 Documentation

Comprehensive documentation is available in the docs/ directory:

Getting Started

Guides

Reference

See the Documentation Index for the complete catalog.

🗺️ Roadmap

v0.1.0 (Released) ✅

  • Clean Architecture with 18 port interfaces
  • Domain entities (Project, System, Container, Component)
  • CLI framework (Cobra + Viper) with shell completions
  • Template system (standard-3layer, serverless project templates)
  • D2 diagram rendering with caching
  • HTML site generation with watch mode
  • MCP server (15 tools for LLM integration)

v0.2.0 (Released) ✅

  • Functional Relationship Graph: find_relationships, query_dependencies, query_related_components, analyze_coupling now return live data
  • Technology-Aware Templates: 7 component templates (compute, datastore, messaging, api, event, storage, generic); --template override
  • D2 Diagram Preview: loko new component --preview renders component position; MCP preview: true parameter
  • Auto-Generated Tables: {{component_table}} / {{container_table}} placeholders auto-populated in docs
  • Drift Detection: loko validate --check-drift with WARNING/ERROR severity and exit code 1 on errors
  • Coverage: Core package coverage improved from 58.1% to 80.7%

v0.3.0 (Future)

  • OpenAPI serving (Swagger UI at /api/docs)
  • Architecture diff and changelog generation
  • Plugin system
  • Multi-project support

🤝 Contributing

We welcome contributions! loko is building in public — see our development progress.

📜 License

Business Source License 1.1 - Copyright (c) 2025-2026 MADSTONE TECHNOLOGY

🙏 Acknowledgments

loko builds on excellent open-source tools:

  • D2 - Declarative diagramming
  • ason - Template scaffolding
  • TOON - Token-efficient notation
  • C4 Model - Architecture visualization approach
  • Cobra - CLI framework
  • Bubbletea - TUI framework

🪇 Why "loko"?

Papa Loko is the lwa (spirit) in Haitian Vodou who guards sacred knowledge, maintains tradition, and passes down wisdom to initiates. As the first houngan (priest), he is the keeper of the ritual knowledge that connects the physical and spiritual worlds.

Like Papa Loko, this tool acts as the guardian of your architectural wisdom — organizing knowledge, maintaining documentation traditions, and making complex systems understandable.

"Papa Loko, you're the wind, pushing us, and we become butterflies." 🦋

About

C4 architecture documentation tool with LLM integration via MCP — design systems conversationally, render D2 diagrams, generate beautiful docs

github.com/madstone-tech/loko

Topics

cli golang documentation mcp architecture devtools d2 diagrams c4-model llm

Resources

Readme

License

View license

Code of conduct

Code of conduct

Contributing

Contributing
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

v0.3.1 Latest
Feb 24, 2026
+ 2 releases

Packages

 
 
 

Contributors

Languages