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 Tests Docker

✨ Features

🤖 LLM-First Design - Design architecture conversationally with Claude, GPT, or Gemini via MCP
📝 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 static sites, PDFs, and markdown documentation
🔧 Powerful CLI - Scaffold, build, validate, and serve - all from the terminal
🐳 Docker Ready - Official images with all dependencies included
🎯 Zero Config - Smart defaults with optional customization via TOML
💰 Token Efficient - Progressive context loading + TOON format minimize LLM costs

🚀 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 (API)

# Start API server
loko api

# Trigger builds via HTTP
curl -X POST http://localhost:8081/api/v1/build

📚 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 (Optional)

TOON reduces tokens by 30-40% for structured data:

# JSON: ~380 tokens
{"systems":[{"name":"PaymentService","containers":["API","DB"]},...]}

# TOON: ~220 tokens
systems[4]{name,containers}:
  PaymentService,API|DB
  OrderService,API|DB
  ...

🎨 Features Deep Dive

Templates

loko includes built-in templates powered by ason:

Template Use Case
standard-3layer Traditional web apps (API → Service → Database)
serverless AWS Lambda architectures (API Gateway, SQS, DynamoDB) 
# Use default template (standard-3layer)
loko new system PaymentService

# Use serverless template for AWS Lambda architectures
loko new system "Order Processing API" -template serverless
loko new container "API Handlers" -parent order-processing-api -template serverless

Templates use ason's variable interpolation syntax for scaffolding. See ason documentation for template authoring.

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 pdf        # PDF documents (requires veve-cli)

Validation

loko validate
# Checks for:
# - Orphaned references
# - Missing required files
# - C4 hierarchy violations
# - Broken diagram syntax

🛠️ 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.

🤝 MCP Integration

loko exposes these tools for LLM interaction:

Tool Description
query_project Get project metadata
query_architecture Token-efficient architecture queries
create_system Scaffold new system
create_container Scaffold container
create_component Scaffold component
update_diagram Write D2 code to file
build_docs Build documentation
validate Check architecture consistency

Token-Efficient Queries

{
  "name": "query_architecture",
  "parameters": {
    "scope": "project | system | container",
    "target": "specific entity name",
    "detail": "summary | structure | full",
    "format": "json | toon",
    "include_diagrams": false
  }
}

📖 Documentation

🌟 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

Architecture

Reference

See the Documentation Index for the complete catalog.

🗺️ Roadmap

v0.1.0 (MVP) - In Progress

Foundation (Complete)

  • ✅ Clean Architecture with 18 port interfaces
  • ✅ Domain entities (Project, System, Container, Component) with tests
  • ✅ CLI framework (Cobra + Viper) with shell completions
  • ✅ Template system with standard-3layer and serverless templates

Current: Handler Refactoring + TOON Alignment (#005)

  • 🟡 Extract business logic from CLI/MCP handlers into use cases
  • 🟡 Align TOON encoder with official TOON v3.0 specification

Remaining

  • 🔲 Scaffolding use cases with ason template engine adapter
  • 🔲 D2 diagram rendering with caching
  • 🔲 HTML site generation with watch mode
  • 🔲 MCP server with token-efficient queries

v0.2.0

  • 📋 HTTP API server for CI/CD integration
  • 📋 PDF export via veve-cli
  • 📋 Multi-format export (HTML, Markdown, PDF)
  • 📋 Advanced validation rules

v0.3.0

  • 📋 Architecture graph visualization
  • 📋 Diff and changelog generation
  • 📋 Plugin system

See specs/ for detailed feature specifications.

🤲 Contributing

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

📜 License

MIT License - 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

No description, website, or topics provided.

Resources

Readme

Code of conduct

Code of conduct

Contributing

Contributing
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages