# fatulm/shamsi_date architecture

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

- Interactive diagram: https://gitdiagram.com/fatulm/shamsi_date
- Repository: https://github.com/fatulm/shamsi_date

## Overview

##### Project Type & Purpose
- This is a pure Dart library (with Flutter support) focused on converting, formatting, and manipulating dates using both the Jalali (Persian/Solar) and Gregorian calendars.
- The README and file structure show that its main purpose is to provide date conversion utilities (for conversion between Jalali and Gregorian, as well as between Dart’s native DateTime objects), formatting tools, and safe date arithmetic along with validity checks using exceptions.

##### Analyzing the File Structure
- Top-level directories/files:
– .github (CI/workflow configuration), CHANGELOG, LICENSE, README, pubspec.yaml: these represent project meta-information and continuous integration setup.
– lib: Contains the actual source code of the package.
– test: Contains unit tests to verify correctness.
- Within lib:
– The main entry point file (shamsi_date.dart) likely exports the package API.
– The “src” folder divides functionality into sub-modules:
- date.dart: Likely defines the core Date abstraction.
- date_exception.dart: Handles errors (ensuring correct date creation, etc.).
- date_formatter.dart: Contains logic for formatting dates.
- extensions/: Contains additional functionality that extends DateTime for user convenience.
– Dedicated subfolders for “gregorian” and “jalali” modules:
- Each has its own calculation and formatter classes (for example, gregorian_calculation.dart, gregorian_date.dart, gregorian_formatter.dart for Gregorian, and similarly for Jalali).
- The presence of an “example” folder implies that usage examples are provided for developers.

##### Key Components
- Public API / Entry Point:
– shamsi_date.dart exposing classes such as Jalali and Gregorian.
- Core Abstraction:
– Date (from date.dart) which is possibly the parent class of both Jalali and Gregorian.
– DateException for handling invalid dates.
- Jalali Module:
– Components:
- Jalali (the main class for Persian dates)
- jalaali_calculation.dart (to share logic for date conversion and arithmetic)
- jalaali_formatter.dart (for formatting)
– Relationships:
- Inherits from Date.
- Exposes conversion functions (toGregorian and fromGregorian).
- Gregorian Module:
– Components:
- Gregorian (the main class for Gregorian dates)
- gregorian_calculation.dart (for computing date-related calculations)
- gregorian_formatter.dart (for formatting)
– Relationships:
- Also inherits from Date.
- Contains conversion methods (toJalali and fromJalali).
- Formatter Module:
– Centralized DateFormatter (from date_formatter.dart) accessible via a getter on date objects.
– Provides different formatting capabilities (month names, two-digit year, etc. along with specific getters for “Afghanistan” in jalali_formatter.dart).
- Extensions:
– Provided in lib/src/extensions folder to add methods on DateTime (for example, conversion from DateTime to Jalali/Gregorian).

##### Elements
- Clear labels for each component (e.g., "Jalali", "Gregorian", "DateFormatter", "Date", "DateException", "Extensions").
– From API calls to core, then branching into specific calendar modules.
– For example, use blue for core classes, green for Jalali-related modules, and orange for Gregorian-related modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Public API"
        API["Public API"]
    end

    subgraph "Core"
        C1["Date"]
        C2["DateException"]
        C3["DateFormatter"]
    end

    API -->|"uses"| C1
    API -->|"invokes"| C3
    C1 -->|"validates"| C2

    subgraph "Jalali Module"
        J1["Jalali"]
        J2["Jalali Calculation"]
        J3["Jalali Formatter"]
        J1 -->|"performs"| J2
        J1 -->|"formats"| J3
    end

    subgraph "Gregorian Module"
        G1["Gregorian"]
        G2["Gregorian Calculation"]
        G3["Gregorian Formatter"]
        G1 -->|"performs"| G2
        G1 -->|"formats"| G3
    end

    C1 -->|"base-for"| J1
    C1 -->|"base-for"| G1
    J1 <-->|"ConversionMethods"| G1

    subgraph "Extensions"
        E1["DateTime Extensions"]
    end

    DT["Dart DateTime"]
    DT -->|"extendedWith"| E1

    subgraph "CI & Testing"
        M1["CI & Meta Files"]
        T1["Tests"]
        M1 --> T1
    end

    click API "https://github.com/fatulm/shamsi_date/blob/master/lib/shamsi_date.dart"
    click C1 "https://github.com/fatulm/shamsi_date/blob/master/lib/src/date.dart"
    click C2 "https://github.com/fatulm/shamsi_date/blob/master/lib/src/date_exception.dart"
    click C3 "https://github.com/fatulm/shamsi_date/blob/master/lib/src/date_formatter.dart"
    click J1 "https://github.com/fatulm/shamsi_date/blob/master/lib/src/jalali/jalali_date.dart"
    click J2 "https://github.com/fatulm/shamsi_date/blob/master/lib/src/jalali/jalali_calculation.dart"
    click J3 "https://github.com/fatulm/shamsi_date/blob/master/lib/src/jalali/jalali_formatter.dart"
    click G1 "https://github.com/fatulm/shamsi_date/blob/master/lib/src/gregorian/gregorian_date.dart"
    click G2 "https://github.com/fatulm/shamsi_date/blob/master/lib/src/gregorian/gregorian_calculation.dart"
    click G3 "https://github.com/fatulm/shamsi_date/blob/master/lib/src/gregorian/gregorian_formatter.dart"
    click E1 "https://github.com/fatulm/shamsi_date/blob/master/lib/src/extensions/date_time_extensions.dart"

    classDef api fill:#80DEEA,stroke:#006064,stroke-width:2px,color:#000;
    classDef core fill:#90CAF9,stroke:#0D47A1,stroke-width:2px,color:#fff;
    classDef jalali fill:#A5D6A7,stroke:#1B5E20,stroke-width:2px,color:#000;
    classDef gregorian fill:#FFCC80,stroke:#E65100,stroke-width:2px,color:#000;
    classDef util fill:#CE93D8,stroke:#4A148C,stroke-width:2px,color:#fff;
    classDef meta fill:#F48FB1,stroke:#880E4F,stroke-width:2px,color:#fff;

    class API api;
    class C1,C2,C3 core;
    class J1,J2,J3 jalali;
    class G1,G2,G3 gregorian;
    class E1,DT util;
    class M1,T1 meta;
```
