🏗️ Architecture Overview

Composer Skills adopts a clean three-layer architecture, strictly separating "domain model / detection & installation", "SDK wrappers", and "application tooling" so that each layer can evolve and be tested independently.

Three-Layer Architecture Diagram

Each layer communicates only with the layer directly below it; lower layers never depend back on upper layers.

Responsibilities of Each Layer

Layer	Responsibility	Package Path
🧱 Base Layer	Domain model, installation detection, shared utilities — zero coupling to business logic	pkg/domain pkg/detector pkg/installer pkg/composerutils
🔌 SDK Layer	Wraps two categories of external systems: the local Composer CLI and the remote Packagist API	pkg/composer pkg/client pkg/repository
🖥️ Application Layer	End-user-facing CLI and developer-facing documentation	cmd/composer-skills docs/

Package Path Table

Package	Path	Purpose
Domain model	github.com/scagogogo/composer-skills/pkg/domain	Data structure definitions, shared by the SDK layer
Detector	github.com/scagogogo/composer-skills/pkg/detector	Cross-OS detection of whether composer is installed
Installer	github.com/scagogogo/composer-skills/pkg/installer	Automatic installation of Composer + PHP
Shared utilities	github.com/scagogogo/composer-skills/pkg/composerutils	Filesystem, HTTP, and Mock helpers
Composer SDK	github.com/scagogogo/composer-skills/pkg/composer	234 methods wrapping the composer CLI
Packagist client	github.com/scagogogo/composer-skills/pkg/client	20 methods accessing the Packagist REST API
Repository layer	github.com/scagogogo/composer-skills/pkg/repository	Repository operations, depends on domain
CLI tool	github.com/scagogogo/composer-skills/cmd/composer-skills	Cobra command-line entry point

🎯 Design Goals

• Extensible 📈 — Adding a new Composer subcommand only requires adding a method in pkg/composer; new API endpoints go in pkg/client, without mutual interference. Options allows injecting custom Detector/Installer/CommandExecutor.
• Testable 🧪 — The Mock mechanism runs through both the base layer and the SDK layer (testMode + SetupMockOutput + MockCommandExecutor); 586 test cases run without a real Composer / PHP / network.
• Type-safe ✅ — Methods return structured types (AuditInfo, OutdatedInfo, VersionInfo), saying goodbye to strings.Split for parsing string output.
• Zero-config 📦 — AutoInstall: true is on by default; when Composer is missing, it installs automatically.

🚀 Why This Layering

Splitting the CLI wrapper (pkg/composer) and the API client (pkg/client) into two independent SDKs stems from their different deployment dependencies: the former requires PHP + Composer on the local machine, while the latter is pure Go with zero external dependencies. With this separation, users can pull in only the parts they need — a server running Packagist queries in CI does not need PHP installed.

Reading Order

We recommend reading Layered Architecture first, then Package Dependencies, and finally Testability Design.