# boyter/scc architecture

> Architecture diagram of the GitHub repository boyter/scc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boyter/scc
- Repository: https://github.com/boyter/scc

## Overview

The “scc” project is a high-performance command‐line tool written in Go that counts source code metrics (e.g., lines of code, blank lines, comments, complexity estimates, and unique lines) for many languages. It is similar in spirit to tools like cloc, sloccount, and tokei. The project’s purpose is to analyze codebases quickly by reading files from disk—honoring ignore files and language mappings—and outputting detailed metrics in a variety of formats (tabular, JSON, CSV, HTML, SQL, etc.). In terms of architectural style, this is a CLI analytics tool built in Go with a “worker pool” style for file processing and a modular design that separates input handling, processing/analysis, and output formatting.

##### Main Components
- CLI Frontend: The “main.go” and executables (in cmd/) expose the command-line interface. This is the user entry-point where arguments, flag configurations (e.g., –ci, –by-file, –remap-unknown, –no-cocomo, etc.) are parsed.
- File System Scanner/Input Manager: This component is responsible for traversing directories (using worker routines) and gathering files to be processed. It respects .gitignore, .ignore, and .sccignore files. The directory-walker (an implementation found in the processor or scripts) fills a “file list queue.”
- File Reading and Job Dispatching: Each file is encapsulated into a “FileJob” that contains its metadata (path, language, bytes) and content. This is coordinated by the worker pool found in the “processor” directory (e.g., workers.go, file.go, filereader.go).
- Parser and Analyzer Core: This module (implemented in processor/) uses a small state machine to continuously evaluate file content, distinguishing between code, blank lines, comments, and even performs complexity estimation (by counting branch keywords). It leverages language definitions loaded (and generated from languages.json) to know the rules for each supported language.
- Remapping and Language Detection: Utilizing the languages.json and corresponding generated Go constants (via go generate), this component maps file extensions, shebang rules, and internal markers to the correct language.
- Data Aggregation and Metrics Calculation: It aggregates file-by-file counts into overall project statistics; here, additional calculations such as the Unique Lines Of Code (ULOC), DRYness metrics, and even COCOMO cost estimations are computed.
- Output Formatter(s): Based on user-specified flags (–format, –format-multi, etc.), this module converts the aggregated statistics into various output formats (tabular, JSON, CSV, HTML, SQL, and even OpenMetrics). This component is clearly isolated so that modifications in one output format do not affect the core processing.
- Optional Extras – Badges Generator: Under the “cmd/badges” directory, a separate command builds badge outputs that display metrics on repository pages. This module integrates with the rest by consuming the metrics data.

##### Relationships and Interactions
- The CLI component gathers user parameters and passes them to the “Input Manager.”
- The Input Manager scans the file system and dispatches file paths to the File Job Dispatcher, which then creates FileJob objects.
- The File Job Dispatcher sends FileJob objects to a Worker Pool in the Parser/Analyzer Core.
- Each worker processes a file using language-specific rules (using a state machine) and outputs raw metrics.
- These results are aggregated by the “Metrics Aggregator,” which then passes the final counts to the “Output Formatter(s).”
- Optional modules like the Badge Generator might consume the aggregated results to render a visual badge for repository hosting platforms.

##### Architectural Patterns and Design Principles
- Modular Design: Separation of concerns is evident, where file scanning, processing, aggregating, and formatting are handled independently.
- Extensibility: The use of languages.json (and its generated Go constants) demonstrates the ability to add or modify language rules easily.

##### Applicable Technologies, Frameworks, and Libraries
- Go (the main language)
- Standard Go libraries for I/O and concurrency (sync and channels)
- Docker (as evidenced by Dockerfile and container instructions)
- GitHub Actions and other CI tools (workflow yaml files)
- The “go generate” tool for integrating language definitions into processor/constants.go
- External integration (e.g., Badge rendering via cmd/badges)

##### Elements
- Annotations or notes inside components to indicate key functions (e.g., “State Machine for Line Classification” in Parser/Analyzer, “Worker Pool for Concurrency”).

##### Additional Advice
- Detail as much as possible by breaking down the system into logical submodules—don’t be afraid to partition the processor component into “File Parsing” and “Complexity Analysis.”
- That each module is annotated with its responsibilities and the technologies it uses.
- Interplay between configuration files (like languages.json) and runtime modules (e.g., language detection) for a complete picture.
- Performance metrics and benchmarking as a side note to highlight areas optimized through concurrency and state-machine design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["CLI Frontend (main.go, cmd/)"]:::cli
    B["File Scanner / Input Manager"]:::scanner
    C["File Reading & Job Dispatching (Worker Pool)"]:::job
    D["Parser & Analyzer Core (State Machine for Metrics)"]:::parser
    E["Remapping & Language Detection"]:::remap
    F["Data Aggregation & Metrics Calculation"]:::agg
    G["Output Formatter(s)"]:::output
    H["Badge Generator"]:::badge
    I["CI/CD & DevOps Support"]:::devops

    A -->|"passes_parameters"| B
    B -->|"scans_for_files"| C
    C -->|"dispatches_FileJobs"| D
    E -- "provides_language_rules" --> D
    D -->|"outputs_metrics"| F
    F -->|"formats_output"| G
    F -->|"feeds_metrics"| H
    I -.->|"builds_deploys"| A

    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef scanner fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef job fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef parser fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef remap fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef agg fill:#9370DB,stroke:#000,stroke-width:2px;
    classDef output fill:#40E0D0,stroke:#000,stroke-width:2px;
    classDef badge fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef devops fill:#F5DEB3,stroke:#000,stroke-width:2px;

    click A "https://github.com/boyter/scc/blob/master/main.go"
    click A "https://github.com/boyter/scc/tree/master/cmd/"
    click B "https://github.com/boyter/scc/blob/master/processor/filereader.go"
    click C "https://github.com/boyter/scc/blob/master/processor/file.go"
    click C "https://github.com/boyter/scc/blob/master/processor/workers.go"
    click D "https://github.com/boyter/scc/blob/master/processor/processor.go"
    click D "https://github.com/boyter/scc/blob/master/processor/detector.go"
    click D "https://github.com/boyter/scc/blob/master/processor/structs.go"
    click E "https://github.com/boyter/scc/blob/master/languages.json"
    click E "https://github.com/boyter/scc/blob/master/processor/constants.go"
    click F "https://github.com/boyter/scc/blob/master/processor/formatters.go"
    click F "https://github.com/boyter/scc/blob/master/processor/cocomo.go"
    click G "https://github.com/boyter/scc/blob/master/processor/formatters.go"
    click G "https://github.com/boyter/scc/blob/master/SCC-OUTPUT-REPORT.html"
    click H "https://github.com/boyter/scc/tree/master/cmd/badges/"
    click I "https://github.com/boyter/scc/tree/master/.github/"
    click I "https://github.com/boyter/scc/tree/master/Dockerfile"
    click I "https://github.com/boyter/scc/tree/master/.devcontainer/"
```
