Architecture Overview

🚀Custy Architecture

Implementation-Aligned

Follow a CLI request through configuration, orchestration, domain services, infrastructure, and presentation.

Commandapp/

📦Category

Architecture

🚀Quick Command

entrypoint -> CLI -> pipeline -> workflow -> services -> effects

---

Typerpipelineworkflow engineGit service

---

🐍

Runtime

Python 3.14+

💻

CLI Framework

Typer and Rich

📁

Primary Source

app

🪄

Execution Style

Sequential orchestration

Overview

Custy uses a pragmatic layered architecture. Public commands live in the CLI layer, but most meaningful operations are expressed as pipeline steps that delegate to a shared workflow engine. The workflow engine coordinates focused services for Git, changelog generation, backup, initialization, project-file updates, and branch transitions.

ℹ️Responsibility layers, not rigid folder walls

The layers describe the active dependency flow. They are not a strict clean- architecture boundary: some core modules import CLI enums, Rich presentation, or UI helpers. These pages document the implementation as it exists rather than implying stronger isolation.

---

Responsibility Layers

💻CLI and Presentation

app/cli, app/ui, app/theme, app/utils

Registers commands, declares options, resolves user input, stores global context, configures logging, and renders Rich output.

🪄Application Orchestration

app/core/pipeline and app/core/workflow

Expands profiles, creates registered steps, carries runtime state, and coordinates ordered validation, generation, Git, release, and finalization operations.

🏗️Domain Services

git_ops, changelog, initialize, backup, cleanup

Implements reusable Git policy, version generation, changelog transformation, project scaffolding, backups, and branch or file cleanup.

📦Infrastructure and Resources

subprocess, filesystem, TOML, Jinja, packaged templates

Executes Git commands, reads and writes project files, loads configuration, renders templates, and supplies initialization resources.

---

🔄Primary Runtime Path

The common pipeline-backed command path; initialization and a few focused handlers use specialized core coordinators.

🕒Workflow Timeline

1

Entrypoint

The installed custy script or python -m app loads app.cli.main:app.

completed

2

Global callback

Resolve global configuration, create AppContext, configure logging, and render banner or help behavior.

completed

3

Command module

Parse typed options, resolve effective values, and select a service or pipeline profile.

completed

4

Composition

Build WorkflowConfig, WorkflowEngine, GitContext, and registered steps.

completed

5

Sequential execution

Each step delegates one operation to the engine or another focused coordinator.

current

6

Effects and presentation

Services access Git, files, templates, or subprocesses while Rich and logging report progress and failures.

pending

---

Primary Dependencies

📦Command Execution

Typer command→Argument resolver

Convert explicit options and project configuration into a typed effective model.

---

Argument resolver→WorkflowEngineBuilder

Transport resolved values into one workflow configuration.

---

CommandResolver→StepRegistry

Turn profile definitions into concrete registered step instances.

---

Pipeline step→WorkflowEngine

Delegate one ordered operation through a shared GitContext.

📦External Effects

WorkflowEngine→GitService

Apply high-level repository policy without calling subprocess directly.

---

GitService→IGitCommandExecutor

Use a protocol-backed low-level command boundary.

---

ChangelogGenerator→GitService and JinjaRenderer

Collect repository history, build domain models, and render Markdown.

---

InitMain→ScaffoldGenerator

Build an initialization plan and create selected packaged resources.

---

🏗️Architectural Patterns

Patterns are used selectively; they do not form a general plugin framework.

Pattern	Purpose	Implementation
Builder	Construct complex workflow and initialization inputs incrementally.	WorkflowEngineBuilder and InitBuilder
Registry	Map stable step names to concrete pipeline classes.	StepRegistry and register_all_steps
Strategy	Generate and sort version tags using interchangeable algorithms.	TagStrategy and TagSorter implementations
Factory	Centralize service, provider, and sorter construction.	create_git_service, MessageProviderFactory, and TagSorterFactory
Pipeline	Execute explicit steps in a predictable sequence.	CommandResolver, PipelineBuilder, Pipeline, and BaseStep
Facade / Application Service	Give steps a cohesive workflow API over several services.	WorkflowEngine

---

Important Architectural Boundaries

• Pipeline execution is sequential and non-transactional; earlier effects are not rolled back when a later step fails.
• Internal profiles and registered steps are not automatically public Run choices.
• Configuration is project-owned after initialization and cached once per process by the shared loader.
• Version generation, version-file synchronization, and tag sorting are separate responsibilities.
• Changelog collection and transformation build domain models before the final Markdown write.
• Registry and strategy interfaces are contributor extension points, not a published third-party plugin contract.

---

Continue

🚀Related Commands

Commands commonly used together with this command.

CLI Layer

Trace entrypoints, command modules, global context, and registration.

Core Layer

Review each core subsystem and its current coupling.

Pipeline Engine

Follow profile resolution through registered sequential steps.

Developer Guide

Use the architecture when changing or extending Custy.