Project Filesystem Structure¶

GTB enforces a standardized filesystem layout for all generated CLI applications. This consistency ensures that any developer familiar with the framework can navigate any tool built with it, while also supporting the deep integration features like automated regeneration and asset merging.

Standard Layout¶

A typical project generated by gtb generate project follows this structure:

mytool/
├── .gtb/
│   └── manifest.yaml       # The "Source of Truth" for your tool
├── cmd/
│   └── mytool/
│       └── main.go         # The Orchestration Layer (entry point)
├── docs/                   # Automated CLI & Package documentation
├── pkg/
│   └── cmd/
│       ├── root/
│       │   ├── cmd.go      # The Root Command definition
│       │   └── assets/     # Domain-specific embedded assets
│       │       └── init/
│       │           └── config.yaml
│       └── sub/
│           ├── cmd.go      # The Wiring Layer (Cobra/Flags/Deps)
│           └── main.go     # The Logic Layer (Business logic stubs)
├── go.mod                  # Standard Go module definition
└── justfile                # Automation tasks (optional)

Reasoning Behind the Structure¶

1. Layered Architecture¶

The structure is designed to support the three layers of a GTB application:

• Discovery Layer (.gtb/): The manifest defines what the tool is. It is the machine-readable design document that the generator uses to synchronize code.
• Orchestration Layer (cmd/): This layer is responsible for wiring things together. The main.go file initializes Props, configures the Logger, and launches the root command. It contains very little "logic."
• Implementation Layer (pkg/cmd/): This is where your actual command logic lives. Every generated command consists of two distinct files to ensure a complete decoupling from the CLI framework:
  • cmd.go (The Wiring): Handles all Cobra-specific logic, including flag definition, argument parsing, and dependency injection from Props. It acts as the bridge between the framework and your logic.
  • main.go (The Logic): The heart of your customization. This file contains the business logic stubs that the wiring layer calls into. It is intentionally kept pure and decoupled from Cobra, allowing you to focus on the tool's core functionality.

2. Standardized Discovery (The cmd/ convention)¶

Following the Go Project Layout convention, all executable entry points live in cmd/. This makes it easy for build systems (like GoReleaser) and other developers to find the main binary logic.

3. Co-located Assets¶

Instead of a single global assets/ folder, GTB encourages placing assets near the code that consumes them.

• Assets in pkg/cmd/root/assets/ provide global defaults.
• Assets in pkg/cmd/my-sub-command/assets/ allow subcommands to contribute their own domain-specific configuration or templates.

The framework's Smart VFS automatically merges these co-located files into a single virtual filesystem at runtime.

4. Automated Documentation (docs/)¶

A core philosophy of GTB is that code and documentation should never diverge. When you run any generate command (project or command):

• Structure Generation: The framework automatically creates and updates the docs/ folder to match your command hierarchy.
• AI-Driven Content: For every new command, the CLI triggers a background reasoning process to analyze your intent and flesh out the documentation with high-quality descriptions and examples.
• TUI Readiness: This folder is immediately consumable by the Integrated Documentation system, ensuring your tool always has built-in help.

5. Manifest as the Source of Truth¶

The .gtb/manifest.yaml file is unique to GTB. It allows the framework to:

• Regenerate Code: If you rename a command in the manifest, the regenerate command will update your Go source code while preserving your custom implementation logic.
• Enforce Consistency: It tracks command hierarchies, aliases, and flags, ensuring that the final binary perfectly matches the intended design.

Summary¶

By adopting this structure, your CLI tool gains the structural integrity needed to grow from a simple utility into a complex, multi-component platform without descending into architectural chaos.