# fazziclay/opentoday architecture

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

- Interactive diagram: https://gitdiagram.com/fazziclay/opentoday
- Repository: https://github.com/fazziclay/opentoday

## Overview

##### Project Type and Purpose
- The project is an Android application written primarily in Java (with several Kotlin parts) that centers around “Items” – individual notes, checkboxes, groups, and various item types. The application supports import/export, data saving/fixing, customizable UI (fragments, activities, toolbars), and a plugin API.
- Existence of an “api” module that provides interfaces for plugins and event handling, and an “app” module which holds the UI logic and business logic for the end-user experience.

##### Main Components
a. API Module:
– Contains the core definitions and interfaces for plugins and event management (e.g., OpenTodayPlugin, EventHandler, PluginManager).
– Represents the backend logic layer that supports extensibility and event-based interactions.
b. App Module (Android Application):
– UI Layer: Includes Activities (MainActivity, SetupActivity, etc.), Fragments (ItemsEditorFragment, AboutFragment, SettingsFragment, etc.), dialogs, and the custom Toolbar.
– Items Management: A rich “items” subsystem with an Items Registry, item types (TextItem, CheckboxItem, GroupItem, etc.), Controllers, and ItemsStorage implementations. This is the central model/component driven by the “Items tree (pedigree)” described in the README.
– Data Handling & Persistence: Components responsible for saving/loading (item_data.json, item_data.gz), data fixer (DataFixer) to update older versions, import/export support, and settings management (settings.json, SettingsManager).
c. External Libraries & Utilities:
– External libraries (JavaNeoUtil, NeoSocket, OpenTodayTelemetry, etc.) included in the “app/libs” folder.
– Utility packages (e.g., util for network, logging, file handling, time conversions) that support both logic and UI.
d. Build, Configuration, and Deployment:
– Gradle build scripts (build.gradle, settings.gradle) for both modules.
– Resource directories for layouts, drawables, and value files which configure UI appearance and behavior.

##### Relationships and Data Flow
- UI Events (from Activities and Fragments) → invoke Controllers in the Items management module.
- Controllers → interact with the Data Persistence component (saving, loading, and data fixing).
- The API Module’s plugin interfaces and event-handling system → interact with both the backend logic and help to inject additional functionality (for example, telemetry events or GCP/ISLP plugins).
- The Import/Export mechanism connects the data persistence layer with external user actions (sharing content through the clipboard or file system).
- Distinguish between responsibility layers:
- Presentation Layer (Android UI: Activities, Fragments, GUI helpers)
- Business Logic Layer (Items management, event callbacks, selection mechanisms)
- Data Layer (Persistence files, settings.json, data fixer modules)

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly divide the codebase into API/backend logic, UI/frontend logic, and data management.
- Modular Architecture: The split between “api” and “app” modules demonstrates a separation between plugin/core logic and the Android-specific implementation.
- Event-driven Interactions: Multiple event or callback files (e.g., EventHandler, Callback interfaces) suggest the use of observer patterns to manage UI updates and item state changes.
- MVC/MVVM-like Principles: With a clear UI layer (activities, fragments) that interacts with backend controllers and model (items) handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Module
    subgraph "API Module (Plugin & Event Handling)"
        a1["OpenTodayPlugin"]:::api
        a2["EventHandler"]:::api
        a3["PluginManager"]:::api
    end

    %% UI Layer (Android Application)
    subgraph "UI Layer (Android Application)"
        u1["MainActivity"]:::ui
        u2["Other Activities"]:::ui
        u3["Fragments (About,ItemEditor,etc.)"]:::ui
        u4["Toolbar & Dialogs"]:::ui
        u5["Layout Resources"]:::ui
    end

    %% Items Management
    subgraph "Items Management"
        im1["ItemsRegistry & ItemsRoot"]:::im
        im2["Item Types (Text,Checkbox,Group)"]:::im
        im3["Controllers & ItemsStorage"]:::im
        im4["Selection Management"]:::im
    end

    %% Data Handling & Persistence
    subgraph "Data Handling & Persistence"
        d1["Data Files (item_data.json,item_data.gz)"]:::data
        d2["DataFixer & Import/Export"]:::data
    end

    %% External Libraries & Utilities
    subgraph "External Libraries & Utilities"
        ex1["External Libraries"]:::ext
        ex2["Utility Packages (Logger,NetworkUtil,TimeUtil)"]:::ext
    end

    %% Build, Configuration & Resources
    subgraph "Build, Config & Resources"
        b1["Build Scripts"]:::build
        b2["Resource Directories (layouts,drawables,values)"]:::build
    end

    %% Connections
    u1 -->|"triggers"| im3
    u3 -->|"invokes"| im3
    u4 -->|"interacts"| im3
    im3 -->|"persists"| d2
    im4 -->|"manages"| im1
    a3 -->|"managesPlugins"| im3
    a2 -->|"dispatchesEvents"| u1
    a1 -->|"integrates"| im3
    d2 -->|"updates"| d1
    ex2 -.->|"supports"| u1
    ex2 -.->|"supports"| im3
    b2 -->|"supplies"| u5
    b1 -->|"builds"| a1

    %% Click Events for API Module
    click a1 "https://github.com/fazziclay/opentoday/tree/main/api/src/main/java/com/fazziclay/opentoday/api"
    click a2 "https://github.com/fazziclay/opentoday/tree/main/api/src/main/java/com/fazziclay/opentoday/api"
    click a3 "https://github.com/fazziclay/opentoday/tree/main/api/src/main/java/com/fazziclay/opentoday/api"

    %% Click Events for UI Layer
    click u1 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/java/com/fazziclay/opentoday/gui/activity"
    click u2 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/java/com/fazziclay/opentoday/gui/activity"
    click u3 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/java/com/fazziclay/opentoday/gui/fragment"
    click u4 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/java/com/fazziclay/opentoday/gui/toolbar"
    click u5 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/res/layout"

    %% Click Events for Items Management
    click im1 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/java/com/fazziclay/opentoday/app/items"
    click im2 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/java/com/fazziclay/opentoday/app/items/item"
    click im3 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/java/com/fazziclay/opentoday/app/items"
    click im4 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/java/com/fazziclay/opentoday/app/items/selection"

    %% Click Events for Data Handling & Persistence
    click d1 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/assets"
    click d2 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/java/com/fazziclay/opentoday/app/datafixer"

    %% Click Events for External Libraries & Utilities
    click ex1 "https://github.com/fazziclay/opentoday/tree/main/app/libs"
    click ex2 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/java/com/fazziclay/opentoday/util"

    %% Click Events for Build, Config & Resources
    click b1 "https://github.com/fazziclay/opentoday/blob/main/build.gradle"
    click b2 "https://github.com/fazziclay/opentoday/tree/main/app/src/main/res"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:1px,color:#000;
    classDef ui fill:#90EE90,stroke:#000,stroke-width:1px,color:#000;
    classDef im fill:#FFA07A,stroke:#000,stroke-width:1px,color:#000;
    classDef data fill:#F4A460,stroke:#000,stroke-width:1px,color:#000;
    classDef ext fill:#D3D3D3,stroke:#000,stroke-width:1px,color:#000;
    classDef build fill:#FFE4B5,stroke:#000,stroke-width:1px,color:#000;
```
