# valdecircarvalho/contalinha architecture

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

- Interactive diagram: https://gitdiagram.com/valdecircarvalho/contalinha
- Repository: https://github.com/valdecircarvalho/contalinha

## Overview

This repo is a **single-machine Python utility** (not a distributed system) that **analyzes a directory on disk** and produces:
- **Aggregated statistics** (files, total lines, blank/comment/code/billable lines, sizes, per-extension breakdown)
- A **CSV report** (summary + per-extension + per-file details)

It has **two entrypoints**:
- **Primary**: `contalinha-ui.py` — **Tkinter GUI** (directory picker, tables, sort/scroll, progress bar, save button)
- **Legacy**: `contalinha.py` — **CLI** output (uses `rich`), still generates CSV

##### Read the repo as “components” (from the file tree)
Top-level “modules” to represent:

- `contalinha-ui.py`
- Presentation layer (Tkinter widgets)
- User interactions: select directory, start analysis, sort table, save CSV
- Progress reporting
- `contalinha.py`
- CLI presentation (console)
- Argument parsing / interactive prompt
- Pretty output via `rich`
- (Shared domain logic is not explicit from the tree; it may be duplicated in both files.)
- Directory traversal
- File-type detection / extension grouping
- Line classification (blank/comment/code/billable)
- Stats aggregation
- CSV report generation
- `requirements.txt`
- External dependency: `rich` (CLI only)
- `build.py`
- Build/packaging workflow (e.g., creating `contalinha.exe` or bundling)

- **C4 Level 1 (Context)**: who uses it and what external resources it touches (filesystem)
- **C4 Level 2 (Container-ish)**: GUI app vs CLI app (two executables/scripts) and their dependencies
- **C4 Level 3 (Component)**: the internal pipeline steps (scan → parse → aggregate → present → export)

##### Actors / External systems
- **User**
- **Local File System** (the directory being analyzed; files read)
- **Local Output Directory** (where CSV is written)

Optional but accurate:
- **OS / Python Runtime**
- **Tkinter (GUI framework)** as a library dependency
- **rich (CLI rendering library)** as a dependency

##### Application entrypoints (two “containers”)
- **GUI App (`contalinha-ui.py`)**
- **CLI App (`contalinha.py`)** (legacy)

##### Directory Selection / Input
- GUI: file dialog + validation + “clear existing results” warning
- CLI: argv parsing or prompt
##### File Discovery / Traversal
- Walk directory tree
- Filter/ignore rules (if any exist in code; if not, keep generic: “enumerates files”)
##### File Reader
- Open/read file content (handle encoding/errors if implemented)
##### Line Classifier
- Counts:
- total lines
- blank lines
- comment lines (language-dependent heuristics)
- code lines
- billable lines (= total - blank)
##### Aggregator / Reducer
- Per-file stats
- Per-extension stats
- Overall totals + percentages
##### Report Generator (CSV)
- Produces `result_YYYY-MM-DD-HH-MM.csv`
- Contains:
- statistics by extension
- per-file detailed list

##### `CLI App` → `CSV Writer` → `File System`: “Write result_*.csv”

- `Developer` → `build.py` → “packager” (if used) → outputs: `contalinha.exe` (legacy per README)
- `requirements.txt` influences CLI runtime dependency installation

##### Internal components: pipeline steps + CSV writer + renderers

This makes it obvious this is a **desktop utility**, not a service.

Even if implemented in one script file, separate conceptual responsibilities:
- Traversal vs parsing vs aggregation vs presentation vs export
This project benefits from that separation because it has **two UIs** that rely on the same underlying computation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Actors / External Systems
    %% =========================
    U["User"]:::actor
    DEV["Developer"]:::actor

    FS[("Local File System\n(Directories & Source Files)")]:::storage
    OUT[("Local Output Directory\n(CSV destination)")]:::storage
    CSV["CSV Report File\nresult_YYYY-MM-DD-HH-MM.csv"]:::artifact

    %% =========================
    %% Runtime: Two Entrypoints
    %% =========================
    subgraph "Runtime (Single-machine Python utility)"
        direction TB

        GUI["contalinha-ui.py\n(Primary Tkinter GUI)"]:::app
        CLI["contalinha.py\n(Legacy CLI)"]:::app

        %% --------
        %% Libraries
        %% --------
        subgraph "Libraries / Runtime Dependencies"
            direction TB
            TK["tkinter\n(GUI framework)"]:::lib
            RICH["rich\n(CLI rendering)"]:::lib
            PY["Python Runtime / OS"]:::platform
        end

        %% =========================
        %% Shared Conceptual Analyzer Core (Pipeline)
        %% (may be duplicated across scripts)
        %% =========================
        subgraph "Analyzer Core (conceptual pipeline; implemented inline/duplicated)"
            direction TB

            INP["Directory Input & Validation\n(GUI dialog / CLI argv or prompt)"]:::component
            TRAV["File Discovery / Traversal\n(walk directory tree)"]:::component
            READ["File Reader\n(open/read text; handle errors if any)"]:::component
            CLASS["Line Classifier\n(total/blank/comment/code/billable)"]:::component
            AGG["Stats Aggregator / Reducer\n(per-file, per-extension, totals, % )"]:::component
            WARN["Warnings & Edge Cases\n(e.g., unrecognized extensions)"]:::crosscut
            PROG["Progress Reporting\n(GUI progress bar updates)"]:::crosscut
            PRES["Presentation Formatting\n(data -> tables/panels)"]:::component
            SORT["GUI Table Sorting/Scrolling\n(presentation-only)"]:::crosscut
            CSVGEN["CSV Report Generator\n(summary + per-extension + per-file)"]:::component
        end

        %% Presentation targets
        GUIVIEW["GUI Tables & Widgets\n(summary + per-extension; scroll/sort)"]:::ui
        CLIVIEW["Console Output\n(rich tables/panels)"]:::ui
    end

    %% =========================
    %% Build / Distribution Path
    %% =========================
    subgraph "Build / Distribution (optional)"
        direction TB
        BUILD["build.py\n(Packaging workflow)"]:::build
        REQ["requirements.txt\n(Runtime deps)"]:::config
        README["README.md\n(Usage & distribution notes)"]:::doc
        PKG["Packager (e.g., PyInstaller)\n(if used)"]:::tool
        ART["Build Artifact\n(contalinha.exe - legacy note)"]:::artifact
    end

    %% =========================
    %% Connections: GUI path
    %% =========================
    U -->|"select_directory"| GUI
    GUI -->|"invoke_analysis"| INP
    INP -->|"validated_path"| TRAV
    TRAV -->|"enumerate_files"| FS
    FS -->|"file_paths"| TRAV
    TRAV -->|"open_read"| READ
    READ -->|"text_lines"| CLASS
    CLASS -->|"per_file_counts"| AGG
    AGG -->|"emit_warnings"| WARN
    AGG -->|"progress_events"| PROG
    AGG -->|"computed_stats"| PRES
    PRES -->|"render_tables"| GUIVIEW
    GUI -->|"display_widgets"| GUIVIEW
    GUIVIEW -->|"sort_columns"| SORT

    U -->|"save_statistics"| GUI
    PRES -->|"csv_rows"| CSVGEN
    CSVGEN -->|"write_result_*.csv"| OUT
    OUT -->|"create_file"| CSV

    %% =========================
    %% Connections: CLI path (legacy)
    %% =========================
    U -->|"provide_path(argv/prompt)"| CLI
    CLI -->|"invoke_analysis"| INP
    PRES -->|"render_via_rich"| RICH
    RICH -->|"print_tables"| CLIVIEW
    CLI -->|"display_output"| CLIVIEW
    CSVGEN -->|"write_result_*.csv"| OUT

    %% =========================
    %% Runtime dependencies wiring
    %% =========================
    PY -->|"runs"| GUI
    PY -->|"runs"| CLI
    GUI -->|"uses"| TK
    CLI -->|"uses"| RICH

    %% =========================
    %% Build / Distribution connections
    %% =========================
    DEV -->|"run_build"| BUILD
    BUILD -->|"uses"| PKG
    PKG -->|"bundle"| ART
    README -->|"documents"| GUI
    README -->|"documents"| CLI
    REQ -->|"installs_deps_for"| CLI
    REQ -->|"lists"| RICH

    %% =========================
    %% Notes
    %% =========================
    NOTE1["Note: Analyzer Core is shown as a shared pipeline for clarity.\nIn this repo it is likely duplicated inline in both entrypoints\n(candidate for shared module)."]:::note
    AGG -.->|"design_note"| NOTE1

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click GUI "https://github.com/valdecircarvalho/contalinha/blob/main/contalinha-ui.py"
    click CLI "https://github.com/valdecircarvalho/contalinha/blob/main/contalinha.py"
    click CSVGEN "https://github.com/valdecircarvalho/contalinha/blob/main/contalinha-ui.py"
    click CSVGEN "https://github.com/valdecircarvalho/contalinha/blob/main/contalinha.py"
    click BUILD "https://github.com/valdecircarvalho/contalinha/blob/main/build.py"
    click REQ "https://github.com/valdecircarvalho/contalinha/blob/main/requirements.txt"
    click README "https://github.com/valdecircarvalho/contalinha/blob/main/README.md"

    %% =========================
    %% Styles
    %% =========================
    classDef actor fill:#ECEFF1,stroke:#546E7A,stroke-width:2,color:#263238
    classDef storage fill:#E3F2FD,stroke:#1565C0,stroke-width:2,color:#0D47A1
    classDef app fill:#E8F5E9,stroke:#2E7D32,stroke-width:3,color:#1B5E20
    classDef component fill:#FFFFFF,stroke:#455A64,stroke-width:2,color:#263238
    classDef ui fill:#FFF8E1,stroke:#FF8F00,stroke-width:2,color:#E65100
    classDef lib fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2,color:#4A148C,stroke-dasharray: 5 4
    classDef crosscut fill:#FCE4EC,stroke:#AD1457,stroke-width:2,color:#880E4F
    classDef artifact fill:#E0F7FA,stroke:#00838F,stroke-width:2,color:#004D40
    classDef build fill:#FFEBEE,stroke:#C62828,stroke-width:2,color:#B71C1C
    classDef tool fill:#E8EAF6,stroke:#283593,stroke-width:2,color:#1A237E,stroke-dasharray: 5 4
    classDef config fill:#F1F8E9,stroke:#558B2F,stroke-width:2,color:#33691E
    classDef doc fill:#FFF3E0,stroke:#EF6C00,stroke-width:2,color:#E65100
    classDef platform fill:#EDE7F6,stroke:#5E35B1,stroke-width:2,color:#311B92
    classDef note fill:#FAFAFA,stroke:#9E9E9E,stroke-width:1,color:#424242,stroke-dasharray: 3 3
```
