Quick Start

From Zero to Running Server

This guide takes you through creating a project, adding a domain context, generating use cases, installing infrastructure, and starting the dev server. The whole thing takes about 5 minutes.

Step 1: Create the Project

vandor new myapi --module github.com/yourname/myapi --tidy auto

This creates a new project called myapi with your Go module path. The --tidy auto flag tells Vandor to automatically run go mod tidy after generating code, so your dependencies stay clean.

Your project starts with this structure:

myapi/
├── cmd/
│   └── app/
│       └── main.go
├── internal/
│   ├── core/
│   │   ├── contracts/
│   │   │   ├── command.go
│   │   │   ├── tx_contract.go
│   │   │   └── event_contract.go
│   │   ├── contexts/           # Empty for now
│   │   └── _gen/
│   │       ├── contexts_gen.go
│   │       └── modules_gen.go
│   ├── bootstrap/
│   │   ├── fx/
│   │   └── runtime/
│   └── config/
├── config/
│   ├── base.yaml
│   └── runner/
│       ├── app.yaml
│       └── worker.yaml
├── vpkg.yaml
├── vpkg.lock
└── go.mod

Notice there is no HTTP server, no database, no cache. Just your domain layer, bootstrapping code, and configuration. This is by design -- you add infrastructure only when you need it.

Step 2: Add a Context

A "context" in Vandor maps to a bounded context in DDD. It is a self-contained area of your business logic. Let us add one for a product catalog:

cd myapi
vandor add context catalog

This creates the context structure inside internal/core/contexts/:

internal/core/contexts/
└── catalog/
    ├── domain/
    │   ├── entity/
    │   ├── valueobject/
    │   ├── repository.go
    │   ├── read_repository.go
    │   └── errors.go
    ├── application/
    │   ├── usecase/
    │   └── service/
    ├── module.go
    └── module_gen.go

The domain/ layer holds your entities, value objects, and repository interfaces. The application/ layer holds your use cases and services. This separation keeps your business rules independent of any infrastructure.

Step 3: Add a Use Case

Use cases represent specific actions your application can perform. Let us add one:

vandor add usecase catalog create_product

This generates a use case file in internal/core/contexts/catalog/application/usecase/create_product.go with a struct, constructor, and an Execute method ready for you to implement.

The constructor uses uber-fx dependency injection with an fx.In deps struct, so your dependencies are automatically resolved at startup.

Step 4: Install Infrastructure Packages

Now let us add the infrastructure your API needs. Vandor uses VPKG -- its own package system -- to install infrastructure components:

# HTTP server with Huma + Chi router
vandor vpkg add @official/http-humachi

# Ent.go ORM for database access
vandor vpkg add @official/entgo

Each package installs code into your project's internal/transport/ or internal/infrastructure/ directories and registers itself with the uber-fx dependency injection system. These directories are managed by VPKG -- you do not edit them directly.

Step 5: Sync and Run

After adding contexts or packages, sync the generated code:

vandor sync all

Then start the development server:

vandor dev:app

Your API server is now running. The dev server watches for file changes and automatically rebuilds.

What Just Happened?

In five commands, you:

1. Created a project with DDD structure, uber-fx dependency injection, configuration management, and structured logging
2. Defined a business boundary (the catalog context) with clean domain and application layers
3. Added a use case (create_product) with dependency injection wiring
4. Installed infrastructure (HTTP server and database ORM) through VPKG
5. Started a dev server with hot reload

The important thing to notice is the order: business logic first, infrastructure second. This is the Vandor way.

Common Commands You Will Use

# Project creation
vandor new --module github.com/acme/myapp --tidy auto

# Adding domain components (space-separated for multiple)
vandor add context catalog identity order
vandor add domain catalog product category
vandor add usecase catalog create_product list_products
vandor add service catalog pricing_service
vandor add valueobject catalog money currency

# Syncing generated code
vandor sync context catalog      # Sync one context
vandor sync core                 # Sync core layer
vandor sync all                  # Sync everything

# Package management
vandor vpkg add @official/http-humachi
vandor vpkg add @official/entgo
vandor vpkg add @official/redis-cache

# Running your application
vandor dev:app                   # Development with hot reload
vandor run:app                   # Production run
vandor run:worker                # Run background worker

Next Steps