# cala-br/jsheets architecture

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

- Interactive diagram: https://gitdiagram.com/cala-br/jsheets
- Repository: https://github.com/cala-br/jsheets

## Overview

##### Project Type & Purpose
- This is a Java-based spreadsheet application built as an object-oriented project for an OOP exam. It implements spreadsheet functionalities (such as different cell types, expression evaluation, and event-based updates) and includes a rich UI built with various components.
- The purpose is to demonstrate an extensive use of OOP principles by organizing the code into packages that encapsulate UI, data models, expression evaluation, event handling, and various supporting services.

##### Breakdown of the File Structure
- Top-Level Directories:
▪ cells — manages different types of spreadsheet cells (TextCell, NumericCell, ExpressionCell, etc.).
▪ events — defines custom events (actions, cell updates, selections) used for handling user interactions and state changes.
▪ expressions — comprises the classes for parsing and evaluating spreadsheet expressions (tokenizer, expression tree, operator implementations, operands, and operations).
▪ frames — provides the main window (MainFrame) that hosts the UI components.
▪ model — includes the business/data logic models (RowHeaderModel, WorkSheetModel).
▪ services — contains service layers for operations such as file storage, session management, font management, and worksheet management, which abstract backend functionalities.
▪ util — maintains helper classes and utility methods that support the core logic.
- docs: Contains generated HTML documentation (and additional resources) for classes and packages, which can be referred to for details on component responsibilities.
- assets, Makefile, and configuration files are used for build and deployment.

a. Main Components:
- UI Layer:
- MainFrame (from frames), various dialogs (ErrorDialog, FileAlreadyExistsDialog, etc.), top bar/menu components, spreadsheet and worksheet UI components.
- Core Logic Layer:
- Cells: Different cell implementations (Text, Numeric, Expression, etc.)
- Models: WorkSheetModel and RowHeaderModel that represent the data.
- Expression Engine: Expression, ExpressionTokenizer, ExpressionTree, operations and operands.
- Event Handling:
- Custom event classes (e.g., ActionEvent, CellEditedEventArgs) that connect UI actions to model changes.
- Services Layer:
- ServiceRepository and individual services (Storage, Session, Font, WorksheetManager) provide backend functionality.
- Utilities:
- Helper classes and utility methods that support different parts of the application.

b. Relationships & Interactions:
- The UI components (in the components and frames packages) handle user interactions which fire events (in the events package).
- These events are propagated to service classes (in the services package) and model classes (in the model package) to update or retrieve data.
- The Expression Engine (in the expressions package) is used by cells when parsing and calculating cell content.
- There is a cyclic interaction: UI → Events → Model/Services → Update UI.

c. Architectural Patterns & Design Principles:
- Separation of Concerns: Clear division between presentation (UI), business logic (models, cells, expression engine), and backend services.
- Event-Driven Architecture: Use of event classes to decouple UI interactions from core logic updates.

d. Relevant Technologies & Frameworks:
- Java is the primary language.
- Likely use of Java Swing or a similar framework isn’t explicitly mentioned but is implied by the presence of UI components (dialogs, main frame, etc.).
- The Makefile implies a standardized build process.

##### Elements
- Components Labeled Clearly:
- Name each package/group (e.g., “UI Components”, “Spreadsheet Cells”, “Expression Evaluation”, “Event Handling”, “Service Layer”).
- How services are invoked by the UI or model to perform operations (like loading files or saving sessions).
- Visual Differentiation:
- A high-level view that shows major components and then break down each component (for example, showing details of the expression engine and its subcomponents).

##### Detailed Steps for the Principal Software Engineer
- UI Layer (MainFrame, dialogs, top bar, spreadsheet view)
- Business Logic (Cells, Models, Expression Engine, Event processing)
- Service Layer (File storage, session management, etc.)
- Utilities (Helper functions).
- For each layer:
- Main classes or packages and represent them as nodes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        UI1["MainFrame"]
        UI2["Dialogs"]
        UI3["Top Bar/Menu"]
        UI4["Spreadsheet Component"]
        UI5["Worksheet Component"]
    end

    %% Core Logic Layer
    subgraph "Core Logic"
        CL1["Spreadsheet Cells"]
        CL2["Data Models"]
        CL3["Expression Engine"]
    end

    %% Event Handling Layer
    subgraph "Event Handling"
        EH["Event Classes"]
    end

    %% Services Layer
    subgraph "Services Layer"
        S1["Service Repository"]
        S2["File Storage Service"]
        S3["Session Management"]
        S4["Font Management"]
        S5["Worksheet Management"]
    end

    %% Utilities Layer
    subgraph "Utilities"
        U1["Utility Classes"]
    end

    %% Inter-layer Relationships
    UI1 -->|"triggers"| EH
    UI2 -->|"triggers"| EH
    UI3 -->|"triggers"| EH

    UI4 -->|"updates"| CL2
    UI5 -->|"updates"| CL2

    EH -->|"updates"| CL2
    EH -->|"calls"| CL3

    CL1 -->|"evaluates"| CL3
    CL1 -->|"updates"| CL2

    CL2 -->|"uses"| S1
    CL2 -->|"calls"| S2
    CL2 -->|"calls"| S3
    CL2 -->|"calls"| S4
    CL2 -->|"calls"| S5

    UI1 -->|"refreshes"| CL2
    UI1 -->|"invokes"| S2
    UI1 -->|"invokes"| S3

    U1 ---|"supports"| UI1
    U1 ---|"supports"| CL1
    U1 ---|"supports"| CL2
    U1 ---|"supports"| EH
    U1 ---|"supports"| S1

    %% Styling definitions
    classDef ui fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef core fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef event fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef service fill:#E8DAEF,stroke:#6C3483,stroke-width:2px;
    classDef util fill:#FAD7A0,stroke:#D35400,stroke-width:2px;

    class UI1,UI2,UI3,UI4,UI5 ui;
    class CL1,CL2,CL3 core;
    class EH event;
    class S1,S2,S3,S4,S5 service;
    class U1 util;

    %% Click events for components
    click UI1 "https://github.com/cala-br/jsheets/blob/master/src/com/jsheets/frames/MainFrame.java"
    click UI2 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/components/dialogs"
    click UI3 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/components/top_bar"
    click UI4 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/components/spreadsheet"
    click UI5 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/components/worksheet"
    click CL1 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/cells"
    click CL2 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/model"
    click CL3 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/expressions"
    click EH "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/events"
    click S1 "https://github.com/cala-br/jsheets/blob/master/src/com/jsheets/services/ServiceRepository.java"
    click S2 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/services/storage"
    click S3 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/services/session"
    click S4 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/services/font"
    click S5 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/services/worksheet_manager"
    click U1 "https://github.com/cala-br/jsheets/tree/master/src/com/jsheets/util"
```
