X-Go Gen-code

Creating a New Application

Gen-X follows a two-phase model for application creation. First you describe the application — its models, fields, and relationships — by writing a Depicter script in Go. Then you run the Depicter, which reads that description and emits a fully structured application. This page walks through both phases from the initial GUI registration to the moment you open the generated app’s folder.

Step 1 — Register the App in ATC

Before Gen-X can generate anything, the application must be registered in the App Tower Control (ATC) GUI. ATC acts as the central registry that Gen-X reads when resolving project names and output paths.

Open ATC at localhost:4555 and follow these steps:

  1. Click New app in the top-right corner.
  2. Enter a name for the app.
  3. Enter the URL of the app.
  4. Enter the port the app will run on.
  5. Check the desired options for the app.
  6. Click Submit.

📝 Note: If the app will run on a remote server, make sure the Has Transponder checkbox is checked. Remote apps without this flag will not have the network layer correctly scaffolded by the generator.

Step 2 — Write the Depicter Script

The Depicter script is the schema definition for your application. It lives in src/srv/depicters/PROJECT_NAME_base_depicter.go inside the gen-x repository. Gen-X reads this file to understand what models to generate, what form fields to create, and how entities relate to each other.

A minimal Depicter script looks like this:

// src/srv/depicters/my_app_base_depicter.go
package depicters

// |@@| W

import (
    "context"
	"gen-x/src/dat"
	"gen-x/src/mdl"
)

type MyAppBaseDepicter struct{
	Depicter *Depicter
}

func (this *MyAppBaseDepicter) Depict(ctx context.Context, config *mdl.ProjectConfig) {

    // Define a model
    model := this.Depicter.AddModel(ctx, config, "garden", true)

	// Add fields to the model
	this.Depicter.AddModelField(ctx, config, &mdl.ModelField{Name: "name", Kind: "string"}, model)

	// Add relationships to the model
	this.Depicter.AddOneToOneModelRelation(ctx, config, model, "owner")
	this.Depicter.AddManyChildToOneParentRelation(ctx, config, model, "plants")
}

Refer to the Depicter reference for the full list of available methods and options.

Step 3 — Run the Depicter

Once your Depicter script is written, run the generator from the gen-x directory. The ENV=dev flag tells Gen-X to use your local development configuration.

ENV=dev go run main.go depict PROJECT_NAME

Replace PROJECT_NAME with the name you registered in ATC. Gen-X will create the generated application in ~/go/src/PROJECT_NAME.

Step 4 — Work in the Generated App

The generated application is ready to run immediately. Open the project directory and start the app using the bird alias.

⚠️ Warning: Every generated file begins with a |@@| file header annotation. Files marked // |@@| C will be overwritten the next time the Depicter runs. If you modify a generated file without changing its header to // |@@| W, your changes will be silently lost on the next generation run.

See Modifying an Existing Application for the complete guide on working safely with generated code, and File Header Reference for the full annotation reference.

Next Steps

Daily Workflow
Modifying An App