Concepts¶

To get the most out of GTB, it is helpful to understand the core concepts and architectural patterns that drive its design. This section provides a deep dive into the framework's "Why" and the underlying mechanics.

Core Pillars¶

Architecture Fundamentals¶

Explore the high-level system design, command registry, and execution flow.

Command Constructor Pattern¶

Understand why we use NewCmd* constructors for explicit dependency injection and testability.

Functional Options Pattern¶

Learn how the framework uses functional options for flexible, backward-compatible constructors across controllers, clones, and TUI components.

Interface Design Principles¶

Comprehensive guide to all public interfaces in GTB, their purposes, and mock generation strategies.

Logging Abstraction¶

Understand the unified logger.Logger interface, backend selection (charmbracelet, slog, noop), and ecosystem integration patterns.

Project Structure¶

Understand the filesystem layout of a GTB project and the reasoning behind it.

Framework CLI¶

Discover why we use a specialized CLI for scaffolding, regeneration, and maintaining architectural consistency.

Regeneration & Sync¶

Learn about the bi-directional synchronization between your manifest and source code.

Documentation Layout (Diátaxis)¶

Understand why generated docs follow the Diátaxis structure, how commands and packages map to the four quadrants, and the docs_layout setting.

Dependency Injection (Props)¶

Learn about the Props container, the central nervous system that provides context to every command.

Configuration Precedence¶

Understand how defaults, files, environment variables, and flags merge to create a robust runtime configuration.

Universal Asset Management¶

Explore embedded assets, multi-filesystem merging, and how the framework manages structured data across the application.

Asset Management¶

A focused look at embedded assets, virtual filesystems, and configuration merging.

Integrated Documentation¶

Learn about the CLI-first documentation browser and AI-powered Q&A system.

Tool Initialisers & Feature Setup¶

Understand the architecture of modular features, self-registration, and initialisation logic.

Tool Initialisers¶

A deeper look at the Initialiser pattern for modular, self-registering feature configuration.

Command Middleware System¶

Understand the middleware chain pattern for cross-cutting CLI command concerns.

Transport Middleware & Resilience¶

Understand middleware/interceptor chains as the extension point for cross-cutting transport concerns — logging, auth, rate limiting, retry, circuit breaking — across HTTP and gRPC, server and client.

Auto-Update Lifecycle¶

Learn how the framework manages throttled version checks and atomic binary replacement.

Release-binary Signing¶

How gtb-derived tools establish a cryptographic chain of trust between you, the release pipeline, and the people running your CLI — without anyone holding a private key on their laptop.

VCS & Repository Abstraction¶

Explore the polymorphic repository strategy and unified GitHub automation API.

Service Orchestration & Control¶

Understand how the framework manages the lifecycle, health, and graceful shutdown of background services.

TUI & Configuration Patterns¶

Understand best practices for interactive setup, environment precedence disclosure, and sensitive data handling.

Centralized Error Handling¶

Learn about the ErrorHandler interface and how the framework manages logging and user support.

AI Agents & MCP¶

How to expose your CLI tool as an autonomous agent for LLMs to control.

Manifest Architecture¶

Understand how the .gtb/manifest.yaml acts as the source of truth for your CLI scaffolding.

AI-Powered Features¶

How to consume AI services to build intelligent features within your tool.

Credentials Architecture¶

The conceptual storage modes, trust model, and consumer architecture for user-supplied secrets.

Telemetry Architecture & Concepts¶

Architectural concepts, privacy controls, data handling, and design limitations behind GTB's telemetry framework.