# ufomiao/zcf architecture

> Architecture diagram of the GitHub repository ufomiao/zcf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ufomiao/zcf
- Repository: https://github.com/ufomiao/zcf

## Overview

ZCF is an interactive and scriptable CLI for initializing Claude Code and Codex environments. The main workflow selects a tool adapter, validates options, then configures the chosen environment; documented initialization can include workflows, API/CCR, and MCP setup. Separate commands handle menus, updates, switching, and uninstalling. The graph includes the shared configuration and installation layers. Some capability links rely on README statements or SOURCE INDEX references because their implementation excerpts were not provided.

Main entry points: [`src/code-tools/claude-code/legacy-init.ts`](https://github.com/ufomiao/zcf/blob/main/src/code-tools/claude-code/legacy-init.ts) (Claude initialization), [`src/commands/init.ts`](https://github.com/ufomiao/zcf/blob/main/src/commands/init.ts) (Init command), [`src/utils/claude-code-config-manager.ts`](https://github.com/ufomiao/zcf/blob/main/src/utils/claude-code-config-manager.ts) (Claude config manager), [`src/cli-setup.ts`](https://github.com/ufomiao/zcf/blob/main/src/cli-setup.ts) (Command registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and commands"]
  node_cli["CLI entry<br/>[cli.ts]"]
  node_command_setup["Command registration<br/>[cli-setup.ts]"]
  node_init["Init command<br/>[init.ts]"]
  node_menu["Interactive menu<br/>[menu.ts]"]
  node_other_commands["Other commands"]
end

subgraph group_tools["Tool adapters"]
  node_registry["Adapter registry<br/>[registry.ts]"]
  node_definitions["Tool definitions<br/>[definitions.ts]"]
  node_claude_adapter["Claude adapter<br/>[adapter.ts]"]
  node_claude_init["Claude initialization<br/>[legacy-init.ts]"]
  node_codex_adapter["Codex adapter<br/>[adapter.ts]"]
  node_codex_config["Codex configuration<br/>[codex.ts]"]
end

subgraph group_setup["Setup capabilities"]
  node_workflows["Workflow setup<br/>[workflows.ts]"]
  node_api_providers["API providers<br/>[api-providers.ts]"]
  node_mcp_services["MCP services<br/>[mcp-services.ts]"]
  node_installer["Setup installer<br/>[installer.ts]"]
end

subgraph group_state["Configuration and state"]
  node_claude_settings["Claude config manager"]
  node_claude_config["Claude config helpers<br/>[claude-config.ts]"]
  node_ccr_config["CCR configuration<br/>[config.ts]"]
  node_zcf_config[("ZCF configuration<br/>[zcf-config.ts]")]
  node_config["General configuration<br/>[config.ts]"]
  node_json_config["JSON configuration I/O<br/>[json-config.ts]"]
  node_claude_types["Claude config model"]
end

subgraph group_shared["Shared utilities"]
  node_shared_utils["Filesystem and platform<br/>[fs-operations.ts]"]
  node_platform["Platform support<br/>[platform.ts]"]
  node_features["Feature operations<br/>[features.ts]"]
  node_banner["CLI presentation<br/>[banner.ts]"]
  node_prompts["Prompt controls<br/>[toggle-prompt.ts]"]
  node_errors["Error handling<br/>[error-handler.ts]"]
end

node_user(("CLI user"))

node_user -->|"runs"| node_cli
node_cli -->|"starts"| node_command_setup
node_command_setup -->|"registers"| node_init
node_command_setup -->|"registers"| node_menu
node_command_setup -->|"registers"| node_other_commands
node_menu -->|"dispatches"| node_init
node_init -->|"selects adapter"| node_registry
node_init -->|"validates options"| node_claude_init
node_init -->|"displays"| node_banner
node_registry -->|"uses definitions"| node_definitions
node_claude_adapter -.->|"delegates initialization"| node_claude_init
node_codex_adapter -->|"uses"| node_codex_config
node_claude_init -->|"configures workflows"| node_workflows
node_claude_init -->|"configures providers"| node_api_providers
node_claude_init -->|"configures MCP"| node_mcp_services
node_claude_init -->|"uses"| node_installer
node_claude_settings -->|"reads and writes"| node_zcf_config
node_claude_settings -->|"updates settings"| node_claude_config
node_claude_settings -->|"reads CCR"| node_ccr_config
node_claude_config -->|"writes JSON"| node_json_config
node_config -->|"uses filesystem"| node_shared_utils
node_config -->|"uses JSON I/O"| node_json_config
node_zcf_config -->|"uses filesystem"| node_shared_utils
node_installer -->|"checks platform"| node_platform
node_installer -->|"uses filesystem"| node_shared_utils
node_claude_settings -->|"uses model"| node_claude_types
node_menu -->|"offers features"| node_features
node_init -->|"handles errors"| node_errors
node_claude_init -.->|"prompts user"| node_prompts

click node_cli "https://github.com/ufomiao/zcf/blob/main/src/cli.ts"
click node_command_setup "https://github.com/ufomiao/zcf/blob/main/src/cli-setup.ts"
click node_init "https://github.com/ufomiao/zcf/blob/main/src/commands/init.ts"
click node_menu "https://github.com/ufomiao/zcf/blob/main/src/commands/menu.ts"
click node_other_commands "https://github.com/ufomiao/zcf/tree/main/src/commands"
click node_registry "https://github.com/ufomiao/zcf/blob/main/src/code-tools/registry.ts"
click node_definitions "https://github.com/ufomiao/zcf/blob/main/src/code-tools/definitions.ts"
click node_claude_adapter "https://github.com/ufomiao/zcf/blob/main/src/code-tools/claude-code/adapter.ts"
click node_claude_init "https://github.com/ufomiao/zcf/blob/main/src/code-tools/claude-code/legacy-init.ts"
click node_codex_adapter "https://github.com/ufomiao/zcf/blob/main/src/code-tools/codex/adapter.ts"
click node_codex_config "https://github.com/ufomiao/zcf/blob/main/src/utils/code-tools/codex.ts"
click node_workflows "https://github.com/ufomiao/zcf/blob/main/src/config/workflows.ts"
click node_api_providers "https://github.com/ufomiao/zcf/blob/main/src/config/api-providers.ts"
click node_mcp_services "https://github.com/ufomiao/zcf/blob/main/src/config/mcp-services.ts"
click node_installer "https://github.com/ufomiao/zcf/blob/main/src/utils/installer.ts"
click node_claude_settings "https://github.com/ufomiao/zcf/blob/main/src/utils/claude-code-config-manager.ts"
click node_claude_config "https://github.com/ufomiao/zcf/blob/main/src/utils/claude-config.ts"
click node_ccr_config "https://github.com/ufomiao/zcf/blob/main/src/utils/ccr/config.ts"
click node_zcf_config "https://github.com/ufomiao/zcf/blob/main/src/utils/zcf-config.ts"
click node_config "https://github.com/ufomiao/zcf/blob/main/src/utils/config.ts"
click node_json_config "https://github.com/ufomiao/zcf/blob/main/src/utils/json-config.ts"
click node_claude_types "https://github.com/ufomiao/zcf/blob/main/src/types/claude-code-config.ts"
click node_shared_utils "https://github.com/ufomiao/zcf/blob/main/src/utils/fs-operations.ts"
click node_platform "https://github.com/ufomiao/zcf/blob/main/src/utils/platform.ts"
click node_features "https://github.com/ufomiao/zcf/blob/main/src/utils/features.ts"
click node_banner "https://github.com/ufomiao/zcf/blob/main/src/utils/banner.ts"
click node_prompts "https://github.com/ufomiao/zcf/blob/main/src/utils/toggle-prompt.ts"
click node_errors "https://github.com/ufomiao/zcf/blob/main/src/utils/error-handler.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_command_setup,node_init,node_menu,node_other_commands,node_user toneBlue
class node_registry,node_definitions,node_claude_adapter,node_claude_init,node_codex_adapter,node_codex_config toneAmber
class node_workflows,node_api_providers,node_mcp_services,node_installer toneMint
class node_claude_settings,node_claude_config,node_ccr_config,node_zcf_config,node_config,node_json_config,node_claude_types toneRose
class node_shared_utils,node_platform,node_features,node_banner,node_prompts,node_errors toneIndigo
```

## Components

### CLI and commands

- [CLI entry](https://github.com/ufomiao/zcf/blob/main/src/cli.ts): `src/cli.ts`
- [Command registration](https://github.com/ufomiao/zcf/blob/main/src/cli-setup.ts): `src/cli-setup.ts`
- [Init command](https://github.com/ufomiao/zcf/blob/main/src/commands/init.ts): `src/commands/init.ts`
- [Interactive menu](https://github.com/ufomiao/zcf/blob/main/src/commands/menu.ts): `src/commands/menu.ts`
- [Other commands](https://github.com/ufomiao/zcf/tree/main/src/commands): `src/commands`

### Tool adapters

- [Adapter registry](https://github.com/ufomiao/zcf/blob/main/src/code-tools/registry.ts): `src/code-tools/registry.ts`
- [Tool definitions](https://github.com/ufomiao/zcf/blob/main/src/code-tools/definitions.ts): `src/code-tools/definitions.ts`
- [Claude adapter](https://github.com/ufomiao/zcf/blob/main/src/code-tools/claude-code/adapter.ts): `src/code-tools/claude-code/adapter.ts`
- [Claude initialization](https://github.com/ufomiao/zcf/blob/main/src/code-tools/claude-code/legacy-init.ts): `src/code-tools/claude-code/legacy-init.ts`
- [Codex adapter](https://github.com/ufomiao/zcf/blob/main/src/code-tools/codex/adapter.ts): `src/code-tools/codex/adapter.ts`
- [Codex configuration](https://github.com/ufomiao/zcf/blob/main/src/utils/code-tools/codex.ts): `src/utils/code-tools/codex.ts`

### Setup capabilities

- [Workflow setup](https://github.com/ufomiao/zcf/blob/main/src/config/workflows.ts): `src/config/workflows.ts`
- [API providers](https://github.com/ufomiao/zcf/blob/main/src/config/api-providers.ts): `src/config/api-providers.ts`
- [MCP services](https://github.com/ufomiao/zcf/blob/main/src/config/mcp-services.ts): `src/config/mcp-services.ts`
- [Setup installer](https://github.com/ufomiao/zcf/blob/main/src/utils/installer.ts): `src/utils/installer.ts`

### Configuration and state

- [Claude config manager](https://github.com/ufomiao/zcf/blob/main/src/utils/claude-code-config-manager.ts): `src/utils/claude-code-config-manager.ts`
- [Claude config helpers](https://github.com/ufomiao/zcf/blob/main/src/utils/claude-config.ts): `src/utils/claude-config.ts`
- [CCR configuration](https://github.com/ufomiao/zcf/blob/main/src/utils/ccr/config.ts): `src/utils/ccr/config.ts`
- [ZCF configuration](https://github.com/ufomiao/zcf/blob/main/src/utils/zcf-config.ts): `src/utils/zcf-config.ts`
- [General configuration](https://github.com/ufomiao/zcf/blob/main/src/utils/config.ts): `src/utils/config.ts`
- [JSON configuration I/O](https://github.com/ufomiao/zcf/blob/main/src/utils/json-config.ts): `src/utils/json-config.ts`
- [Claude config model](https://github.com/ufomiao/zcf/blob/main/src/types/claude-code-config.ts): `src/types/claude-code-config.ts`

### Shared utilities

- [Filesystem and platform](https://github.com/ufomiao/zcf/blob/main/src/utils/fs-operations.ts): `src/utils/fs-operations.ts`
- [Platform support](https://github.com/ufomiao/zcf/blob/main/src/utils/platform.ts): `src/utils/platform.ts`
- [Feature operations](https://github.com/ufomiao/zcf/blob/main/src/utils/features.ts): `src/utils/features.ts`
- [CLI presentation](https://github.com/ufomiao/zcf/blob/main/src/utils/banner.ts): `src/utils/banner.ts`
- [Prompt controls](https://github.com/ufomiao/zcf/blob/main/src/utils/toggle-prompt.ts): `src/utils/toggle-prompt.ts`
- [Error handling](https://github.com/ufomiao/zcf/blob/main/src/utils/error-handler.ts): `src/utils/error-handler.ts`

### Other components

- **CLI user**

## Connections

- CLI user → CLI entry: runs (evidence: `README.md`)
- CLI entry → Command registration: starts (evidence: `src/cli.ts`)
- Command registration → Init command: registers (evidence: `src/cli-setup.ts`)
- Command registration → Interactive menu: registers (evidence: `src/cli-setup.ts`)
- Command registration → Other commands: registers (evidence: `src/cli-setup.ts`)
- Interactive menu → Init command: dispatches (evidence: `src/commands/menu.ts`)
- Init command → Adapter registry: selects adapter (evidence: `src/commands/init.ts`)
- Init command → Claude initialization: validates options (evidence: `src/commands/init.ts`)
- Init command → CLI presentation: displays (evidence: `src/commands/init.ts`)
- Adapter registry → Tool definitions: uses definitions (evidence: `src/code-tools/index.ts`)
- Claude adapter → Claude initialization: delegates initialization
- Codex adapter → Codex configuration: uses (evidence: `src/code-tools/codex/adapter.ts`)
- Claude initialization → Workflow setup: configures workflows (evidence: `src/code-tools/claude-code/legacy-init.ts`)
- Claude initialization → API providers: configures providers (evidence: `src/code-tools/claude-code/legacy-init.ts`)
- Claude initialization → MCP services: configures MCP (evidence: `src/code-tools/claude-code/legacy-init.ts`)
- Claude initialization → Setup installer: uses (evidence: `src/code-tools/claude-code/legacy-init.ts`)
- Claude config manager → ZCF configuration: reads and writes (evidence: `src/utils/claude-code-config-manager.ts`)
- Claude config manager → Claude config helpers: updates settings (evidence: `src/utils/claude-code-config-manager.ts`)
- Claude config manager → CCR configuration: reads CCR (evidence: `src/utils/claude-code-config-manager.ts`)
- Claude config helpers → JSON configuration I/O: writes JSON (evidence: `src/utils/claude-config.ts`)
- General configuration → Filesystem and platform: uses filesystem (evidence: `src/utils/config.ts`)
- General configuration → JSON configuration I/O: uses JSON I/O (evidence: `src/utils/config.ts`)
- ZCF configuration → Filesystem and platform: uses filesystem (evidence: `src/utils/zcf-config.ts`)
- Setup installer → Platform support: checks platform (evidence: `src/utils/installer.ts`)
- Setup installer → Filesystem and platform: uses filesystem (evidence: `src/utils/installer.ts`)
- Claude config manager → Claude config model: uses model (evidence: `src/utils/claude-code-config-manager.ts`)
- Interactive menu → Feature operations: offers features (evidence: `src/commands/menu.ts`)
- Init command → Error handling: handles errors (evidence: `src/commands/init.ts`)
- Claude initialization → Prompt controls: prompts user (evidence: `src/code-tools/claude-code/legacy-init.ts`)
