Core Concepts

Understanding Vandor

Vandor is not another scaffolding tool that dumps a pile of boilerplate on you and walks away. It is a development system built on a clear separation of responsibilities: your domain logic belongs to you, your infrastructure is delivered on-demand, and your production binary never needs the Vandor CLI to run.

Everything in Vandor v0.4 flows from three pillars.

The Three Pillars

1. Core-First Development

Vandor Core owns the domain layer. When you run vandor add context, Vandor scaffolds the bounded context structure inside internal/core/ -- entities, value objects, repositories, use cases, services, and the module wiring. This is the part of your application that represents what your business actually does.

The core layer is domain-pure. It never imports transport code, infrastructure code, or framework wiring. If your business logic can run without an HTTP server, a database driver, or a DI container in scope, you know your boundaries are right.

internal/core/
├── contracts/         # Shared domain contracts (commands, events, transactions)
├── contexts/
│   ├── identity/      # Business capability: authentication and user management
│   ├── catalog/       # Business capability: product catalog
│   └── order/         # Business capability: order processing
└── _gen/              # Auto-generated module wiring

Learn more about the core layer and bounded contexts

2. On-Demand Infrastructure

Transport and infrastructure are not baked into every project. They arrive through Vpkg, Vandor's package system. Need an HTTP server? Install @official/http-humachi. Need a database? Install @official/entgo and @official/atlas. Need background job processing? Install @official/asynq.

Vpkg packages write code into internal/transport/ and internal/infrastructure/, directories that Vpkg owns. This means your project starts lean and only carries the infrastructure it actually uses.

# Add HTTP transport
vandor vpkg add @official/http-humachi

# Add database support
vandor vpkg add @official/entgo
vandor vpkg add @official/atlas

# Add background job processing
vandor vpkg add @official/asynq

This is what makes Vandor versatile. The same core scaffolding supports web APIs, CLI tools, event processors, API gateways, and background workers -- you just install different packages.

Learn more about the Vpkg system

3. Runtime Independence

When you deploy to production, you ship a plain Go binary. There is no Vandor runtime, no Vandor CLI dependency, no hidden framework that needs to be present on the server. Vandor is a development tool. It helps you scaffold, generate, and manage code. Once the code exists, it is yours -- a standard Go application that builds and runs with the standard Go toolchain.

This means:

• No vendor lock-in at deployment time
• No special runtime to install on production servers
• No framework overhead in your final binary
• Standard Go debugging, profiling, and tooling works as expected

Learn more about the core-first design

How These Concepts Work Together

Here is a practical example. Suppose you are building an HRIS (Human Resource Information System).

Step 1: Create the project

vandor new hris-api

You get a project with logger, configuration, project structure, and uber-fx wiring. No transport, no database, no cache.

Step 2: Design your bounded contexts

vandor add context identity      # employees, authentication, roles
vandor add context payroll        # salary, deductions, pay runs
vandor add context attendance     # clock-in, leave, schedules
vandor add context recruitment    # job postings, applications, interviews

Each context gets its own domain structure with entities, value objects, repositories, use cases, and services. Your business logic lives here and can be tested without any infrastructure.

Step 3: Add infrastructure via Vpkg

vandor vpkg add @official/http-humachi    # REST API transport
vandor vpkg add @official/entgo           # Database ORM
vandor vpkg add @official/atlas           # Schema migrations
vandor vpkg add @official/redis-cache     # Caching layer
vandor vpkg add @official/asynq           # Background jobs for payroll processing

Step 4: Build and deploy

go build -o hris-api cmd/app/main.go
./hris-api

A standard Go binary. No Vandor CLI needed in production.

Key Concepts

Philosophy in Practice

Traditional Approach

Most frameworks give you everything upfront:

project/
├── controllers/      # HTTP layer forced on you
├── models/           # Database layer forced on you
├── routes/           # Routing forced on you
└── services/         # Service layer forced on you

Problems with this:

• Cannot build CLI tools (HTTP is forced on you)
• Cannot build event processors (HTTP is forced on you)
• Cannot build gateways (database is forced on you)
• All projects look the same regardless of their actual needs

Vandor Approach

Start with your domain. Add infrastructure when you need it.

project/
├── internal/
│   ├── core/           # Your business logic (always present)
│   ├── transport/      # Empty until you install a Vpkg transport package
│   ├── infrastructure/ # Empty until you install a Vpkg infrastructure package
│   ├── bootstrap/      # uber-fx wiring and runtime management
│   └── config/         # Typed configuration with validation
├── config/
│   ├── base.yaml       # Base configuration
│   └── runner/         # Runner-specific overlays
└── vpkg.yaml           # Desired package state

Then add only what your application actually requires:

• Building an API? vandor vpkg add @official/http-humachi
• Need a database? vandor vpkg add @official/entgo
• Need caching? vandor vpkg add @official/redis-cache
• Need background jobs? vandor vpkg add @official/asynq

Benefits

For Developers

Clear Boundaries -- Each bounded context is independent. You can work on the payroll context without touching identity or attendance.

Testability -- The core layer has no infrastructure dependencies. Test your business logic in isolation with simple mocks. If you need a database connection to test a use case, something is wrong with your boundaries.

Flexibility -- Change infrastructure without touching business logic. Switching from one cache provider to another only affects infrastructure code, never your domain.

For Teams

Parallel Development -- Different team members work on different contexts without merge conflicts.

Onboarding -- New developers understand business capabilities immediately. "Work on the payroll context" is clearer than "work on the salary model and its controllers and services."

Ownership -- Teams own contexts, not layers. The payroll team owns everything about payroll: entities, use cases, repository interfaces, and the business rules that govern pay calculations.

For Projects

Scalability -- Start small, grow as needed. Add infrastructure only when your requirements demand it.

Maintainability -- Business logic is isolated from infrastructure. Changes to one side do not ripple into the other.

Microservice Readiness -- Each bounded context has clean boundaries. When the time comes to extract a context into its own service, the boundaries are already drawn.

Next Steps

Dive deeper into each concept: