Ledgerify README

项目的 README,来自 github.com/AhmadHassan-BTed/Ledgerify。合并为一个 markdown 文件:README.md。

Ledgerify Logo

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.

TypeScript React Vite TailwindCSS License Build Status

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:

View Perspective Target Role Key Metrics & Visualizations Status
Executive CEO / Founders Month-over-Month trajectory, buyer retention rates, revenue pacing gauge, customer acquisition split. ✓
Finance CFO / Controller Gross ledger totals, net revenue, category yields (50ml, 100ml, Discovery, Trio), refund liabilities. ✓
Inventory Supply Chain / Ops Fragrance velocity meters, reorder urgency triage, composite set extraction, physical bottle share. ✓
Operations Warehouse / Fulfillment Day-of-week dispatch heatmap, shipping province hotspots, multi-box packing complexity ratios. ✓
Marketing Growth / Performance High-value customer tiers, geographic ad allocation, cart co-purchase affinity matrix, repeat cohorts. ✓
Creative Design & Studio Visual brief generators, hero product identification, packaging style trends, scent keyword demand. ✓
Admin Quality Data Engineers Automated health scores, missing field audits, test order isolation, quantity spike detection. ✓
Comparison Strategy & Finance Side-by-side multi-file benchmarking, variance delta calculations, dual-series curves. ✓

Technical Specifications

Schema & Field Normalization Specifications

Supported Input Columns (Fuzzy Matched)

The normalizer handles varied naming conventions across Shopify CSV and Excel exports:

  • Order Identifier: Name, Order ID, Order Number, #, Invoice ID
  • Timestamp: Created at, Order Date, Date, Processed at, Sale Date
  • Customer Email: Email, Customer Email, Contact Email
  • Financial Status: Financial Status, Payment Status, Status
  • Total Amount: Total, Total Amount, Gross Sales, Net Sales, Subtotal
  • Item Summary: Lineitem name, Item Name, Items, Products, Description
  • Quantity: Lineitem quantity, Total Quantity, Quantity, Qty
  • Shipping Destination: Shipping City, City, Shipping Province, State, Region
Local Storage & Security Architecture

Client-Side Isolation

  • Storage Layer: IndexedDB database (LedgerifyDB) operating within origin sandboxing.
  • Data Retention: Workbooks persist locally in the operator's browser session or local storage cache.
  • Zero Third-Party Tracking: No analytics scripts, remote beacons, or external telemetries are bundled.

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

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.

Ledgerify (AhmadHassan-BTed/Ledgerify)

正在搜索数据库…

这是什么?Ledgerify 是一个基于浏览器的数据分析平台,可以解析 Shopify 的 Excel 账本导出文件,并将其转换为结构化仪表板,覆盖八个不同的业务职能(管理层、财务、库存、运营、营销、创意、数据质量和对比分析),且无需任何后端服务器。
这是托管服务,还是需要我自己运行的程序?它是一个纯客户端的 React 网页应用,没有后端:你在浏览器中打开它,上传 Excel 工作簿,所有数据都会在本地解析,并存储在 IndexedDB 中。
怎么把它跑起来?克隆仓库,用 npm 安装依赖,然后运行本地开发服务器;项目内置了一份示例账本,因此无需上传自己的文件即可立即体验。
运行之前需要先安装什么?Node.js 20.0 或更高版本,以及 npm 9.0 或更高版本。
它能处理杂乱或不一致的 Shopify 导出文件吗?它就是专门为此设计的:模糊匹配的标准化流程可以统一不同店铺之间不同的列名、货币格式以及组合型订单行项目,而管理员质量仪表板会标记缺失字段、测试订单和数量异常激增的情况。
这套仪表板是为谁设计的?开箱即用,覆盖八类组织角色:CEO/创始人、CFO/财务总监、供应链/运营、仓储/履约、增长/效果营销、设计与工作室、数据工程师,以及战略/财务。
我的 Shopify 销售数据会被上传到别处吗?不会。工作簿完全在浏览器中处理,并缓存在本地 IndexedDB 数据库中;项目中不包含任何分析脚本、追踪信标或外部调用。
我能把两份不同的账本导出文件并排对比吗?可以,对比仪表板支持多文件并排基准对比,包含差异计算和双序列曲线。
我可以上传哪些文件格式?它设计用于处理 Shopify 的 Excel 导出文件(多工作表工作簿)和 CSV 文件,并通过浏览器原生的 SheetJS 在客户端完成解析。
代码库的内部结构是怎样组织的?它严格遵循关注点分离原则:领域计算逻辑位于 core/services/ 中,并通过轻量级的 IoC/依赖注入容器注入到 UI 组件,而不是与展示代码混在一起。
大小
0.8 MB
星标
4.8K
更新
提交Oct 13
时长
4个月
提交 · 90 天