# arsalanyavari/scal architecture

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

- Interactive diagram: https://gitdiagram.com/arsalanyavari/scal
- Repository: https://github.com/arsalanyavari/scal

## Overview

##### Project type and purpose
- This is a small suite of UNIX-style command-line utilities (“scal”, “sdate”, “sstat”) written in Rust.
- Purpose:
- scal: display Jalali (Shamsi) calendars
- sdate: convert between Jalali and Gregorian dates
- sstat: display file system stats with Jalali dates

##### File structure
- Top-level: Cargo.toml (Rust workspace), LICENSE, README, .github/ workflows for CI and binary/package releases, man/ pages.
- src/bin/: three binaries (scal.rs, sdate.rs, sstat.rs) each containing the CLI entry point.
- src/lib.rs: shared library with core logic (calendar calculations, date conversions, file-stat formatting).
- tests/: integration tests targeting library and bin behavior.

##### Insights from README
- Confirms the three CLI tools, their flags and subcommands.
- Mentions fixed leap-year bugs and added sstat.
- Packaging targets (deb, rpm, zip) via CI workflows.

##### Final advice
- Every layer: user input → CLI parsing → core logic → OS.
- Don’t forget documentation (man pages) and CI/CD as first-class elements.
- Aim for clarity: a reader should instantly see “three binaries share one library” and “OS & CI boundaries.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Binaries
    subgraph "CLI Binaries"
        scal["scal"]:::cli
        sdate["sdate"]:::cli
        sstat["sstat"]:::cli
    end

    %% Core Library
    subgraph "Core Library"
        calendar["calendar (module)"]:::lib
        conversion["conversion (module)"]:::lib
        file_stat["file_stat (module)"]:::lib
    end

    %% OS Interfaces
    OSTime["OS Time API"]:::os
    OSFS["OS FileSystem API"]:::os

    %% Documentation
    subgraph "Documentation"
        man_scal["scal.1.roff"]:::doc
        man_sdate["sdate.1.roff"]:::doc
        man_sstat["sstat.1.roff"]:::doc
        man_lib["slib.3.roff"]:::doc
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        test_wf["Test Workflow"]:::ci
        build["Build (cargo build)"]:::ci
        binary_release_wf["Binary Release Workflow"]:::ci
        linux_pkg_wf["Linux Package Release Workflow"]:::ci
    end

    %% Tests and Config
    Tests["Integration Tests"]:::test
    Cargo["Cargo.toml"]:::config

    %% Connections: CLI -> Core
    scal -->|"calls"| calendar
    scal -->|"calls"| conversion
    sdate -->|"calls"| conversion
    sstat -->|"calls"| file_stat
    sstat -->|"calls"| conversion

    %% Core -> OS
    calendar -->|"get current date"| OSTime
    conversion -->|"convert dates"| OSTime
    file_stat -->|"stat file"| OSFS
    file_stat -->|"format times"| OSTime

    %% CI/CD Flow
    test_wf -->|runs tests on| Tests
    test_wf -->|uses| Cargo
    test_wf -->|triggers| build
    build -->|produces binaries| binary_release_wf
    build -->|produces packages| linux_pkg_wf
    build -->|reads| Cargo
    build -->|includes man pages| man_scal
    build -->|includes man pages| man_sdate
    build -->|includes man pages| man_sstat
    build -->|includes man pages| man_lib

    %% Click Events
    click scal "https://github.com/arsalanyavari/scal/blob/main/src/bin/scal.rs"
    click sdate "https://github.com/arsalanyavari/scal/blob/main/src/bin/sdate.rs"
    click sstat "https://github.com/arsalanyavari/scal/blob/main/src/bin/sstat.rs"
    click calendar "https://github.com/arsalanyavari/scal/blob/main/src/lib.rs"
    click conversion "https://github.com/arsalanyavari/scal/blob/main/src/lib.rs"
    click file_stat "https://github.com/arsalanyavari/scal/blob/main/src/lib.rs"
    click man_scal "https://github.com/arsalanyavari/scal/blob/main/man/scal.1.roff"
    click man_sdate "https://github.com/arsalanyavari/scal/blob/main/man/sdate.1.roff"
    click man_sstat "https://github.com/arsalanyavari/scal/blob/main/man/sstat.1.roff"
    click man_lib "https://github.com/arsalanyavari/scal/blob/main/man/slib.3.roff"
    click test_wf "https://github.com/arsalanyavari/scal/blob/main/.github/workflows/test.yml"
    click binary_release_wf "https://github.com/arsalanyavari/scal/blob/main/.github/workflows/binary_release.yml"
    click linux_pkg_wf "https://github.com/arsalanyavari/scal/blob/main/.github/workflows/linux_package_release.yml"
    click Tests "https://github.com/arsalanyavari/scal/blob/main/tests/tests.rs"
    click Cargo "https://github.com/arsalanyavari/scal/blob/main/Cargo.toml"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef lib fill:#90EE90,stroke:#333,stroke-width:1px
    classDef os fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef doc fill:#E6E6FA,stroke:#333,stroke-width:1px,shape:parallelogram
    classDef ci fill:#FFA500,stroke:#333,stroke-width:1px
    classDef test fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef config fill:#FFC0CB,stroke:#333,stroke-width:1px
```
