# azisk/zpace architecture

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

- Interactive diagram: https://gitdiagram.com/azisk/zpace
- Repository: https://github.com/azisk/zpace

## Overview

##### Project type and purpose
- Zpace is a command-line disk-space analysis tool written in Python.
- It scans directories, categorizes files by type (videos, docs, code, etc.), detects special directories (node_modules, .venv, .git), and presents actionable insights.

##### File structure
- Top level:
- main.py – entry point for CLI invocation
- pyproject.toml – build/packaging config for Poetry/UV tools
- ARCHITECTURE.md, README.md, CHANGELOG.md – documentation
- test_.py – unit tests
- .github/workflows/*.yml – CI/CD pipelines
- No frontend/backend split, but internally it likely follows a pipeline pattern:
- CLI parser → Scanner → Categorizer → Reporter/Formatter
- CI workflows (ci.yml, publish-pypi.yml) show automated testing and release.

##### README for additional insights
- Lists core features (categorization, special-dir detection, sparse file handling).
- Describes usage flags (-n, -m).
- Development instructions reference Ruff (lint/format), pytest, and UV tooling.

a. Main components
1. CLI Interface
- Responsible for parsing arguments (-n, -m, target path).
2. File System Scanner
- Recursively walks directories, gathers file metadata (size, type, permissions).
3. File Categorizer
- Applies rules to group files into categories (Documents, Videos, Code, Special Dirs).
- Handles sparse file detection (Docker images).
4. Data Aggregator / Metrics Engine
- Maintains per-category totals, identifies top-N biggest files.
5. Reporter / Formatter
- Formats results into console tables or JSON (if extended).
6. External Services / OS
- Disk I/O subsystem (POSIX APIs, macOS full-disk-access).
7. Tests & CI
- pytest test suite, pre-commit hooks, GitHub Actions pipelines.

b. Relationships and interactions
- User invokes “zpace” command → CLI Interface
- CLI Interface passes parameters to Scanner
- Scanner issues filesystem calls, streams file entries to Categorizer
- Categorizer tags files, forwards to Data Aggregator
- Data Aggregator computes metrics, then hands results to Reporter
- Tests drive individual components; CI runs entire pipeline on push.

c. Architectural patterns/design principles
- Pipeline pattern: each stage (scan, categorize, aggregate, report) is a separate module.
- Single-Responsibility: CLI vs. scanning vs. reporting each isolated.
- Plugin-style extensibility: categorization rules or reporter formats could be pluggable.
- Lightweight modularity: no heavy frameworks, easy to test each stage.

d. Key technologies/frameworks
- Python 3.x (specified in .python-version)
- uv (CLI tool manager)
- pytest for testing
- Ruff for linting/formatting
- GitHub Actions for CI/CD
- PyPI publishing (publish-pypi.yml)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Pipeline (Blue)
    subgraph "Core Pipeline"
        style CorePipeline fill:none,stroke:none
        CLI["zpace CLI"]:::core
        Parser["Parser\n(flags: -n, -m, path)"]:::core
        Scanner["Scanner\n(os.walk, lstat, sparse checks)"]:::core
        Categorizer["Categorizer\n(rule sets:\nDocuments, Videos,\nCode, Special-dirs)"]:::core
        Aggregator["Aggregator\n(per-category totals,\ntop-N logic)"]:::core
        Reporter["Reporter\n(console table,\nJSON extension)"]:::core
        Console["Console Output"]:::core
    end

    CLI -->|invokes| Parser
    Parser -->|parameters| Scanner
    Scanner -->|file paths/metadata| Categorizer
    Categorizer -->|categorized items| Aggregator
    Aggregator -->|aggregated metrics| Reporter
    Reporter -->|formatted output| Console

    %% External System (Green)
    OS["OS Filesystem\n(POSIX, macOS APIs)"]:::external
    Scanner <-->|I/O calls| OS
    Categorizer <-->|metadata queries| OS

    %% Testing & CI (Orange)
    Tests["pytest / tests"]:::ci
    CI["GitHub Actions"]:::ci

    Tests -->|validates components| Parser
    CI -->|runs pipeline| Parser

    %% Documentation & Config (Purple)
    subgraph "Project Config & Docs"
        PyProj["pyproject.toml"]:::config
        PreCommit[".pre-commit-config.yaml"]:::config
        Version[".python-version"]:::config
        README["README.md"]:::config
        ARCH["ARCHITECTURE.md"]:::config
        Changelog["CHANGELOG.md"]:::config
    end

    CI -->|uses| PyProj
    CLI -->|builds with| PyProj
    CLI -->|lint via| PreCommit

    %% Click Events
    click CLI "https://github.com/azisk/zpace/blob/main/main.py"
    click Parser "https://github.com/azisk/zpace/blob/main/main.py"
    click Scanner "https://github.com/azisk/zpace/blob/main/main.py"
    click Categorizer "https://github.com/azisk/zpace/blob/main/main.py"
    click Aggregator "https://github.com/azisk/zpace/blob/main/main.py"
    click Reporter "https://github.com/azisk/zpace/blob/main/main.py"
    click PyProj "https://github.com/azisk/zpace/blob/main/pyproject.toml"
    click Tests "https://github.com/azisk/zpace/blob/main/test_.py"
    click CI "https://github.com/azisk/zpace/blob/main/.github/workflows/ci.yml"
    click CI "https://github.com/azisk/zpace/blob/main/.github/workflows/publish-pypi.yml"
    click PreCommit "https://github.com/azisk/zpace/blob/main/.pre-commit-config.yaml"
    click README "https://github.com/azisk/zpace/blob/main/README.md"
    click ARCH "https://github.com/azisk/zpace/blob/main/ARCHITECTURE.md"
    click Changelog "https://github.com/azisk/zpace/blob/main/CHANGELOG.md"
    click Version "https://github.com/azisk/zpace/blob/main/.python-version"

    %% Styles
    classDef core fill:#E0F7FA,stroke:#0288D1,stroke-width:2px
    classDef external fill:#E8F5E9,stroke:#43A047,stroke-width:2px,stroke-dasharray: 5 5
    classDef ci fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px,stroke-dasharray: 5 5
    classDef config fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px,stroke-dasharray: 5 5
```
