Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/alfariiizi/vandor


https://github.com/alfariiizi/vandor

code-generator ddd-architecture go golang hexagonal-architecture vpkg vpkg-registry

Last synced: 3 months ago
JSON representation

Awesome Lists containing this project

README 

          
# Vandor Ecosystem



> **Architecture-agnostic Go backend scaffolding and package management system**



[![Go Version](https://img.shields.io/badge/Go-1.24.1+-00ADD8?style=flat&logo=go)](https://go.dev/)

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

[![Status](https://img.shields.io/badge/Status-v0.1%20Development-yellow)](TODO.md)



**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



---



## 🚀 Quick Start



### One-Line Installation



**Using curl:**

```bash

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

```



**Using wget:**

```bash

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

```



**Custom installation directory:**

```bash

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

```



### Initialize Your First Project



```bash

# Interactive wizard (recommended)

vandor init my-project



# Or use presets for quick setup

vandor init my-api --preset=web-api --non-interactive

```



### Build from Source (Alternative)



If you prefer to build from source:



```bash

# 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/

```



---



## 📚 Documentation



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



| Document | Purpose | Audience |

|----------|---------|----------|

| **[Documentation Index](docs/navigation/DOCUMENTATION_INDEX.md)** | 📖 Master index of all files | Everyone |

| **[Quick Reference](docs/navigation/QUICK_REFERENCE.md)** | ⚡ Quick reference card | Developers |

| **[Structure Guide](docs/navigation/STRUCTURE_GUIDE.md)** | 🌳 Visual tree structure | Explorers |

| **[Getting Started](guide/getting-started.md)** | 🎓 Complete tutorial | Beginners |

| **[Installation Guide](guide/installation.md)** | 💿 Installation guide | New users |

| **[VPKG Quick Start](guide/vpkg-quick-start.md)** | 📦 Package system guide | Developers |



### Learning Paths



**For Users:**

1. [Installation Guide](guide/installation.md)

2. [Getting Started](guide/getting-started.md)

3. [Interactive Mode Guide](guide/interactive-mode-guide.md)



**For Contributors:**

1. [CLAUDE.md](CLAUDE.md) - Project overview

2. [TODO.md](TODO.md) - Implementation roadmap

3. [Architecture Decisions](discussion/architecture/11-final-architecture-decisions.md)



**For Architects:**

1. [Final Architecture Decisions](discussion/architecture/11-final-architecture-decisions.md)

2. [Domain Granularity Strategy](discussion/architecture/05-domain-granularity-strategy.md)

3. [Architecture-Agnostic Structure](discussion/architecture/04-architecture-agnostic-final-structure.md)



---



## 🏗️ Repository 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](https://github.com/alfariiizi/vandor-backend-template)



---



## ✨ Features



### Vandor CLI (`cli/`)

- **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



### Backend Templates

- **Reference Implementation** - Available at [vandor-backend-template](https://github.com/alfariiizi/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



### VPKG System

- **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



---



## 🎯 Core Philosophy



### 1. Architecture-Agnostic Foundation



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.



### 2. Domain = Business Capability



❌ **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.



### 3. Minimal Base Template



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



### 4. Hybrid Repository Strategy



**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](REPOSITORY_STRATEGY.md) for details.



---



## 📦 Components



### [Vandor CLI](cli/README.md)

Command-line tool for project scaffolding and management.



**Key Commands:**

```bash

vandor init               # Initialize new project

vandor add domain         # Add business capability domain

vandor add handler        # Add HTTP handler

vandor vpkg add        # Install VPKG package

vandor tui                      # Launch interactive mode

vandor sync all                 # Regenerate code

```



### Backend Reference Implementation

Hexagonal architecture reference implementation available at:

**[github.com/alfariiizi/vandor-backend-template](https://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)



### [Templates](templates/)

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



---



## 🛠️ Development



### Prerequisites

- Go 1.24.1+

- Task (task runner)

- Air (hot reload - optional)

- Docker (for examples - optional)



### Building Components



```bash

# Build Vandor CLI

cd cli

go build -o vandor main.go

./vandor --version

```



### Running Tests



```bash

# Test Vandor CLI

cd cli

go test ./...



# Run validation scripts

./test/scripts/validate_priority5.sh

```



---



## 🗺️ Roadmap



### v0.1.0 - Core Foundation (Q1 2025) - **Production Ready**

- ✅ 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)



### v0.2.0 - Template Ecosystem (Q2 2025)

- 🔲 Separate template repositories

- 🔲 Template discovery system

- 🔲 Custom template support

- 🔲 API Gateway template



### v0.3.0 - Specialized Templates (Q3 2025)

- 🔲 CLI tool template

- 🔲 Event processor template

- 🔲 Worker template



### v0.4.0 - Advanced Features (Q4 2025)

- 🔲 Architecture migration tools

- 🔲 Multi-template monorepo

- 🔲 Cloud deployment integrations



See [TODO.md](TODO.md) for detailed progress tracking.



---



## 📖 Key Documentation



### Architecture & Design

- [Final Architecture Decisions](discussion/architecture/11-final-architecture-decisions.md) ⭐⭐⭐

- [Architecture-Agnostic Structure](discussion/architecture/04-architecture-agnostic-final-structure.md) ⭐⭐

- [Domain Granularity Strategy](discussion/architecture/05-domain-granularity-strategy.md) ⭐⭐

- [Minimal Base Template](discussion/architecture/08-minimal-base-template-strategy.md) ⭐⭐

- [VPKG Design Philosophy](discussion/design/01-shadcn-vs-vpkg-design-philosophy.md) ⭐



### Implementation

- [CLAUDE.md](CLAUDE.md) - Project overview for AI assistants

- [TODO.md](TODO.md) - Implementation roadmap and progress

- [REPOSITORY_STRATEGY.md](REPOSITORY_STRATEGY.md) - Monorepo strategy

- [CLEANUP_PLAN.md](CLEANUP_PLAN.md) - Repository organization



### User Guides

- [Getting Started](guide/getting-started.md) - Complete beginner tutorial

- [Installation](guide/installation.md) - Installation instructions

- [Interactive Mode](guide/interactive-mode-guide.md) - TUI wizard guide

- [VPKG Quick Start](VPKG-QUICK-START.md) - Package system reference



### Quality Reports

**Latest Reports (2025-11-02)**: See [`docs/quality/2025-11-02/`](docs/quality/2025-11-02/)



- [Architecture Alignment](docs/quality/2025-11-02/architecture-alignment.md) - 100% compliance verification

- [Integration Test Report](docs/quality/2025-11-02/integration-test-report.md) - End-to-end testing results

- [Fix Verification](docs/quality/2025-11-02/fix-verification-report.md) - Integration test fixes (100% success)

- [Registry Generator Fixes](docs/quality/2025-11-02/registry-generator-fixes.md) - Handler & job registry fixes

- [Daily Summary](docs/quality/2025-11-02/daily-summary.md) - Complete work overview

- [Final Verification](docs/quality/2025-11-02/final-verification-report.md) - System verification (23/23 tests)



---



## 🤝 Contributing



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



1. **Understand the Architecture**

   - Read [CLAUDE.md](CLAUDE.md)

   - Read [Architecture Decisions](discussion/architecture/11-final-architecture-decisions.md)

   - Review [TODO.md](TODO.md) for current priorities



2. **Pick a Task**

   - Check [TODO.md](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



---



## 📊 Status



**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](docs/quality/2025-11-02/) for detailed documentation



See [TODO.md](TODO.md) for detailed status and roadmap.



---



## 🔗 Links



- **Documentation Hub:** [Documentation Index](docs/navigation/DOCUMENTATION_INDEX.md)

- **Architecture Decisions:** [discussion/architecture/](discussion/architecture/)

- **User Guides:** [guide/](guide/)

- **Quality Reports:** [docs/](docs/)

- **Issue Tracker:** GitHub Issues (coming soon)

- **Discussions:** GitHub Discussions (coming soon)



---



## 📄 License



MIT License - See LICENSE file for details



---



## 🙏 Acknowledgments



**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**



---



## 🚦 Getting Help



- 📖 **Documentation:** Start with [Documentation Index](docs/navigation/DOCUMENTATION_INDEX.md)

- 🎓 **Tutorial:** Follow [Getting Started Guide](guide/getting-started.md)

- ⚡ **Quick Ref:** Check [Quick Reference](docs/navigation/QUICK_REFERENCE.md)

- 🐛 **Issues:** GitHub Issues (coming soon)

- 💬 **Discussions:** GitHub Discussions (coming soon)



---



**Happy coding! 🚀**