# 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.
[](https://www.typescriptlang.org/)
[](https://react.js.org/)
[](https://vitejs.dev/)
[](https://tailwindcss.com/)
[](LICENSE)
[](https://github.com/AhmadHassan-BTed/.github/actions)
[Live Demonstration](https://ahmadhassan-bted.github.io/.github/) • [System Architecture](./ARCHITECTURE.md) • [Contributing](#contributing-and-standards)
---
## 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](./ARCHITECTURE.md).
```mermaid
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.
```mermaid
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:
```mermaid
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.
```mermaid
classDiagram
class IFileParser {
<