System Modularity Inspection & Codebase Peeling Subsystem Operational Architecture Guide
1. Executive Summary & Design Philosophy
The System Modularity Inspection & Codebase Peeling Subsystem (pkg/systempeel) provides structural inspection, dynamic modular command peeling, lines-of-code (LOC) metrics analysis, and threshold enforcement across the ZQK Knowledge Kernel.
As a high-performance systems engineering framework, ZQK must maintain clean module boundaries, prevent monolithic command bloat, and dynamically register peeled subcommands into the active Cobra command hierarchy. Governed by core modularity policy POL-DEFAULT-b17f54c251eb3c4d, the subsystem enforces architectural decoupling by:
- Structural Codebase Inspection: Scanning Go source packages to determine file inventories, file-level lines of code, and subcommand composition.
- Dynamic Command Peeling: Enabling subcommands to be isolated into modular packages and re-attached dynamically to parent Cobra commands via
AttachPeeledCommand. - Threshold Sentinel & Bloat Detection: Identifying source files exceeding configurable lines-of-code thresholds (defaulting to 1,000 LOC for package inspections) to prevent architectural decay.
- Thread-Safe Component Registry: Maintaining an in-memory concurrent registry (
PeeledComponentRegistry) with read-write mutex synchronization for tracking peeled system components across worker routines. - High Concurrency & 100.0% Statement Coverage: Guaranteeing fail-closed error boundaries, hermetic cleanup, and full test verification under concurrent
goroutinelabelsworkers.
2. Architectural Overview
In complex CLI architectures, command trees tend to accrete monolithic implementations where multiple subcommands, flags, and heavy business logic are concentrated in single packages or oversized files. This accretion degrades compilation times, complicates unit testing, increases cyclomatic complexity, and introduces merge conflicts across autonomous agent swarms.
The pkg/systempeel package solves this challenge through a peeling workflow:
- Inspection:
SystemInspectoranalyzes candidate system packages, counting lines of code, locating subcommands, and isolating large files. - Peeling: Monolithic commands are decomposed ("peeled") into modular packages with dedicated lifecycle hooks.
- Registration: Peeled components register their metadata into
PeeledComponentRegistry. - Dynamic Attachment: Parent command trees bind peeled subcommands dynamically at boot time using
AttachPeeledCommand.
flowchart TD
subgraph Filesystem["Codebase Filesystem Tree"]
Dir["cmd/zqk/system/ or target pkg"] --> GoFiles["Go Source Files (*.go)"]
Dir --> NonGo["Non-Go Assets (filtered out)"]
Dir --> SubDirs["Subdirectories (filtered out)"]
end
subgraph InspectionEngine["pkg/systempeel Subsystem"]
Inspector["SystemInspector<br/>(NewSystemInspector)"]
Scanner["GoFileScanner<br/>(scanGoFiles)"]
Metrics["LOCMetricEngine<br/>(InspectSystemPackage)"]
Sentinel["ThresholdSentinel<br/>(FindFilesExceedingThreshold)"]
Registry["PeeledComponentRegistry<br/>(GetGlobalRegistry / sync.RWMutex)"]
end
subgraph RuntimeCLI["Cobra Command Runtime"]
ParentCmd["Parent Command (*cobra.Command)"]
Attach["AttachPeeledCommand"]
ChildCmd["Peeled Subcommand (*cobra.Command)"]
end
Filesystem --> Inspector
Inspector --> Scanner
Scanner --> Metrics
Scanner --> Sentinel
Metrics --> Registry
Registry --> Attach
ParentCmd --> Attach
ChildCmd --> Attach
Attach --> ParentCmd
3. Core Component Topology
The subsystem is composed of decoupled architectural components:
graph TD
A["SystemInspector"] -->|"invokes"| B["scanGoFiles"]
B -->|"reads entries"| C["fileutil.ReadDir"]
B -->|"reads content"| D["fileutil.ReadFile"]
A -->|"aggregates"| E["InspectSystemPackage"]
A -->|"evaluates"| F["FindFilesExceedingThreshold"]
E -->|"produces"| G["PeeledCommandMetadata"]
E -->|"detects >1000 LOC"| H["LargeFileReport"]
F -->|"produces"| H
G -->|"stored in"| I["PeeledComponentRegistry"]
J["AttachPeeledCommand"] -->|"attaches to"| K["cobra.Command"]
1. SystemInspector
The primary operational entry point:
RootDir: Base directory path against which relative package paths are resolved.NewSystemInspector(rootDir string) *SystemInspector: Instantiates an inspector bound to a root workspace.
2. Internal Scanner (scanGoFiles)
The directory traversal and filtering layer:
- Resolves package directories using
filepath.Join(si.RootDir, pkgRelPath). - Skips nested subdirectories (
entry.IsDir()) and non-Go assets (!strings.HasSuffix(entry.Name(), ".go")). - Reads file contents via
fileutil.ReadFileand calculates lines of code via line splitting. - Enforces strict error propagation when directories do not exist, paths are files, or permissions are denied.
3. Metric Engine & Metadata Model (PeeledCommandMetadata)
Captures structural metadata:
Name: Base directory name of the inspected package.PackagePath: Relative package directory path.LinesOfCode: Total lines of code across all scanned Go files in the package.Subcommands: Derived list of subcommand base names (e.g.check.gobecomescheck).LargeFiles: Sorted slice ofLargeFileReportrecords identifying files exceeding threshold limits.
4. Threshold Sentinel (FindFilesExceedingThreshold)
Monitors and isolates oversized files:
- Compares each file's LOC against a caller-specified
maxLOC. - Sorts reports descending by
LinesOfCodeso that the most critical complexity hotspots appear first.
5. Thread-Safe Registry (PeeledComponentRegistry)
Coordinates peeled components across concurrent agent routines:
- Protected by
sync.RWMutexto guarantee safe concurrent reads (Get,List) and writes (Register). - Provides a shared singleton via
GetGlobalRegistry()as well as support for isolated test instances. - Returns components sorted alphabetically by
NameinList()for deterministic output.
6. Cobra Command Binder (AttachPeeledCommand)
Binds modular subcommands to parent command trees:
- Performs defensive nil-checks on both parent and child command pointers.
- Dynamically calls
parent.AddCommand(cmd)when both arguments are valid.
4. Peeling & Modularization Lifecycle
The end-to-end lifecycle of inspecting, peeling, and registering a modular command is depicted in the following sequence diagram:
sequenceDiagram
autonumber
actor Dev as Agent / Engineer
participant SI as SystemInspector
participant FS as Local Filesystem
participant Reg as PeeledComponentRegistry
participant Cobra as Cobra Root Command
Dev->>SI: NewSystemInspector(rootDir)
Dev->>SI: InspectSystemPackage("cmd/zqk/system")
SI->>FS: ReadDir("cmd/zqk/system")
FS-->>SI: Directory entries
loop For each entry
alt Entry is Go File
SI->>FS: ReadFile(entry)
FS-->>SI: File contents
SI->>SI: Calculate LOC & Subcommand Name
else Entry is Subdir or Non-Go
SI->>SI: Skip entry
end
end
SI->>SI: Sort LargeFiles descending (>1000 LOC)
SI-->>Dev: Return PeeledCommandMetadata
alt Bloat Detected
Dev->>SI: FindFilesExceedingThreshold("cmd/zqk/system", 500)
SI-->>Dev: Return []LargeFileReport
Dev->>Dev: Refactor / Peel subcommands into separate packages
end
Dev->>Reg: Register("system", metadata)
Dev->>Cobra: AttachPeeledCommand(rootCmd, peeledSubcommand)
Cobra-->>Dev: Subcommand mounted dynamically
5. Large File Detection & Complexity Metrics
File size directly correlates with maintainability issues and architectural drift. The subsystem applies dual-layer threshold evaluation:
Built-in 1,000 LOC Floor (InspectSystemPackage)
When inspecting a package, InspectSystemPackage automatically flags any Go file exceeding 1,000 lines of code:
if f.loc > 1000 {
largeFiles = append(largeFiles, LargeFileReport{
RelativePath: f.relPath,
LinesOfCode: f.loc,
BaseName: f.baseName,
})
}
All large file reports are sorted descending by LinesOfCode.
Tunable Thresholding (FindFilesExceedingThreshold)
For targeted refactoring campaigns or stricter modularity policies (e.g. 300 LOC or 500 LOC limits), FindFilesExceedingThreshold accepts an arbitrary maxLOC parameter:
reports, err := inspector.FindFilesExceedingThreshold("cmd/zqk/system", 300)
if err != nil {
return fmt.Errorf("threshold inspection failed: %w", err)
}
for _, report := range reports {
log.Printf("HOTSPOT: %s (%d lines of code)", report.RelativePath, report.LinesOfCode)
}
6. Concurrency & Thread-Safety Guarantees
The pkg/systempeel subsystem is designed for concurrent execution in multi-agent and parallel worker environments:
- Read-Write Mutex Protection:
PeeledComponentRegistrysynchronizes all access with async.RWMutex. Multiple goroutines can read (Get,List) concurrently using shared read locks (r.mu.RLock()), while registration (Register) acquires exclusive write locks (r.mu.Lock()). - Stateless Inspectors:
SystemInspectorholds only an immutableRootDirstring after construction. Multiple concurrent goroutines can executeInspectSystemPackageorFindFilesExceedingThresholdacross different or identical paths without state interference. - Managed Goroutines: Concurrency tests and background scans utilize
goroutinelabels.NewGoroutine("...", "...").StartSimple(...)to enforce managed goroutine standards and avoid nakedgoroutines.
7. Verification & Three-Fold Proof Breakdown
The subsystem satisfies rigorous verification criteria across the Three-Fold Proof:
| Verification Dimension | Contract / Guarantee | Implementation Proof |
|---|---|---|
| Static Floor Invariant | Statement test coverage strictly \(\ge 85.0\%\) (target 100.0%) | Verified at 100.0% statement coverage via go test -cover ./pkg/systempeel. |
| Operational Dynamic Proof | Traversal, metric calculation, threshold detection, sorting, and registry lifecycle | Comprehensive test scenarios covering multi-file packages, empty directories, large files, and concurrent workers. |
| Negative Adversarial Boundary | Fail-closed error handling on invalid paths, unreadable files, nil pointers, and payload integrity | Boundary tests covering non-existent directories, file-as-directory errors, chmod 0000 permission denials, nil command attachments, and payload integrity checks. |
8. Operational Usage Recipes
Inspecting a Package
package main
import (
"fmt"
"log"
"github.com/zqk-os/zqk/pkg/systempeel"
)
func main() {
inspector := systempeel.NewSystemInspector(".")
meta, err := inspector.InspectSystemPackage("cmd/zqk/system")
if err != nil {
log.Fatalf("Inspection failed: %v", err)
}
fmt.Printf("Package: %s\n", meta.Name)
fmt.Printf("Total LOC: %d\n", meta.LinesOfCode)
fmt.Printf("Subcommands: %v\n", meta.Subcommands)
for _, lf := range meta.LargeFiles {
fmt.Printf(" Large File (>1000 LOC): %s (%d LOC)\n", lf.RelativePath, lf.LinesOfCode)
}
}
Registering and Attaching a Peeled Command
package main
import (
"github.com/spf13/cobra"
"github.com/zqk-os/zqk/pkg/systempeel"
)
func RegisterAndAttach(rootCmd *cobra.Command, peeledCmd *cobra.Command, meta *systempeel.PeeledCommandMetadata) {
registry := systempeel.GetGlobalRegistry()
registry.Register(meta.Name, meta)
systempeel.AttachPeeledCommand(rootCmd, peeledCmd)
}
9. Verification & Test Execution
Run Targeted Unit Test Suite
ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -v -timeout 30s -cover ./pkg/systempeel
Run Race Detection
ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -race -timeout 30s ./pkg/systempeel
Verify Code Formatting
gofmt -w pkg/systempeel/
Run Source Hygiene & Tree Gate
./bin/zqk-vet -suite hygiene,tree
Run Public Release Payload Check
sh scripts/open-core/check-public-release-payload.sh .