Ledgerify

Client-Side Shopify Ledger Intelligence & Multi-Department Analytics

A resilient, browser-native analytics platform engineered for complex Shopify Excel exports. Built with an Obsidian dark interface, zero-backend architecture, dynamic schema normalization, and multi-departmental intelligence.

Live Demonstration • System Architecture • Contributing

Overview

Modern e-commerce ledgers generated by Shopify exports often contain irregular schemas, composite product bundles, inconsistent date serials, and fragmented departmental requirements. Ledgerify was created to solve this problem entirely on the client side.

By combining browser-native SheetJS parsing, resilient schema normalization, and an Inversion-of-Control (IoC) dependency injection container, Ledgerify transforms raw, multi-megabyte Excel spreadsheets into structured domain intelligence across eight specialized organizational roles without sending data to an external server.

The platform provides human-centric visibility: leaders and operators receive clear, synthesized conclusions rather than being overwhelmed by raw tabular data.

Architectural Principles

Ledgerify is built upon three core engineering pillars:

1. Separation of Concerns (SoC): Strict isolation between parsing, storage, domain metric calculation, and UI presentation.
2. Dependency Injection (DI): Business logic resides in decoupled domain services injected through a lightweight IoC container.
3. Zero-Knowledge Privacy: 100% client-side computation. Workbooks are parsed in-memory, cached in browser IndexedDB, and never transmitted over the network.

Architecture Overview

For the comprehensive technical specification, class diagrams, normalization rules, and state management flow, see ARCHITECTURE.md.

flowchart TD
    subgraph ClientLayer["Client Layer (Browser Runtime)"]
        A["User Upload (.xlsx / .csv)"] --> B["IFileParser (SheetJS Engine)"]
        B --> C["Resilient Normalizer & Header Mapper"]
        C --> D["Domain Entities (NormalizedOrder[])"]
        D --> E["IStorageService (IndexedDB Cache)"]
    end

    subgraph ServiceLayer["Domain & Service Layer (IoC Container)"]
        E --> F["Dependency Injection Container"]
        F --> G1["ExecutiveService"]
        F --> G2["FinanceService"]
        F --> G3["InventoryService"]
        F --> G4["OperationsService"]
        F --> G5["MarketingService"]
        F --> G6["CreativeService"]
        F --> G7["AdminDataQualityService"]
        F --> G8["CompareService"]
    end

    subgraph PresentationLayer["Presentation Layer (Obsidian UI)"]
        G1 & G2 & G3 & G4 & G5 & G6 & G7 & G8 --> H["React Context Providers"]
        H --> I["Departmental View Controllers"]
        I --> J["Interactive Visualizations & Drill-Downs"]
    end

Data Flow & Normalization Pipeline

Raw Shopify exports exhibit variations across stores, countries, and export configurations. The normalization pipeline dynamically detects headers, reconciles currency formats, and structures composite line items.

flowchart LR
    A["Raw Workbook Buffer"] --> B["Workbook Sheet Discovery"]
    B --> C["Header Fuzzy Normalization"]
    C --> D["Value Sanitization & Type Coercion"]
    D --> E["Compound Bundle Splitting"]
    E --> F["Flag & Anomaly Tagging"]
    F --> G["NormalizedOrder Schema"]

    subgraph NormalizationLogic["Transformation Rules"]
        C -.- C1["Case & whitespace agnostic regex matching"]
        D -.- D1["Excel serial date to ISO UTC conversion"]
        E -.- E1["Extracts individual bottles from Discovery/Trio sets"]
        F -.- F1["Identifies $0 test orders, missing emails, spike quantities"]
    end

Request & Parsing Lifecycle

When an operator uploads a workbook or toggles between datasets, the execution flow follows a deterministic, non-blocking lifecycle:

sequenceDiagram
    autonumber
    actor User as Operator
    participant UI as Dashboard UI
    participant Parser as File Parser (SheetJS)
    participant Normalizer as Schema Normalizer
    participant Storage as IndexedDB Storage
    participant DI as IoC Container
    participant Services as Domain Services

    User->>UI: Selects .xlsx / .csv file
    UI->>Parser: Passes ArrayBuffer
    Parser->>Normalizer: Streams raw sheet records
    Normalizer->>Normalizer: Resolves dynamic column mappings
    Normalizer->>Normalizer: Extracts category yields & anomalies
    Normalizer-->>Storage: Persists NormalizedDataset
    Normalizer-->>DI: Injects Active Dataset State
    DI->>Services: Trigger reactive metric calculation
    Services-->>UI: Dispatches aggregated view models
    UI-->>User: Renders Obsidian dashboards with 0ms server latency

Module Relationship & Dependency Injection

The application decouples interface components from domain calculation algorithms through the Service Context and IoC Container.

classDiagram
    class IFileParser {
        <<interface>>
        +parse(file: File): Promise~NormalizedOrder[]~
    }

    class IStorageService {
        <<interface>>
        +saveDataset(dataset: Dataset): Promise~void~
        +getDatasets(): Promise~Dataset[]~
        +deleteDataset(id: string): Promise~void~
    }

    class ServiceContainer {
        +financeService: FinanceService
        +executiveService: ExecutiveService
        +inventoryService: InventoryService
        +operationsService: OperationsService
        +marketingService: MarketingService
        +creativeService: CreativeService
        +adminService: AdminDataQualityService
        +compareService: CompareService
    }

    class DataProvider {
        +activeDataset: Dataset
        +filteredOrders: NormalizedOrder[]
        +setFilter(filter: FilterState): void
    }

    ServiceContainer --> FinanceService
    ServiceContainer --> ExecutiveService
    ServiceContainer --> InventoryService
    ServiceContainer --> OperationsService
    ServiceContainer --> MarketingService
    DataProvider ..> ServiceContainer : Consumes via Context
    IFileParser <|.. XlsxParser
    IStorageService <|.. IndexedDbStorage

Build & Deployment Pipeline

Ledgerify utilizes automated continuous integration via GitHub Actions, compiling TypeScript bundles and deploying static assets to GitHub Pages.

flowchart TD
    subgraph GitRepository["Git Repository"]
        A["Push to main branch"] --> B["GitHub Actions Triggered"]
    end

    subgraph CIWorkflow["CI / CD Pipeline"]
        B --> C["Setup Node.js Runtime"]
        C --> D["npm ci (Deterministic Dependency Tree)"]
        D --> E["tsc --noEmit (Type Integrity Validation)"]
        E --> F["vite build (Production Minification)"]
        F --> G["Upload Artifact (dist/)"]
    end

    subgraph HostingInfrastructure["Edge Hosting"]
        G --> H["Deploy to GitHub Pages Environment"]
        H --> I["Public Release (HTTPS / Global CDN)"]
    end

Departmental Perspectives

Ledgerify structures analytical output into eight dedicated dashboards, each aligned with specific business functions:

Technical Specifications

Repository Structure

Ledgerify/
├── .github/
│   └── workflows/
│       └── deploy.yml              # GitHub Actions Pages deployment pipeline
├── scripts/
│   ├── inspect.js                  # CLI utility for workbook inspection
│   └── inspect_sheets.js           # Multi-sheet diagnostic analyzer
├── src/
│   ├── components/
│   │   ├── charts/                 # Recharts components (Area, Bar, Donut, Multi-Series)
│   │   ├── layout/                 # Top navigation, dataset switcher, theme controls
│   │   ├── ui/                     # Atomic UI cards, heatmaps, gauges, tables
│   │   └── views/                  # 8 departmental dashboard implementations
│   ├── context/
│   │   ├── DataContext.tsx         # Dataset state and upload orchestrator
│   │   ├── FilterContext.tsx       # Date, search, and category filter provider
│   │   ├── ServiceContext.tsx      # Dependency injection context provider
│   │   └── ThemeContext.tsx        # Obsidian dark / light mode manager
│   ├── core/
│   │   ├── di/
│   │   │   └── container.ts        # IoC Service Container
│   │   ├── parser/
│   │   │   ├── IFileParser.ts      # Parser contract
│   │   │   ├── normalizer.ts       # Resilient header & entity normalizer
│   │   │   └── xlsxParser.ts       # SheetJS workbook parser
│   │   ├── services/               # Pure departmental calculation services
│   │   └── storage/                # IndexedDB persistence adapter
│   ├── styles/
│   │   └── themes/                 # CSS theme definitions and role accents
│   ├── types/                      # Domain interfaces and analytics models
│   ├── App.tsx                     # Root application container
│   ├── index.css                   # Obsidian design tokens and base styles
│   └── main.tsx                    # Application entry point
├── package.json                    # Project manifests and scripts
├── tsconfig.json                   # TypeScript compiler configuration
└── vite.config.ts                  # Vite build bundler configuration

Development Workflow

Prerequisites

• Node.js 20.0 or higher
• npm 9.0 or higher

Local Setup

# Clone the repository
git clone https://github.com/AhmadHassan-BTed/.github.git Ledgerify
cd Ledgerify

# Install dependencies deterministically
npm ci

# Start the local development server
npm run dev

The application will be accessible at http://localhost:5173. A sample ledger is pre-bundled for instant local evaluation.

Verification & Production Build

# Execute TypeScript type validation and Vite production bundling
npm run build

# Preview production build locally
npm run preview

Contributing and Standards

Contributions adhering to strict engineering standards are welcomed. When submitting changes:

1. Maintain complete Separation of Concerns: calculation logic belongs in core/services/, not inside presentation components.
2. Ensure strict TypeScript type safety without the use of any overrides where domain models exist.
3. Validate that parsing resilience handles corrupted inputs, $0 test orders, and missing columns without runtime exceptions.
4. Verify that npm run build passes with zero errors before opening pull requests.

Author & Attribution

Engineered and designed by Ahmad Hassan (B-Ted).

License

This project is open-source software licensed under the MIT License.