🪇 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.

✨ 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

Global templates (~/.loko/templates/) and project templates (.loko/templates/) powered by ason:

loko new system PaymentService
# Uses template: ~/.loko/templates/c4-system/

# Customize per-project
cp -r ~/.loko/templates/c4-system .loko/templates/custom-system
loko new system --template custom-system MyService

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:

simple-project - Minimal C4 documentation
3layer-app - Standard web → API → database
serverless - AWS Lambda architecture

🐳 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.23+
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.

🗺️ Roadmap

v0.1.0 (MVP) - Q1 2025

✅ CLI commands (init, new, build, serve, watch)
✅ MCP server with token-efficient queries
✅ D2 diagram rendering with caching
✅ HTML site generation
✅ Template system (ason integration)
✅ Clean Architecture implementation

v0.2.0 - Q2 2025

🚧 HTTP API server
🚧 TOON format support for MCP
🚧 PDF export via veve-cli
🚧 Advanced validation rules

v0.3.0 - Q3 2025

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

See ROADMAP.md for detailed feature plans.

🤲 Contributing

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

🐛 Bug reports → Open an issue
💡 Feature requests → Start a discussion
🔧 Pull requests → See CONTRIBUTING.md

📜 License

🙏 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." 🦋

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github		.github
.specify		.specify
docs/adr		docs/adr
internal/core/entities		internal/core/entities
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Makefile		Makefile
README.md		README.md
ROADMAP.md		ROADMAP.md
Taskfile.yml		Taskfile.yml
go.mod		go.mod
main.go		main.go

madstone-tech/loko

Folders and files

Latest commit

History

Repository files navigation