# skaplanofficial/raycast-pins architecture

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

- Interactive diagram: https://gitdiagram.com/skaplanofficial/raycast-pins
- Repository: https://github.com/skaplanofficial/raycast-pins

## Overview

##### Main Components

a) Frontend Layer:
- React Components (from /src/components)
- Menu item components hierarchy
- Quick pins subsystem

b) Core Logic Layer:
- Library Components (from /src/lib)
- Groups Management
- Pins Management
- Local Data Handling
- Placeholders System
- Storage System

c) Integration Layer:
- Raycast API Integration
- File System Integration
- Menu Bar Integration

##### Component Relationships

- User Interface → Core Logic (show data flow)
- Core Logic → Storage (show persistence)
- Placeholders → Pins (show dynamic content injection)
- Menu Bar Extra ↔ Pin/Group Management

##### Specific Implementation Details

Create sections showing:
- The placeholder system architecture (extensive based on /src/lib/placeholders)
- Quick pins subsystem (from /components/menu-items/quick-pins)
- Data flow for pin/group management

##### Key Architectural Patterns to Highlight
- Component-based UI architecture
- Plugin system for placeholders
- Data persistence layer
- Event-driven menu bar integration

**┌─────────────────────────────────────────┐**
- User Interface             │
- (Forms, Lists, Menus, Quick Actions)   │
- ┤
- Core Logic                 │
- (Pins, Groups, Placeholders, Utils)   │
- ┤
- Integration Layer             │
- (Raycast API, FileSystem, MenuBar)   │
- ┤
- Data Layer                 │
- (LocalStorage, Import/Export)      │
- ┘

Important Elements to Include:

##### Placeholder system's extensibility
- How custom placeholders can be added
- Placeholder resolution flow

##### Quick pins feature
- Different types (App, Directory, Document, etc.)
- Their interaction with the core system

##### Data flow for key operations
- Pin creation/editing
- Management
- Menu bar updates

##### External Integration Points
- Raycast Extension API
- File System Access
- Menu Bar Integration
- Browser Integration (for tab pinning)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef ui fill:#3498db,stroke:#2980b9,color:white
    classDef core fill:#2ecc71,stroke:#27ae60,color:white
    classDef integration fill:#f1c40f,stroke:#f39c12,color:black
    classDef storage fill:#9b59b6,stroke:#8e44ad,color:white
    classDef external fill:#e67e22,stroke:#d35400,color:white

    %% Frontend Layer
    subgraph Frontend
        UI[User Interface]
        Forms[Forms]
        MenuItems[Menu Items]
        QuickPins[Quick Pins System]
        
        UI --> Forms
        UI --> MenuItems
        UI --> QuickPins
        
        %% Forms Components
        Forms --> GroupForm[Group Form]
        Forms --> PinForm[Pin Form]
        Forms --> PinListItem[Pin List Item]
        
        %% Quick Pins Components
        QuickPins --> AppQuickPin[App Quick Pin]
        QuickPins --> DirectoryQuickPin[Directory Quick Pin]
        QuickPins --> DocumentQuickPin[Document Quick Pin]
    end

    %% Core Logic Layer
    subgraph CoreLogic
        Groups[Groups Management]
        Pins[Pins Management]
        LocalData[Local Data Handler]
        Storage[Storage System]
        
        Placeholders[Placeholder System]
        CustomPlaceholders[Custom Placeholders]
        
        Placeholders --> CustomPlaceholders
        Groups --> Storage
        Pins --> Storage
        LocalData --> Storage
    end

    %% Integration Layer
    subgraph Integration
        RaycastAPI[Raycast API]
        FileSystem[File System]
        MenuBar[Menu Bar]
        ActionHandlers[Action Handlers]
    end

    %% Data Layer
    subgraph DataManagement
        LocalStorage[(Local Storage)]
        ImportExport[Import/Export]
        ScheduledExec[Scheduled Execution]
    end

    %% Connections between layers
    Frontend --> CoreLogic
    CoreLogic --> Integration
    Integration --> DataManagement
    
    %% External Systems
    RaycastExt[Raycast Extension API]:::external
    FSAccess[File System Access]:::external
    Browser[Browser Integration]:::external

    Integration --> RaycastExt
    Integration --> FSAccess
    Integration --> Browser

    %% Click Events
    click GroupForm "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/components/GroupForm.tsx"
    click PinForm "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/components/PinForm.tsx"
    click PinListItem "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/components/PinListItem.tsx"
    click AppQuickPin "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/components/menu-items/quick-pins/AppQuickPin.tsx"
    click DirectoryQuickPin "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/components/menu-items/quick-pins/DirectoryQuickPin.tsx"
    click DocumentQuickPin "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/components/menu-items/quick-pins/DocumentQuickPin.tsx"
    click Groups "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/lib/Groups.ts"
    click Pins "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/lib/Pins.ts"
    click LocalData "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/lib/LocalData.ts"
    click Storage "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/lib/storage.ts"
    click Placeholders "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/lib/placeholders/index.ts"
    click CustomPlaceholders "https://github.com/SKaplanOfficial/Raycast-Pins/tree/main/src/lib/placeholders/custom-placeholders"
    click MenuBar "https://github.com/SKaplanOfficial/Raycast-Pins/tree/main/src/components/menu-items"
    click ActionHandlers "https://github.com/SKaplanOfficial/Raycast-Pins/tree/main/src/components/actions"
    click ImportExport "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/import-data.tsx"
    click LocalStorage "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/lib/LocalData.ts"
    click ScheduledExec "https://github.com/SKaplanOfficial/Raycast-Pins/blob/main/src/lib/scheduled-execution.ts"

    %% Legend
    subgraph Legend
        UI_L[UI Components]:::ui
        Core_L[Core Logic]:::core
        Int_L[Integration]:::integration
        Store_L[Storage]:::storage
        Ext_L[External Systems]:::external
    end
```
