Architecture-agnostic Go backend scaffolding and package management system

Vandor is a comprehensive ecosystem for building production-ready Go backends with a focus on:

• 🏗️ Architecture Flexibility - Support for multiple architecture patterns (Hexagonal, EDA, Clean, Minimal)
• 📦 Package Management - VPKG system for reusable components
• 🎨 Interactive CLI - Beautiful TUI with Catppuccin themes
• 🧩 Domain-Driven Design - Business capability-focused domain organization
• 🚀 Developer Experience - Code generation, hot reload, comprehensive tooling

Using curl:

curl -fsSL https://raw.githubusercontent.com/alfariiizi/vandor/main/install.sh | bash

Using wget:

wget -qO- https://raw.githubusercontent.com/alfariiizi/vandor/main/install.sh | bash

Custom installation directory:

INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/alfariiizi/vandor/main/install.sh | bash

# Interactive wizard (recommended)
vandor init my-project

# Or use presets for quick setup
vandor init my-api --preset=web-api --non-interactive

If you prefer to build from source:

# Clone the repository
git clone https://github.com/alfariiizi/vandor.git
cd vandor

# Build the CLI
cd cli
go build -o vandor main.go

# Install (optional)
sudo mv vandor /usr/local/bin/

New to Vandor? Start with our comprehensive documentation navigation system:

For Users:

1. Installation Guide
2. Getting Started
3. Interactive Mode Guide

For Contributors:

1. CLAUDE.md - Project overview
2. TODO.md - Implementation roadmap
3. Architecture Decisions

For Architects:

1. Final Architecture Decisions
2. Domain Granularity Strategy
3. Architecture-Agnostic Structure

vandor/                            # Repository root
├── cli/                           # 🛠️ Vandor CLI Tool (main component)
│   ├── cmd/                       # CLI commands
│   ├── internal/                  # Generators, TUI, VPKG
│   └── README.md                  # CLI documentation
│
├── templates/                     # 📋 Project Templates
│   ├── base/                      # Minimal base template
│   └── hexagonal/                 # Hexagonal architecture template
│
├── test/                          # 🧪 Test Suite
│   ├── fixtures/                  # Generated test projects
│   ├── scripts/                   # Validation scripts
│   └── manual/                    # Manual test files
│
├── discussion/                    # 📖 Design Discussions
│   ├── architecture/              # 11 architecture decision docs
│   └── design/                    # VPKG and design philosophy
│
├── docs/                          # ✅ Project Documentation
│   ├── completed/                 # Completion reports
│   ├── current/                   # Active development docs
│   └── archive/                   # Historical decisions
│
└── guide/                         # 📚 User Guides
    ├── getting-started.md         # Complete beginner tutorial
    ├── installation.md            # Installation instructions
    └── interactive-mode-guide.md  # TUI wizard guide

Note: The reference backend implementation has been moved to a separate repository: github.com/alfariiizi/vandor-backend-template

• Interactive Project Init - Beautiful TUI wizard with Catppuccin themes
• Multiple Architecture Templates - Hexagonal, EDA, Clean, Minimal (v0.1 focuses on Hexagonal)
• VPKG Package System - Install infrastructure components on-demand
• Code Generators - Domain, use case, service, handler generators
• Domain Discovery - AI-powered and rule-based domain suggestions
• Task Runner - Integrated Taskfile support
• Theme System - Auto-detecting Catppuccin themes

• Reference Implementation - Available at vandor-backend-template
• Complete Stack - Ent.go, Huma v2, Chi, FX dependency injection
• Database Tools - Atlas migrations, Ent code generation
• Background Jobs - Asynq task queue integration
• Observability - OpenTelemetry, structured logging

• Extension Mechanism - Add HTTP, database, cache, messaging on-demand
• Two Package Types - fx-module (libraries) and cli-command (tools)
• Registry Support - Remote package discovery and installation
• Dependency Resolution - Automatic dependency management

All projects share the same top-level structure:

internal/
├── domain/              # Business capabilities
├── adapter/             # Infrastructure & transport
├── pkg/                 # Logger + config only
└── vpkg/                # Installed packages

Only the internal domain structure changes per architecture.

❌ Wrong: Table-based domains (user/, product/, order_item/)
✅ Right: Business capability domains (identity/, catalog/, order/)

Use Event Storming or business capability analysis to discover domains.

Base template includes ONLY:

• Logger
• Configuration
• Project structure

Everything else (HTTP, database, cache) is added via VPKG.

This supports:

• ✅ Web APIs
• ✅ CLI tools
• ✅ Event processors
• ✅ API gateways
• ✅ Background workers

Now (v0.1 Development):

• 🎯 Monorepo for easy coordination
• Single git clone
• Atomic commits across components

Current Organization:

• ✅ github.com/alfariiizi/vandor - CLI tool and templates
• ✅ github.com/alfariiizi/vandor-backend-template - Reference implementation

Future:

• Additional specialized templates in separate repositories

See REPOSITORY_STRATEGY.md for details.

Command-line tool for project scaffolding and management.

Key Commands:

vandor init <name>              # Initialize new project
vandor add domain <name>        # Add business capability domain
vandor add handler <path>       # Add HTTP handler
vandor vpkg add <package>       # Install VPKG package
vandor tui                      # Launch interactive mode
vandor sync all                 # Regenerate code

Hexagonal architecture reference implementation available at: github.com/alfariiizi/vandor-backend-template

Tech Stack:

• Go 1.24.1+
• Uber FX (dependency injection)
• Ent.go (database ORM)
• Huma v2 (HTTP framework)
• Asynq (background jobs)
• OpenTelemetry (observability)

Project templates for different architectures.

Available:

• Base (templates/base/) - Minimal foundation
• Hexagonal (templates/hexagonal/) - Ports & adapters

Planned (v0.2+):

• Event-Driven Architecture
• Clean Architecture
• Custom templates

• Go 1.24.1+
• Task (task runner)
• Air (hot reload - optional)
• Docker (for examples - optional)

# Build Vandor CLI
cd cli
go build -o vandor main.go
./vandor --version

# Test Vandor CLI
cd cli
go test ./...

# Run validation scripts
./test/scripts/validate_priority5.sh

• ✅ Hexagonal architecture template
• ✅ Interactive init wizard
• ✅ VPKG ecosystem
• ✅ Domain generators
• ✅ Testing infrastructure
• ✅ All 5 registry generators
• ✅ CLI bug fixes (8 critical issues)
• ✅ Architecture alignment (100%)
• ✅ Integration testing (100% success)
• ✅ Documentation (comprehensive quality reports)

• 🔲 Separate template repositories
• 🔲 Template discovery system
• 🔲 Custom template support
• 🔲 API Gateway template

• 🔲 CLI tool template
• 🔲 Event processor template
• 🔲 Worker template

• 🔲 Architecture migration tools
• 🔲 Multi-template monorepo
• 🔲 Cloud deployment integrations

See TODO.md for detailed progress tracking.

• Final Architecture Decisions ⭐⭐⭐
• Architecture-Agnostic Structure ⭐⭐
• Domain Granularity Strategy ⭐⭐
• Minimal Base Template ⭐⭐
• VPKG Design Philosophy ⭐

• CLAUDE.md - Project overview for AI assistants
• TODO.md - Implementation roadmap and progress
• REPOSITORY_STRATEGY.md - Monorepo strategy
• CLEANUP_PLAN.md - Repository organization

• Getting Started - Complete beginner tutorial
• Installation - Installation instructions
• Interactive Mode - TUI wizard guide
• VPKG Quick Start - Package system reference

Latest Reports (2025-11-02): See docs/quality/2025-11-02/

• Architecture Alignment - 100% compliance verification
• Integration Test Report - End-to-end testing results
• Fix Verification - Integration test fixes (100% success)
• Registry Generator Fixes - Handler & job registry fixes
• Daily Summary - Complete work overview
• Final Verification - System verification (23/23 tests)

We welcome contributions! Here's how to get started:

1. Understand the Architecture

   • Read CLAUDE.md
   • Read Architecture Decisions
   • Review TODO.md for current priorities

2. Pick a Task

   • Check TODO.md for open tasks
   • Look for Priority 1-2 tasks for v0.1
   • Check docs/current/ for active development

3. Make Your Changes

   • Follow Go best practices
   • Add tests for new features
   • Update documentation
   • Use conventional commits

4. Submit a PR

   • Ensure tests pass
   • Update TODO.md if needed
   • Add to docs/completed/ when done

Current Phase: v0.1.0 Released (100% complete - Production Ready)

What's Working:

• ✅ Hexagonal template generation
• ✅ Interactive init wizard
• ✅ VPKG package system
• ✅ Domain discovery
• ✅ Code synchronization
• ✅ Testing infrastructure
• ✅ Registry generators (all 5 working perfectly)
• ✅ Architecture alignment (100% compliance)
• ✅ Integration testing (100% success rate)
• ✅ CLI bug fixes (all 8 critical issues resolved)
• ✅ Complete end-to-end workflow verified

v0.1.0 Released:

• ✅ All core features implemented
• ✅ All critical bugs fixed
• ✅ Comprehensive testing complete (23/23 tests passed)
• ✅ Quality documentation (6 reports, 3,900+ lines)
• ✅ CHANGELOG.md and RELEASE_NOTES.md created
• ✅ FAQ and Troubleshooting guides added

Recent Improvements (2025-11-02):

• ✅ Fixed 8 critical CLI bugs
• ✅ Achieved 100% architecture alignment
• ✅ Fixed integration test issues (89% → 100% success)
• ✅ Fixed registry generator bugs (all 5 registries working)
• ✅ Complete system verification (23/23 tests passed)

See: Quality Reports for detailed documentation

See TODO.md for detailed status and roadmap.

• Documentation Hub: Documentation Index
• Architecture Decisions: discussion/architecture/
• User Guides: guide/
• Quality Reports: docs/
• Issue Tracker: GitHub Issues (coming soon)
• Discussions: GitHub Discussions (coming soon)

MIT License - See LICENSE file for details

Design Inspiration:

• shadcn/ui - Component ownership philosophy
• DDD Community - Domain-driven design patterns
• Go Community - Best practices and idioms

Technologies:

• Cobra - CLI framework
• Bubble Tea - TUI framework
• Catppuccin - Beautiful color themes
• Ent - Database ORM
• Huma - HTTP framework

Made with ❤️ for the Go community

• 📖 Documentation: Start with Documentation Index
• 🎓 Tutorial: Follow Getting Started Guide
• ⚡ Quick Ref: Check Quick Reference
• 🐛 Issues: GitHub Issues (coming soon)
• 💬 Discussions: GitHub Discussions (coming soon)

Happy coding! 🚀