Architecture Deep Dive

This section documents the internal design of ai-commit: how the application bootstraps, how its major subsystems are structured, and how the components interact at runtime. It covers the framework foundation, command dispatch, the generator abstraction, the configuration system, and the HTTP client layer.

For user-facing usage of these systems, see the User Guide. For a step-by-step walkthrough of adding new generators, see Adding New Generators.

---

System Overview

ai-commit is a Laravel Zero console application. Laravel Zero is a trimmed-down Laravel build designed for standalone CLI tools. The application is distributed as a PHAR and as a Composer binary.

The codebase is organized around four major subsystems:

Subsystem	Primary Entry Point	Purpose
Application Bootstrap	bootstrap/app.php	Wires together all subsystems at startup
Command Layer	app/Commands/	Handles CLI interaction
Generator System	app/Generators/ + app/GeneratorManager.php	Abstracts all AI backends
Configuration System	app/ConfigManager.php	Merges layered JSON config
HTTP Client Layer	app/Clients/	Sends requests to AI APIs

Each subsystem has its own child page. This page provides the cross-cutting view.

Sources: bootstrap/app.php1-116 composer.json58-68 app/Providers/AppServiceProvider.php1-68

---

Top-Level Architecture

Diagram: Major subsystems and their runtime relationships

Sources: bootstrap/app.php36-116 app/Providers/AppServiceProvider.php29-68

---

Bootstrap Sequence

The application is initialized in bootstrap/app.php using Application::configure(). The sequence is:

1. Application::configure() — Sets the base path, declares singletons.
2. withSingletons([GeneratorManager::class]) — Registers GeneratorManager in the IoC container as a singleton.
3. booting callbacks — Three callbacks run before the application fully boots:
   • ConfigManager::load() merges the three-layer configuration.
   • TinkerZeroServiceProvider is conditionally registered in non-production environments.
   • The LogManager binding is normalized.
4. booted callback — After boot, every registered Artisan command receives two additional global options:
   • --xdebug — Suppresses the Xdebug restart handler.
   • --configuration — Allows runtime config key-value overrides (e.g. --configuration=app.name=foo).
5. CommandStarting event listener — Checks --xdebug and applies --configuration values into the running config.
6. withExceptions — Maps ValidationException to a formatted multi-line message. Exceptions are only reported (not swallowed) when not running from a PHAR.

Diagram: Bootstrap phase sequence

Sources: bootstrap/app.php36-116

---

Service Provider Bindings

AppServiceProvider (app/Providers/AppServiceProvider.php) registers two bindings during register():

Binding	Type	Purpose
OutputStyle::class	singletonIf	Symfony output style, configured from $_SERVER['argv'] and auto-configured verbosity flags
ConsoleLogger::class	singleton	PSR logger backed by the OutputStyle instance

The OutputStyle binding manually calls ConsoleApplication::configureIO() so that -v / -vv / -vvv flags are respected at the time of binding, independently of when Application::run() is called.

Sources: app/Providers/AppServiceProvider.php36-62

---

Subsystem Dependency Map

Diagram: Class-level dependencies across subsystems (code entity names)

Sources: bootstrap/app.php36-116 app/Providers/AppServiceProvider.php1-68

---

Framework Foundation

The application is built on Laravel Zero (laravel-zero/framework: ^12.0), which itself wraps laravel/framework: ^12.0. Key framework components in use:

Component	Role in ai-commit
Illuminate\Support\ServiceProvider	Base class for AppServiceProvider
Illuminate\Console\OutputStyle	Console output abstraction
Illuminate\Support\Manager	Base class for GeneratorManager
Illuminate\Config\Repository	Base class for ConfigManager
LaravelZero\Framework\Application	Application container and lifecycle
Symfony\Component\Console\*	Command parsing, input/output, logging
GuzzleHttp\Client	HTTP client used by API-based generators
Symfony\Component\Process\Process	Shell execution for CLI-based generators

Sources: composer.json58-68

---

Key Design Patterns

Illuminate Manager Pattern

GeneratorManager extends Illuminate\Support\Manager. This provides the driver(), getDefaultDriver(), and createDriver() methods. Concrete generator drivers are resolved by combining the driver name from configuration with a class naming convention. See Generator System Architecture for full details.

Three-Layer Configuration

ConfigManager merges three sources in ascending priority:

1. config/ai-commit.php — PHP defaults baked into the application.
2. ~/.ai-commit/.ai-commit.json — Global user config.
3. .ai-commit.json — Local project config.

See Configuration System Implementation for full details.

Command-Centric Dispatch

All user interaction flows through Symfony Console commands. The CommitCommand orchestrates the full workflow: staging validation, type selection, generator invocation, confirmation loop, and git commit execution. See Command Architecture.

Abstract Generator + Contract

AbstractGenerator provides shared infrastructure (config injection, output stream, process runner) while GeneratorContract defines the public interface (generate()). Each backend implements generate() either by calling an HTTP client or by spawning a subprocess. See Generator Architecture.

---

Runtime Flow: commit Command

Diagram: Simplified runtime flow from CLI invocation to git commit

Sources: bootstrap/app.php36-116

---

Child Pages

The subsystems described above each have dedicated pages with full implementation details:

Page	Title	Covers
4.1	Application Foundation	Bootstrap, AppServiceProvider, ConfigManager::load(), global options, exception handling
4.2	Command Architecture	CommitCommand, ConfigCommand, ThanksCommand, command registration
4.3	Generator System Architecture	GeneratorManager, AbstractGenerator, GeneratorContract, driver resolution
4.4	Configuration System Implementation	ConfigManager, three-layer merge, putLocal/putGlobal, JSON serialization
4.5	HTTP Client Layer	AbstractClient, OpenAI/Moonshot/Ernie clients, streaming, retry