X-Go Gen-code

Quick Start Guide

Gen-X takes a depiction script — a Go file describing your domain — and produces a complete, compilable Go/Gin web application in under a second. You declare the models, fields, validations, and navigation entries you need; the generator emits the handlers, Maestros, fetchers, views, routes, and database migrations. This guide gets a minimal app running in ten minutes.

What You Need

  • Go 1.22+
  • Git
  • Node.js 18+ (for Tailwind CSS compilation in the generated app)
  • ATC and DevT (installed in Step 1 below)

10-Minute Setup

Step 1 — Install ATC and DevT

ATC (Apps Control Tower) and DevT (Developer Tools) are the two companion services that manage the Gen-X development environment. Install each from its repository directory.

cd ~/go/src/atc
./bin/install/install-linux.sh

cd ~/go/src/devt
./bin/install/install-linux.sh

If you have not cloned the repositories yet, see the Installation guide for the full environment setup.

Step 2 — Register Your App in ATC

Gen-X resolves project names and output paths from ATC’s registry. Every app must be registered before the generator can run.

  1. Open ATC at http://localhost:4555.
  2. Click New App in the top-right corner.
  3. Fill in the app name (plant-log), URL, and port (8086).
  4. Click Submit.

Step 3 — Write a Depiction Script

Create a depiction script in src/srv/depicters/ inside the gen-x repository. The example below generates a PlantLog app — a simple tracker for your seed garden.

// src/srv/depicters/plant_log_depicter.go

// |@@| W

package depicters

import (
	"context"

	"gitlab.com/blue-lila/gen-x/src/mdl"
	"gitlab.com/blue-lila/gen-x/src/srv/depicter"
)

type PlantLogDepicter struct{}

func (this *PlantLogDepicter) Depict(ctx context.Context, d *depicter.Depicter) {
	config := d.CreateProject(ctx, projectId, "plant-log", "plant-log", packagePath, nil)

	model := d.AddModel(ctx, config, "PlantLog", true)

	nameField := d.AddModelField(ctx, config, &mdl.ModelField{
		Name: "name", Kind: mdl.ModelFieldKindString, ModelId: model.Id,
	}, model)
	d.AddStringRequiredModelValidation(ctx, nameField)

	d.AddModelField(ctx, config, &mdl.ModelField{
		Name:    "status",
		Kind:    mdl.ModelFieldKindString,
		Data:    d.StringDataEnum([]string{"seeded", "sprouted", "growing", "harvested"}),
		ModelId: model.Id,
	}, model)

	d.AddPublicRouter(ctx)
	d.AddIntoTopMenu(ctx, "Plant Logs", "/plant-logs")
	d.CopiesOverwrittenFiles(ctx, config)
}

📝 Note: The // |@@| W annotation on line 3 marks this file as hand-written. Without it, the next Depicter run will treat the file as generated and overwrite it. See File Header Reference for the full annotation reference.

Step 4 — Run the Generator

From the gen-x directory, run the Depicter with the app name you registered in ATC.

⚠️ Warning: Running the Depicter overwrites all // |@@| C files in the output directory. Any custom changes not protected by a // |@@| W header will be lost without warning.

ENV=dev go run main.go depict plant-log

The generated application is written to /tmp/generated_project_plant-log and then copied to ~/go/src/plant-log.

Step 5 — Start the Generated App

Navigate to the generated project and start it with the bird alias.

cd ~/go/src/plant-log && bird

Open http://localhost:8086/plant-logs to see the running application.

Next Steps

Installation
Installation