# hirasso/focal-point-picker architecture

> Architecture diagram of the GitHub repository hirasso/focal-point-picker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hirasso/focal-point-picker
- Repository: https://github.com/hirasso/focal-point-picker

## Overview

##### Project’s Nature and Purpose
- This is a WordPress plugin designed to enhance image handling by letting users define and retrieve focal points.
- Its main purpose is to integrate with WordPress (via functions such as wp_get_attachment_image) and inject custom CSS properties or inline styles based on computed focal points.
- The plugin is distributed via Composer and also supports a manual installation process into the wp-content/plugins folder.

##### File Structure to Understand Key Components
- Top-level Files:
- PHP plugin entry point: “focal-point-picker.php” (also a CSS and JavaScript file: “focal-point-picker.css”, “focal-point-picker.js”), which likely integrate the plugin’s rendering and frontend behavior.
- “src” directory: Contains core PHP classes (FocalPoint.php, FocalPointPicker.php) that implement the business logic for calculating the focal point positions.
- “bin” directory: Holds CLI support scripts (cli.js, support.js) which are most likely used for plugin testing, automation, or bundling tasks.
- Composer files (composer.json, composer.lock): Manage PHP dependencies and autoloading.
- Package-related files (package.json, pnpm-lock.yaml): Possibly used for managing JavaScript dependencies or running frontend builds.
- Configuration and CI/CD files (.github folders, husky, .editorconfig, etc.): Indicate that the project makes use of automated testing, linting, and deployment scripts.

##### Components
a. External Environment:
- The WordPress Core System: This is the host environment where the plugin is installed and activated. It calls WordPress functions like wp_get_attachment_image_src, wp plugin activation commands, and others.
b. Plugin Entry & Integration Layer:
- Plugin Main File (“focal-point-picker.php”): Acts as the integration point with WordPress. It registers plugin hooks and interfaces with WordPress functions.
- Composer autoloading support: Demonstrated through “composer.json” and “autoload.dist.php” which ensures the classes in “src” are loaded properly.
c. Business Logic/Core Components:
- “src” Directory: Contains classes (FocalPoint.php and FocalPointPicker.php) that encapsulate the main algorithm to determine the focal point coordinates (both fraction values and percentages).
d. User Interface and Frontend Integration:
- Frontend Assets: “focal-point-picker.css” for styling and “focal-point-picker.js” for any dynamic behavior.
- Template Usage: The README shows how the plugin adds classes and inline styles (like CSS custom properties) for enabling focal point behavior during image rendering.
e. Auxiliary/Support Tools:
- CLI Utilities (located in the “bin” directory): For debugging, support tasks, or perhaps build scripts.
- Development and CI/CD Automation: GitHub Actions workflows, Husky pre-commit hooks, and other configuration files that sustain code quality and deployment practices.

##### Architectural Patterns & Key Design Principles
- Separation of Concerns:
- Interface with WordPress handled in the main plugin file.
- Business logic contained in dedicated PHP classes.
- UI behavior and styling separated into CSS and JavaScript files.
- Extensibility:
- The plugin’s structure allows for future enhancements, managed via version control and deployment automation (e.g., changesets and GitHub actions).

## Diagram (Mermaid)

```mermaid
graph TD
    WP["WordPress Core"]:::external

    subgraph "Focal Point Picker Plugin"
        subgraph "Integration Layer"
            A1["focal-point-picker.php"]:::integration
        end

        subgraph "Core Business Logic"
            B1["FocalPoint.php"]:::core
            B2["FocalPointPicker.php"]:::core
        end

        subgraph "UI/Frontend Assets"
            C1["focal-point-picker.css"]:::ui
            C2["focal-point-picker.js"]:::ui
        end

        subgraph "CLI & DevOps Tools"
            D1["cli.js"]:::cli
            D2["support.js"]:::cli
            D3["composer.json"]:::composer
            D4["composer.lock"]:::composer
            D5["autoload.dist.php"]:::composer
            D6[".github"]:::devops
        end
    end

    WP -->|"calls"| A1
    A1 -->|"uses"| B1
    A1 -->|"uses"| B2
    A1 -->|"injects"| C1
    A1 -->|"injects"| C2
    A1 -->|"triggers"| D1
    A1 -->|"triggers"| D2
    D3 -->|"autoloads"| B1
    D3 -->|"autoloads"| B2
    A1 -->|"build/deploy"| D6

    classDef external fill:#D7BDE2,stroke:#000,stroke-width:1px;
    classDef integration fill:#AED6F1,stroke:#000,stroke-width:1px;
    classDef core fill:#A3E4D7,stroke:#000,stroke-width:1px;
    classDef ui fill:#F9E79F,stroke:#000,stroke-width:1px;
    classDef cli fill:#F5B7B1,stroke:#000,stroke-width:1px;
    classDef composer fill:#CCD1D1,stroke:#000,stroke-width:1px;
    classDef devops fill:#FAD7A0,stroke:#000,stroke-width:1px;

    click A1 "https://github.com/hirasso/focal-point-picker/blob/main/focal-point-picker.php"
    click B1 "https://github.com/hirasso/focal-point-picker/blob/main/src/FocalPoint.php"
    click B2 "https://github.com/hirasso/focal-point-picker/blob/main/src/FocalPointPicker.php"
    click C1 "https://github.com/hirasso/focal-point-picker/blob/main/focal-point-picker.css"
    click C2 "https://github.com/hirasso/focal-point-picker/blob/main/focal-point-picker.js"
    click D1 "https://github.com/hirasso/focal-point-picker/blob/main/bin/cli.js"
    click D2 "https://github.com/hirasso/focal-point-picker/blob/main/bin/support.js"
    click D3 "https://github.com/hirasso/focal-point-picker/blob/main/composer.json"
    click D4 "https://github.com/hirasso/focal-point-picker/blob/main/composer.lock"
    click D5 "https://github.com/hirasso/focal-point-picker/blob/main/autoload.dist.php"
    click D6 "https://github.com/hirasso/focal-point-picker/blob/main/.github"
```
