{"id":33249372,"url":"https://github.com/alfariiizi/vandor","last_synced_at":"2026-03-05T01:31:08.868Z","repository":{"id":338598804,"uuid":"1157924663","full_name":"alfariiizi/vandor","owner":"alfariiizi","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-15T14:40:17.000Z","size":5408,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-15T16:30:41.722Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alfariiizi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-14T14:18:40.000Z","updated_at":"2026-02-15T14:40:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alfariiizi/vandor","commit_stats":null,"previous_names":["alfariiizi/vandor"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/alfariiizi/vandor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfariiizi%2Fvandor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfariiizi%2Fvandor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfariiizi%2Fvandor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfariiizi%2Fvandor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alfariiizi","download_url":"https://codeload.github.com/alfariiizi/vandor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfariiizi%2Fvandor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30104270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T01:06:53.091Z","status":"ssl_error","status_checked_at":"2026-03-05T01:02:35.679Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-generator","ddd-architecture","go","golang","hexagonal-architecture","vpkg","vpkg-registry"],"created_at":"2025-11-16T22:01:19.285Z","updated_at":"2026-03-05T01:31:08.842Z","avatar_url":"https://github.com/alfariiizi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vandor Ecosystem\n\n\u003e **Architecture-agnostic Go backend scaffolding and package management system**\n\n[![Go Version](https://img.shields.io/badge/Go-1.24.1+-00ADD8?style=flat\u0026logo=go)](https://go.dev/)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Status](https://img.shields.io/badge/Status-v0.1%20Development-yellow)](TODO.md)\n\n**Vandor** is a comprehensive ecosystem for building production-ready Go backends with a focus on:\n- 🏗️ **Architecture Flexibility** - Support for multiple architecture patterns (Hexagonal, EDA, Clean, Minimal)\n- 📦 **Package Management** - VPKG system for reusable components\n- 🎨 **Interactive CLI** - Beautiful TUI with Catppuccin themes\n- 🧩 **Domain-Driven Design** - Business capability-focused domain organization\n- 🚀 **Developer Experience** - Code generation, hot reload, comprehensive tooling\n\n---\n\n## 🚀 Quick Start\n\n### One-Line Installation\n\n**Using curl:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/alfariiizi/vandor/main/install.sh | bash\n```\n\n**Using wget:**\n```bash\nwget -qO- https://raw.githubusercontent.com/alfariiizi/vandor/main/install.sh | bash\n```\n\n**Custom installation directory:**\n```bash\nINSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/alfariiizi/vandor/main/install.sh | bash\n```\n\n### Initialize Your First Project\n\n```bash\n# Interactive wizard (recommended)\nvandor init my-project\n\n# Or use presets for quick setup\nvandor init my-api --preset=web-api --non-interactive\n```\n\n### Build from Source (Alternative)\n\nIf you prefer to build from source:\n\n```bash\n# Clone the repository\ngit clone https://github.com/alfariiizi/vandor.git\ncd vandor\n\n# Build the CLI\ncd cli\ngo build -o vandor main.go\n\n# Install (optional)\nsudo mv vandor /usr/local/bin/\n```\n\n---\n\n## 📚 Documentation\n\n**New to Vandor?** Start with our comprehensive documentation navigation system:\n\n| Document | Purpose | Audience |\n|----------|---------|----------|\n| **[Documentation Index](docs/navigation/DOCUMENTATION_INDEX.md)** | 📖 Master index of all files | Everyone |\n| **[Quick Reference](docs/navigation/QUICK_REFERENCE.md)** | ⚡ Quick reference card | Developers |\n| **[Structure Guide](docs/navigation/STRUCTURE_GUIDE.md)** | 🌳 Visual tree structure | Explorers |\n| **[Getting Started](guide/getting-started.md)** | 🎓 Complete tutorial | Beginners |\n| **[Installation Guide](guide/installation.md)** | 💿 Installation guide | New users |\n| **[VPKG Quick Start](guide/vpkg-quick-start.md)** | 📦 Package system guide | Developers |\n\n### Learning Paths\n\n**For Users:**\n1. [Installation Guide](guide/installation.md)\n2. [Getting Started](guide/getting-started.md)\n3. [Interactive Mode Guide](guide/interactive-mode-guide.md)\n\n**For Contributors:**\n1. [CLAUDE.md](CLAUDE.md) - Project overview\n2. [TODO.md](TODO.md) - Implementation roadmap\n3. [Architecture Decisions](discussion/architecture/11-final-architecture-decisions.md)\n\n**For Architects:**\n1. [Final Architecture Decisions](discussion/architecture/11-final-architecture-decisions.md)\n2. [Domain Granularity Strategy](discussion/architecture/05-domain-granularity-strategy.md)\n3. [Architecture-Agnostic Structure](discussion/architecture/04-architecture-agnostic-final-structure.md)\n\n---\n\n## 🏗️ Repository Structure\n\n```\nvandor/                            # Repository root\n├── cli/                           # 🛠️ Vandor CLI Tool (main component)\n│   ├── cmd/                       # CLI commands\n│   ├── internal/                  # Generators, TUI, VPKG\n│   └── README.md                  # CLI documentation\n│\n├── templates/                     # 📋 Project Templates\n│   ├── base/                      # Minimal base template\n│   └── hexagonal/                 # Hexagonal architecture template\n│\n├── test/                          # 🧪 Test Suite\n│   ├── fixtures/                  # Generated test projects\n│   ├── scripts/                   # Validation scripts\n│   └── manual/                    # Manual test files\n│\n├── discussion/                    # 📖 Design Discussions\n│   ├── architecture/              # 11 architecture decision docs\n│   └── design/                    # VPKG and design philosophy\n│\n├── docs/                          # ✅ Project Documentation\n│   ├── completed/                 # Completion reports\n│   ├── current/                   # Active development docs\n│   └── archive/                   # Historical decisions\n│\n└── guide/                         # 📚 User Guides\n    ├── getting-started.md         # Complete beginner tutorial\n    ├── installation.md            # Installation instructions\n    └── interactive-mode-guide.md  # TUI wizard guide\n```\n\n\u003e **Note**: The reference backend implementation has been moved to a separate repository:\n\u003e [github.com/alfariiizi/vandor-backend-template](https://github.com/alfariiizi/vandor-backend-template)\n\n---\n\n## ✨ Features\n\n### Vandor CLI (`cli/`)\n- **Interactive Project Init** - Beautiful TUI wizard with Catppuccin themes\n- **Multiple Architecture Templates** - Hexagonal, EDA, Clean, Minimal (v0.1 focuses on Hexagonal)\n- **VPKG Package System** - Install infrastructure components on-demand\n- **Code Generators** - Domain, use case, service, handler generators\n- **Domain Discovery** - AI-powered and rule-based domain suggestions\n- **Task Runner** - Integrated Taskfile support\n- **Theme System** - Auto-detecting Catppuccin themes\n\n### Backend Templates\n- **Reference Implementation** - Available at [vandor-backend-template](https://github.com/alfariiizi/vandor-backend-template)\n- **Complete Stack** - Ent.go, Huma v2, Chi, FX dependency injection\n- **Database Tools** - Atlas migrations, Ent code generation\n- **Background Jobs** - Asynq task queue integration\n- **Observability** - OpenTelemetry, structured logging\n\n### VPKG System\n- **Extension Mechanism** - Add HTTP, database, cache, messaging on-demand\n- **Two Package Types** - `fx-module` (libraries) and `cli-command` (tools)\n- **Registry Support** - Remote package discovery and installation\n- **Dependency Resolution** - Automatic dependency management\n\n---\n\n## 🎯 Core Philosophy\n\n### 1. Architecture-Agnostic Foundation\n\nAll projects share the same top-level structure:\n```\ninternal/\n├── domain/              # Business capabilities\n├── adapter/             # Infrastructure \u0026 transport\n├── pkg/                 # Logger + config only\n└── vpkg/                # Installed packages\n```\n\nOnly the **internal domain structure** changes per architecture.\n\n### 2. Domain = Business Capability\n\n❌ **Wrong:** Table-based domains (`user/`, `product/`, `order_item/`)  \n✅ **Right:** Business capability domains (`identity/`, `catalog/`, `order/`)\n\nUse Event Storming or business capability analysis to discover domains.\n\n### 3. Minimal Base Template\n\nBase template includes **ONLY:**\n- Logger\n- Configuration\n- Project structure\n\nEverything else (HTTP, database, cache) is added via **VPKG**.\n\nThis supports:\n- ✅ Web APIs\n- ✅ CLI tools\n- ✅ Event processors\n- ✅ API gateways\n- ✅ Background workers\n\n### 4. Hybrid Repository Strategy\n\n**Now (v0.1 Development):**\n- 🎯 Monorepo for easy coordination\n- Single `git clone`\n- Atomic commits across components\n\n**Current Organization:**\n- ✅ `github.com/alfariiizi/vandor` - CLI tool and templates\n- ✅ `github.com/alfariiizi/vandor-backend-template` - Reference implementation\n\n**Future:**\n- Additional specialized templates in separate repositories\n\nSee [REPOSITORY_STRATEGY.md](REPOSITORY_STRATEGY.md) for details.\n\n---\n\n## 📦 Components\n\n### [Vandor CLI](cli/README.md)\nCommand-line tool for project scaffolding and management.\n\n**Key Commands:**\n```bash\nvandor init \u003cname\u003e              # Initialize new project\nvandor add domain \u003cname\u003e        # Add business capability domain\nvandor add handler \u003cpath\u003e       # Add HTTP handler\nvandor vpkg add \u003cpackage\u003e       # Install VPKG package\nvandor tui                      # Launch interactive mode\nvandor sync all                 # Regenerate code\n```\n\n### Backend Reference Implementation\nHexagonal architecture reference implementation available at:\n**[github.com/alfariiizi/vandor-backend-template](https://github.com/alfariiizi/vandor-backend-template)**\n\n**Tech Stack:**\n- Go 1.24.1+\n- Uber FX (dependency injection)\n- Ent.go (database ORM)\n- Huma v2 (HTTP framework)\n- Asynq (background jobs)\n- OpenTelemetry (observability)\n\n### [Templates](templates/)\nProject templates for different architectures.\n\n**Available:**\n- **Base** (`templates/base/`) - Minimal foundation\n- **Hexagonal** (`templates/hexagonal/`) - Ports \u0026 adapters\n\n**Planned (v0.2+):**\n- Event-Driven Architecture\n- Clean Architecture\n- Custom templates\n\n---\n\n## 🛠️ Development\n\n### Prerequisites\n- Go 1.24.1+\n- Task (task runner)\n- Air (hot reload - optional)\n- Docker (for examples - optional)\n\n### Building Components\n\n```bash\n# Build Vandor CLI\ncd cli\ngo build -o vandor main.go\n./vandor --version\n```\n\n### Running Tests\n\n```bash\n# Test Vandor CLI\ncd cli\ngo test ./...\n\n# Run validation scripts\n./test/scripts/validate_priority5.sh\n```\n\n---\n\n## 🗺️ Roadmap\n\n### v0.1.0 - Core Foundation (Q1 2025) - **Production Ready**\n- ✅ Hexagonal architecture template\n- ✅ Interactive init wizard\n- ✅ VPKG ecosystem\n- ✅ Domain generators\n- ✅ Testing infrastructure\n- ✅ All 5 registry generators\n- ✅ CLI bug fixes (8 critical issues)\n- ✅ Architecture alignment (100%)\n- ✅ Integration testing (100% success)\n- ✅ Documentation (comprehensive quality reports)\n\n### v0.2.0 - Template Ecosystem (Q2 2025)\n- 🔲 Separate template repositories\n- 🔲 Template discovery system\n- 🔲 Custom template support\n- 🔲 API Gateway template\n\n### v0.3.0 - Specialized Templates (Q3 2025)\n- 🔲 CLI tool template\n- 🔲 Event processor template\n- 🔲 Worker template\n\n### v0.4.0 - Advanced Features (Q4 2025)\n- 🔲 Architecture migration tools\n- 🔲 Multi-template monorepo\n- 🔲 Cloud deployment integrations\n\nSee [TODO.md](TODO.md) for detailed progress tracking.\n\n---\n\n## 📖 Key Documentation\n\n### Architecture \u0026 Design\n- [Final Architecture Decisions](discussion/architecture/11-final-architecture-decisions.md) ⭐⭐⭐\n- [Architecture-Agnostic Structure](discussion/architecture/04-architecture-agnostic-final-structure.md) ⭐⭐\n- [Domain Granularity Strategy](discussion/architecture/05-domain-granularity-strategy.md) ⭐⭐\n- [Minimal Base Template](discussion/architecture/08-minimal-base-template-strategy.md) ⭐⭐\n- [VPKG Design Philosophy](discussion/design/01-shadcn-vs-vpkg-design-philosophy.md) ⭐\n\n### Implementation\n- [CLAUDE.md](CLAUDE.md) - Project overview for AI assistants\n- [TODO.md](TODO.md) - Implementation roadmap and progress\n- [REPOSITORY_STRATEGY.md](REPOSITORY_STRATEGY.md) - Monorepo strategy\n- [CLEANUP_PLAN.md](CLEANUP_PLAN.md) - Repository organization\n\n### User Guides\n- [Getting Started](guide/getting-started.md) - Complete beginner tutorial\n- [Installation](guide/installation.md) - Installation instructions\n- [Interactive Mode](guide/interactive-mode-guide.md) - TUI wizard guide\n- [VPKG Quick Start](VPKG-QUICK-START.md) - Package system reference\n\n### Quality Reports\n**Latest Reports (2025-11-02)**: See [`docs/quality/2025-11-02/`](docs/quality/2025-11-02/)\n\n- [Architecture Alignment](docs/quality/2025-11-02/architecture-alignment.md) - 100% compliance verification\n- [Integration Test Report](docs/quality/2025-11-02/integration-test-report.md) - End-to-end testing results\n- [Fix Verification](docs/quality/2025-11-02/fix-verification-report.md) - Integration test fixes (100% success)\n- [Registry Generator Fixes](docs/quality/2025-11-02/registry-generator-fixes.md) - Handler \u0026 job registry fixes\n- [Daily Summary](docs/quality/2025-11-02/daily-summary.md) - Complete work overview\n- [Final Verification](docs/quality/2025-11-02/final-verification-report.md) - System verification (23/23 tests)\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Understand the Architecture**\n   - Read [CLAUDE.md](CLAUDE.md)\n   - Read [Architecture Decisions](discussion/architecture/11-final-architecture-decisions.md)\n   - Review [TODO.md](TODO.md) for current priorities\n\n2. **Pick a Task**\n   - Check [TODO.md](TODO.md) for open tasks\n   - Look for Priority 1-2 tasks for v0.1\n   - Check `docs/current/` for active development\n\n3. **Make Your Changes**\n   - Follow Go best practices\n   - Add tests for new features\n   - Update documentation\n   - Use conventional commits\n\n4. **Submit a PR**\n   - Ensure tests pass\n   - Update TODO.md if needed\n   - Add to docs/completed/ when done\n\n---\n\n## 📊 Status\n\n**Current Phase:** v0.1.0 Released (100% complete - **Production Ready**)\n\n**What's Working:**\n- ✅ Hexagonal template generation\n- ✅ Interactive init wizard\n- ✅ VPKG package system\n- ✅ Domain discovery\n- ✅ Code synchronization\n- ✅ Testing infrastructure\n- ✅ Registry generators (all 5 working perfectly)\n- ✅ Architecture alignment (100% compliance)\n- ✅ Integration testing (100% success rate)\n- ✅ CLI bug fixes (all 8 critical issues resolved)\n- ✅ Complete end-to-end workflow verified\n\n**v0.1.0 Released:**\n- ✅ All core features implemented\n- ✅ All critical bugs fixed\n- ✅ Comprehensive testing complete (23/23 tests passed)\n- ✅ Quality documentation (6 reports, 3,900+ lines)\n- ✅ CHANGELOG.md and RELEASE_NOTES.md created\n- ✅ FAQ and Troubleshooting guides added\n\n**Recent Improvements (2025-11-02):**\n- ✅ Fixed 8 critical CLI bugs\n- ✅ Achieved 100% architecture alignment\n- ✅ Fixed integration test issues (89% → 100% success)\n- ✅ Fixed registry generator bugs (all 5 registries working)\n- ✅ Complete system verification (23/23 tests passed)\n\n**See**: [Quality Reports](docs/quality/2025-11-02/) for detailed documentation\n\nSee [TODO.md](TODO.md) for detailed status and roadmap.\n\n---\n\n## 🔗 Links\n\n- **Documentation Hub:** [Documentation Index](docs/navigation/DOCUMENTATION_INDEX.md)\n- **Architecture Decisions:** [discussion/architecture/](discussion/architecture/)\n- **User Guides:** [guide/](guide/)\n- **Quality Reports:** [docs/](docs/)\n- **Issue Tracker:** GitHub Issues (coming soon)\n- **Discussions:** GitHub Discussions (coming soon)\n\n---\n\n## 📄 License\n\nMIT License - See LICENSE file for details\n\n---\n\n## 🙏 Acknowledgments\n\n**Design Inspiration:**\n- **shadcn/ui** - Component ownership philosophy\n- **DDD Community** - Domain-driven design patterns\n- **Go Community** - Best practices and idioms\n\n**Technologies:**\n- **Cobra** - CLI framework\n- **Bubble Tea** - TUI framework\n- **Catppuccin** - Beautiful color themes\n- **Ent** - Database ORM\n- **Huma** - HTTP framework\n\n---\n\n**Made with ❤️ for the Go community**\n\n---\n\n## 🚦 Getting Help\n\n- 📖 **Documentation:** Start with [Documentation Index](docs/navigation/DOCUMENTATION_INDEX.md)\n- 🎓 **Tutorial:** Follow [Getting Started Guide](guide/getting-started.md)\n- ⚡ **Quick Ref:** Check [Quick Reference](docs/navigation/QUICK_REFERENCE.md)\n- 🐛 **Issues:** GitHub Issues (coming soon)\n- 💬 **Discussions:** GitHub Discussions (coming soon)\n\n---\n\n**Happy coding! 🚀**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfariiizi%2Fvandor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falfariiizi%2Fvandor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfariiizi%2Fvandor/lists"}