# ziad-maged/vcs-protection architecture

> Architecture diagram of the GitHub repository ziad-maged/vcs-protection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ziad-maged/vcs-protection
- Repository: https://github.com/ziad-maged/vcs-protection

## Overview

vcs-protection is a branch-protection tool with local Git-hook enforcement and a GitHub Actions guard. The main workflow configures protected branch rules, then checks attempted local ref changes and pushes; the remote guard checks GitHub push and pull-request events and can report or revert violations. The graph also includes rule-management, status/audit, installation, and workflow-generation capabilities. Relationships are based on the README and SOURCE INDEX references; sampled source excerpts provide additional evidence for hook and configuration behavior.

Main entry points: [`src/hooks/handlers.ts`](https://github.com/ziad-maged/vcs-protection/blob/master/src/hooks/handlers.ts) (Hook enforcement), [`src/cli.ts`](https://github.com/ziad-maged/vcs-protection/blob/master/src/cli.ts) (CLI entry), [`src/commands/shared.ts`](https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/shared.ts) (Command services), [`src/config/load.ts`](https://github.com/ziad-maged/vcs-protection/blob/master/src/config/load.ts) (Effective config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and commands"]
  node_cli["CLI entry<br/>[cli.ts]"]
  node_rules_cmd["Rule commands<br/>[rules.ts]"]
  node_init_cmd["Initialization<br/>[init.ts]"]
  node_status_cmd["Status and doctor<br/>[status.ts]"]
  node_github_cmd["GitHub and audit<br/>[github.ts]"]
  node_install_cmd["Hook management<br/>[install.ts]"]
  node_ci_cmd["CI guard command<br/>[ciGuard.ts]"]
end

subgraph group_local["Local protection"]
  node_hook_shim["Git hook shims<br/>[shim.ts]"]
  node_hook_handler["Hook enforcement<br/>[handlers.ts]"]
  node_evaluator["Rule evaluation<br/>[evaluate.ts]"]
  node_audit["Bypass audit log<br/>[log.ts]"]
end

subgraph group_github["GitHub enforcement"]
  node_workflow["Workflow generation<br/>[workflow.ts]"]
  node_guard["Remote guard logic<br/>[guard.ts]"]
  node_gh_client["GitHub API client<br/>[client.ts]"]
  node_gh_remote["GitHub remote parsing<br/>[remote.ts]"]
end

subgraph group_config["Rules and repository"]
  node_matcher["Branch matching<br/>[match.ts]"]
  node_config_load["Effective config<br/>[load.ts]"]
  node_config_schema["Config schema<br/>[schema.ts]"]
  node_git_repo["Git repository access<br/>[repo.ts]"]
  node_git_exec["Git command runner<br/>[exec.ts]"]
end

subgraph group_support["Setup and visibility"]
  node_shared["Command services<br/>[shared.ts]"]
end

node_user(("Repository user"))
node_github(("GitHub"))
node_git[("Git repository")]

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches to"| node_rules_cmd
node_cli -->|"dispatches to"| node_init_cmd
node_cli -->|"dispatches to"| node_status_cmd
node_cli -->|"dispatches to"| node_github_cmd
node_cli -->|"dispatches to"| node_install_cmd
node_cli -->|"dispatches to"| node_ci_cmd
node_cli -->|"dispatches hooks"| node_hook_handler
node_rules_cmd -->|"uses services"| node_shared
node_init_cmd -->|"uses services"| node_shared
node_status_cmd -->|"uses services"| node_shared
node_github_cmd -->|"uses services"| node_shared
node_install_cmd -->|"installs shims"| node_hook_shim
node_init_cmd -->|"loads config"| node_config_load
node_init_cmd -->|"generates workflow"| node_workflow
node_rules_cmd -->|"updates workflow"| node_workflow
node_shared -->|"loads effective rules"| node_config_load
node_shared -->|"creates client"| node_gh_client
node_shared -->|"parses remote"| node_gh_remote
node_hook_shim -->|"invokes"| node_hook_handler
node_hook_handler -->|"loads rules"| node_config_load
node_hook_handler -->|"evaluates updates"| node_evaluator
node_hook_handler -->|"matches branch"| node_matcher
node_hook_handler -->|"inspects repository"| node_git_repo
node_hook_handler -->|"checks Git result"| node_git_exec
node_hook_handler -->|"records bypass"| node_audit
node_hook_handler -->|"repairs hooks"| node_hook_shim
node_config_load -->|"parses config"| node_config_schema
node_config_load -->|"finds default ref"| node_git_repo
node_config_load -->|"reads remote config"| node_git_exec
node_git_repo -->|"runs Git queries"| node_git_exec
node_evaluator -->|"uses rule types"| node_config_schema
node_evaluator -->|"matches rules"| node_matcher
node_hook_shim -->|"runs on Git events"| node_git
node_git_repo -->|"reads repository state"| node_git
node_ci_cmd -->|"runs guard"| node_guard
node_guard -->|"uses API"| node_gh_client
node_guard -->|"checks protected branches"| node_matcher
node_gh_client -->|"requests REST API"| node_github
node_workflow -->|"runs on GitHub Actions"| node_github
node_guard -->|"checks and reverts pushes"| node_github
node_github_cmd -->|"reads bypass log"| node_audit

click node_cli "https://github.com/ziad-maged/vcs-protection/blob/master/src/cli.ts"
click node_rules_cmd "https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/rules.ts"
click node_init_cmd "https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/init.ts"
click node_status_cmd "https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/status.ts"
click node_github_cmd "https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/github.ts"
click node_install_cmd "https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/install.ts"
click node_ci_cmd "https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/ciGuard.ts"
click node_hook_shim "https://github.com/ziad-maged/vcs-protection/blob/master/src/hooks/shim.ts"
click node_hook_handler "https://github.com/ziad-maged/vcs-protection/blob/master/src/hooks/handlers.ts"
click node_evaluator "https://github.com/ziad-maged/vcs-protection/blob/master/src/rules/evaluate.ts"
click node_matcher "https://github.com/ziad-maged/vcs-protection/blob/master/src/rules/match.ts"
click node_audit "https://github.com/ziad-maged/vcs-protection/blob/master/src/audit/log.ts"
click node_config_load "https://github.com/ziad-maged/vcs-protection/blob/master/src/config/load.ts"
click node_config_schema "https://github.com/ziad-maged/vcs-protection/blob/master/src/config/schema.ts"
click node_git_repo "https://github.com/ziad-maged/vcs-protection/blob/master/src/git/repo.ts"
click node_git_exec "https://github.com/ziad-maged/vcs-protection/blob/master/src/git/exec.ts"
click node_shared "https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/shared.ts"
click node_workflow "https://github.com/ziad-maged/vcs-protection/blob/master/src/github/workflow.ts"
click node_guard "https://github.com/ziad-maged/vcs-protection/blob/master/src/github/guard.ts"
click node_gh_client "https://github.com/ziad-maged/vcs-protection/blob/master/src/github/client.ts"
click node_gh_remote "https://github.com/ziad-maged/vcs-protection/blob/master/src/github/remote.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_rules_cmd,node_init_cmd,node_status_cmd,node_github_cmd,node_install_cmd,node_ci_cmd,node_user toneBlue
class node_hook_shim,node_hook_handler,node_evaluator,node_audit,node_git toneAmber
class node_workflow,node_guard,node_gh_client,node_gh_remote toneMint
class node_matcher,node_config_load,node_config_schema,node_git_repo,node_git_exec toneRose
class node_shared,node_github toneIndigo
```

## Components

### CLI and commands

- [CLI entry](https://github.com/ziad-maged/vcs-protection/blob/master/src/cli.ts): `src/cli.ts`
- [Rule commands](https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/rules.ts): `src/commands/rules.ts`
- [Initialization](https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/init.ts): `src/commands/init.ts`
- [Status and doctor](https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/status.ts): `src/commands/status.ts`
- [GitHub and audit](https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/github.ts): `src/commands/github.ts`
- [Hook management](https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/install.ts): `src/commands/install.ts`
- [CI guard command](https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/ciGuard.ts): `src/commands/ciGuard.ts`

### Local protection

- [Git hook shims](https://github.com/ziad-maged/vcs-protection/blob/master/src/hooks/shim.ts): `src/hooks/shim.ts`
- [Hook enforcement](https://github.com/ziad-maged/vcs-protection/blob/master/src/hooks/handlers.ts): `src/hooks/handlers.ts`
- [Rule evaluation](https://github.com/ziad-maged/vcs-protection/blob/master/src/rules/evaluate.ts): `src/rules/evaluate.ts`
- [Bypass audit log](https://github.com/ziad-maged/vcs-protection/blob/master/src/audit/log.ts): `src/audit/log.ts`

### GitHub enforcement

- [Workflow generation](https://github.com/ziad-maged/vcs-protection/blob/master/src/github/workflow.ts): `src/github/workflow.ts`
- [Remote guard logic](https://github.com/ziad-maged/vcs-protection/blob/master/src/github/guard.ts): `src/github/guard.ts`
- [GitHub API client](https://github.com/ziad-maged/vcs-protection/blob/master/src/github/client.ts): `src/github/client.ts`
- [GitHub remote parsing](https://github.com/ziad-maged/vcs-protection/blob/master/src/github/remote.ts): `src/github/remote.ts`

### Rules and repository

- [Branch matching](https://github.com/ziad-maged/vcs-protection/blob/master/src/rules/match.ts): `src/rules/match.ts`
- [Effective config](https://github.com/ziad-maged/vcs-protection/blob/master/src/config/load.ts): `src/config/load.ts`
- [Config schema](https://github.com/ziad-maged/vcs-protection/blob/master/src/config/schema.ts): `src/config/schema.ts`
- [Git repository access](https://github.com/ziad-maged/vcs-protection/blob/master/src/git/repo.ts): `src/git/repo.ts`
- [Git command runner](https://github.com/ziad-maged/vcs-protection/blob/master/src/git/exec.ts): `src/git/exec.ts`

### Setup and visibility

- [Command services](https://github.com/ziad-maged/vcs-protection/blob/master/src/commands/shared.ts): `src/commands/shared.ts`

### Other components

- **Repository user**
- **GitHub**
- **Git repository**

## Connections

- Repository user → CLI entry: runs commands (evidence: `README.md`)
- CLI entry → Rule commands: dispatches to (evidence: `src/cli.ts`)
- CLI entry → Initialization: dispatches to (evidence: `src/cli.ts`)
- CLI entry → Status and doctor: dispatches to (evidence: `src/cli.ts`)
- CLI entry → GitHub and audit: dispatches to (evidence: `src/cli.ts`)
- CLI entry → Hook management: dispatches to (evidence: `src/cli.ts`)
- CLI entry → CI guard command: dispatches to (evidence: `src/cli.ts`)
- CLI entry → Hook enforcement: dispatches hooks (evidence: `src/cli.ts`)
- Rule commands → Command services: uses services (evidence: `src/commands/rules.ts`)
- Initialization → Command services: uses services (evidence: `src/commands/init.ts`)
- Status and doctor → Command services: uses services (evidence: `src/commands/status.ts`)
- GitHub and audit → Command services: uses services (evidence: `src/commands/github.ts`)
- Hook management → Git hook shims: installs shims (evidence: `src/commands/install.ts`)
- Initialization → Effective config: loads config (evidence: `src/commands/init.ts`)
- Initialization → Workflow generation: generates workflow (evidence: `src/commands/init.ts`)
- Rule commands → Workflow generation: updates workflow (evidence: `src/commands/rules.ts`)
- Command services → Effective config: loads effective rules (evidence: `src/commands/shared.ts`)
- Command services → GitHub API client: creates client (evidence: `src/commands/shared.ts`)
- Command services → GitHub remote parsing: parses remote (evidence: `src/commands/shared.ts`)
- Git hook shims → Hook enforcement: invokes (evidence: `README.md`)
- Hook enforcement → Effective config: loads rules (evidence: `src/hooks/handlers.ts`)
- Hook enforcement → Rule evaluation: evaluates updates (evidence: `src/hooks/handlers.ts`)
- Hook enforcement → Branch matching: matches branch (evidence: `src/hooks/handlers.ts`)
- Hook enforcement → Git repository access: inspects repository (evidence: `src/hooks/handlers.ts`)
- Hook enforcement → Git command runner: checks Git result (evidence: `src/hooks/handlers.ts`)
- Hook enforcement → Bypass audit log: records bypass (evidence: `src/hooks/handlers.ts`)
- Hook enforcement → Git hook shims: repairs hooks (evidence: `src/hooks/handlers.ts`)
- Effective config → Config schema: parses config (evidence: `src/config/load.ts`)
- Effective config → Git repository access: finds default ref (evidence: `src/config/load.ts`)
- Effective config → Git command runner: reads remote config (evidence: `src/config/load.ts`)
- Git repository access → Git command runner: runs Git queries (evidence: `src/git/repo.ts`)
- Rule evaluation → Config schema: uses rule types (evidence: `src/rules/evaluate.ts`)
- Rule evaluation → Branch matching: matches rules (evidence: `src/rules/evaluate.ts`)
- Git hook shims → Git repository: runs on Git events (evidence: `README.md`)
- Git repository access → Git repository: reads repository state (evidence: `src/git/repo.ts`)
- CI guard command → Remote guard logic: runs guard (evidence: `src/commands/ciGuard.ts`)
- Remote guard logic → GitHub API client: uses API (evidence: `src/github/guard.ts`)
- Remote guard logic → Branch matching: checks protected branches (evidence: `src/github/guard.ts`)
- GitHub API client → GitHub: requests REST API (evidence: `src/github/client.ts`)
- Workflow generation → GitHub: runs on GitHub Actions (evidence: `README.md`)
- Remote guard logic → GitHub: checks and reverts pushes (evidence: `README.md`)
- GitHub and audit → Bypass audit log: reads bypass log (evidence: `src/commands/github.ts`)
