# moustafa-nasr/fahmatrix architecture

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

- Interactive diagram: https://gitdiagram.com/moustafa-nasr/fahmatrix
- Repository: https://github.com/moustafa-nasr/fahmatrix

## Overview

##### Project type and purpose
- Fahmatrix is a standalone Java library (an open-source tool) for in-memory, tabular data manipulation. It provides a DataFrame API, CSV/XLSX importers, and helper utilities for data selection and preview.

##### File structure
- Top‐level modules:
- build & config: `build.gradle.kts`, `pom.xml`, Gradle wrapper
- Examples: `examples/` (usage demos)
- Source: `src/main/java/com/fahmatrix/`
– Core: `DataFrame.java`, `Series.java`
– Importers: `Importers/CsvImporter.java`, `Importers/SimpleXlsxImporter.java`
– Helpers: `Helpers/DataSelector.java`
- No web front end or backend services—everything runs in‐process.
- No external dependencies (right now).

##### README for additional insights
- Core features: CSV reading, pretty printing, head/tail, aggregation stubs.
- Future plans: filtering, grouping, pivot, export.
- Intended as a drop-in library to Java applications.

##### Diagramming the architecture
a. Main components
- Client Application (user’s code that calls Fahmatrix)
- Core Module: DataFrame, Series
- Importers Module: CsvImporter, SimpleXlsxImporter
- Helpers Module: DataSelector (column/row subsetting)
- Data Sources: File system (CSV, XLSX)
- Output: Console Printer (DataFrame.print())
b. Relationships & interactions
1. Client invokes `DataFrame.readCSV(path)`
2. `CsvImporter` reads raw file → produces a table of rows/columns
3. Raw data passed to `DataFrame` constructor
4. Client calls methods on DataFrame (e.g., head(), tail(), series operations)
5. Internally, DataFrame uses `Series` for per-column computations and `DataSelector` to implement filtering/slicing
6. `DataFrame.print()` formats and writes to console
c. Architectural patterns & principles
- Modular separation: Importers, Core, Helpers
- Single responsibility: each class focuses on one aspect (parsing vs. data representation vs. selection)
- In-process library: no network or external service dependencies
d. Key technologies & libraries
- Java 11+
- Gradle / Maven build
- Apache POI in future (for XLSX parsing) if dependencies are added

##### Detailed step-by-step for the principal software engineer
– Importers (CsvImporter, SimpleXlsxImporter) on the left
– Core (DataFrame, Series) in the center
– Helpers (DataSelector) on the right
4. Importers → Core to show data ingestion
5. Core → Helpers for selection/filtering
6. Core → Console for output of print()
10. Every component is named with its Java package path for clarity

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    ClientApp["Client Application"]:::external

    %% Fahmatrix Library Container
    subgraph "Fahmatrix Library"
        direction TB

        subgraph "Importers"
            direction TB
            CsvImporter["com.fahmatrix.Importers.CsvImporter"]:::importer
            SimpleXlsxImporter["com.fahmatrix.Importers.SimpleXlsxImporter"]:::importer
        end

        subgraph "Core"
            direction TB
            DataFrame["com.fahmatrix.DataFrame"]:::core
            Series["com.fahmatrix.Series"]:::core
        end

        subgraph "Helpers"
            direction TB
            DataSelector["com.fahmatrix.Helpers.DataSelector"]:::helper
        end
    end

    %% External Systems
    FileSystem["File System (CSV/XLSX)"]:::external
    Console["Console I/O"]:::external
    BuildConfig["Build & Config"]:::external

    %% Connections
    ClientApp -->|"invoke readCSV()"| DataFrame
    FileSystem -->|"provide files"| CsvImporter
    FileSystem -->|"provide files"| SimpleXlsxImporter
    DataFrame -->|"use CsvImporter/SimpleXlsxImporter"| CsvImporter
    DataFrame -->|"use CsvImporter/SimpleXlsxImporter"| SimpleXlsxImporter
    CsvImporter -->|"parse data"| DataFrame
    SimpleXlsxImporter -->|"parse data"| DataFrame
    DataFrame -->|"use Series for column ops"| Series
    DataFrame -->|"use DataSelector for slicing"| DataSelector
    DataFrame -->|"format & print()"| Console
    BuildConfig -.-> DataFrame

    %% Click Events
    click ClientApp "https://github.com/moustafa-nasr/fahmatrix/tree/main/examples/"
    click DataFrame "https://github.com/moustafa-nasr/fahmatrix/blob/main/src/main/java/com/fahmatrix/DataFrame.java"
    click Series "https://github.com/moustafa-nasr/fahmatrix/blob/main/src/main/java/com/fahmatrix/Series.java"
    click CsvImporter "https://github.com/moustafa-nasr/fahmatrix/blob/main/src/main/java/com/fahmatrix/Importers/CsvImporter.java"
    click SimpleXlsxImporter "https://github.com/moustafa-nasr/fahmatrix/blob/main/src/main/java/com/fahmatrix/Importers/SimpleXlsxImporter.java"
    click DataSelector "https://github.com/moustafa-nasr/fahmatrix/blob/main/src/main/java/com/fahmatrix/Helpers/DataSelector.java"
    click FileSystem "https://github.com/moustafa-nasr/fahmatrix/tree/main/examples/exampleFiles/"
    click BuildConfig "https://github.com/moustafa-nasr/fahmatrix/blob/main/build.gradle.kts"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef importer fill:#90EE90,stroke:#000,stroke-width:1px
    classDef helper fill:#FFD580,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
