# Architecture of the no-mistakes Git Proxy: A Local Validation Pipeline Deep Dive

> Explore the no-mistakes git proxy architecture. This local Git intermediary validates commits with pipelines before pushing to your remote repository. Ensure code quality locally.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: architecture
- Published: 2026-06-28

---

**The no-mistakes git proxy is a local Git intermediary that intercepts pushes to a custom remote, spins up disposable work-trees to execute validation pipelines, and only forwards commits to the actual remote after all checks pass.**

The `kunchenguid/no-mistakes` repository implements a sophisticated local Git proxy that acts as a gatekeeper between your working directory and the upstream repository. This architecture ensures that every commit undergoes rigorous validation—including rebasing, testing, linting, and documentation checks—before reaching the remote. Unlike traditional CI/CD that runs after push, this **no-mistakes git proxy architecture** validates code locally using temporary work-trees that leave your original checkout untouched.

## Core Architectural Layers

The proxy splits functionality across five distinct layers, each handling specific responsibilities from command parsing to Git operations.

### CLI Entry Point and Remote Interface

Built with the Cobra framework, the CLI serves as the Git remote interface. When you configure `no-mistakes` as a Git remote and execute `git push no-mistakes`, Git invokes the binary at [`internal/cli/root.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/root.go). This entry point parses the push command, initializes a run record, and triggers the validation pipeline while presenting itself to Git as a standard remote helper.

### Pipeline Orchestration Layer

The [`internal/pipeline/pipeline.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/pipeline.go) file coordinates the execution of validation steps in strict sequence. It tracks run state in a local SQLite database, manages step transitions, and determines whether to continue execution, pause for user intervention when a finding occurs, or abort the entire operation. This orchestrator treats each validation phase as a discrete unit that must report success before the next begins.

### Step Execution and Disposable Work-Trees

Individual validation steps reside in `internal/pipeline/steps/` and include dedicated files like [`rebase.go`](https://github.com/kunchenguid/no-mistakes/blob/main/rebase.go), [`test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/test.go), [`lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/lint.go), and [`push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/push.go). Each step operates within a **disposable work-tree**—a temporary Git workspace created by utilities in [`internal/git/git.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/git.go)—ensuring your original repository remains untouched while subprocesses run commands like `go test -race ./...` or `npm run lint`. Steps can auto-fix safe issues, emit findings requiring user approval, or fail fast depending on severity.

### Daemon and Background Process Management

For long-running operations and TUI attachment capabilities, [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go) implements a persistent background service. This daemon manages work-tree-bound processes, handles cancellation requests, and maintains the interactive interface, allowing you to detach and re-attach to validation runs without losing state.

### Persistent Storage with SQLite

The [`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go) module provides a lightweight SQLite database that stores per-repository configuration, run metadata, findings, and timestamps. This persistence layer enables the proxy to resume interrupted runs and maintain state across CLI invocations, supporting the `no-mistakes` TUI for reviewing pending findings.

## The Push Flow: From Local Branch to Remote

When you push to the `no-mistakes` remote, the architecture executes a rigorous validation chain:

1. **Work-tree creation**: The CLI spins up a disposable work-tree via [`internal/git/git.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/git.go), isolating validation from your working directory.
2. **Pipeline initialization**: A new run record is created in SQLite via [`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go), and the pipeline coordinator in [`internal/pipeline/pipeline.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/pipeline.go) begins sequential step execution.
3. **Sequential validation**: The system runs rebase → test → lint → docs → push, with each step executing in the temporary work-tree.
4. **Finding handling**: If a step produces a finding, the pipeline pauses, storing the state in SQLite until you approve, fix, or skip the issue via the TUI.
5. **Remote push**: Only after all steps report success does [`internal/pipeline/steps/push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/push.go) perform a lease-guarded push to the actual remote and optionally open a pull request.

## Key Source Files and Implementation Details

Understanding the **no-mistakes git proxy architecture** requires familiarity with these specific implementation files:

- **[`internal/cli/root.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/root.go)**: Entry point that implements the Git remote protocol and handles `git push no-mistakes` invocations.
- **[`internal/cli/wizard.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/wizard.go)**: Run-attachment logic and interactive wizard for connecting to existing validation runs.
- **[`internal/pipeline/pipeline.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/pipeline.go)**: Central coordinator that manages step execution order and run state transitions.
- **[`internal/pipeline/steps/rebase.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/rebase.go)**: Handles rebasing onto the remote-tracking branch within the disposable work-tree.
- **[`internal/pipeline/steps/test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/test.go)**: Executes test suites like `go test -race ./...` and reports results.
- **[`internal/pipeline/steps/lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/lint.go)**: Runs linting tools including `go vet` and custom skill-checks.
- **[`internal/pipeline/steps/push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/push.go)**: Performs the final lease-guarded force-push to the target remote.
- **[`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go)**: Background service for managing long-running processes and TUI sessions.
- **[`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go)**: SQLite schema and queries for persisting run metadata and findings.
- **[`internal/git/git.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/git.go)**: Low-level Git operations including repository root detection and work-tree management.

## Summary

- The **no-mistakes git proxy architecture** intercepts pushes via a custom Git remote, acting as a local gatekeeper.
- **Disposable work-trees** in [`internal/git/git.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/git.go) isolate validation from your working directory, ensuring safe experimentation.
- **Pipeline orchestration** in [`internal/pipeline/pipeline.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/pipeline.go) coordinates sequential validation steps (rebase, test, lint, docs, push).
- **SQLite persistence** via [`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go) enables run resumption and finding management across sessions.
- **Background daemon** support in [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go) handles long-running processes and TUI interactions.
- Only after all validation steps pass does the proxy forward commits to the actual remote using lease-guarded pushes.

## Frequently Asked Questions

### What is the no-mistakes git proxy?

The no-mistakes git proxy is a local CLI tool built with Cobra that functions as a Git remote intermediary. It intercepts pushes to a custom remote name (e.g., `no-mistakes`), validates the code through automated pipelines, and only forwards commits to the actual upstream repository after all checks pass, preventing broken code from entering the remote.

### How does the disposable work-tree mechanism work?

When you push to the proxy, the system creates a temporary Git work-tree via utilities in [`internal/git/git.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/git.go). This isolated directory contains a copy of your branch where validation steps run destructive commands like rebasing or force-checkout without affecting your original working directory. Once validation completes, the disposable work-tree is cleaned up automatically.

### What happens when a validation step fails?

If a step in `internal/pipeline/steps/` encounters an issue, it emits a *finding* that gets stored in the SQLite database via [`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go). The pipeline pauses, allowing you to address the issue through the TUI by fixing the code, approving the finding, or skipping that specific check. The run resumes only after you explicitly handle the finding.

### How does the proxy handle concurrent runs?

The daemon manager in [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go) maintains a background service that tracks active runs in SQLite. This architecture prevents conflicts by managing work-tree-bound processes centrally and ensuring that only one validation pipeline operates per repository workspace at a time, though multiple repositories can run validations simultaneously.