# 0xintuition/intuition-raycast architecture

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

- Interactive diagram: https://gitdiagram.com/0xintuition/intuition-raycast
- Repository: https://github.com/0xintuition/intuition-raycast

## Overview

##### Project Type and Purpose
- This is a **Raycast menu-bar extension** built with **TypeScript** and **React**.
- It provides several menu-bar commands (“Intuition Menu”, search atoms, lists, triples) that call the Intuition knowledge graph’s API and render results in Raycast UI components.

##### File Structure
- Top-level:
- configuration files (.eslintrc.json, tsconfig.json, package.json, pnpm-lock.yaml)
- README, CHANGELOG, assets folder
- **src/**: where all extension source lives
- Under src/:
- root TSX files for distinct commands (atom-detail.tsx, search-atoms.tsx, intuition-menu.tsx, etc.)
- **features/**: reusable hooks or HOCs (with-query.tsx)
- **lib/**:
– consts (general.ts)
– queries (GraphQL query definitions: atoms.ts, lists.ts, triples.ts)
– utils (format.ts)

##### README for Insights
- Core function: let users search Intuition knowledge graph from Raycast’s menu bar.
- Prereqs: Node.js, pnpm, Raycast.
- No internal database; all data comes from an external API (“Intuition knowledge graph”).
- Development: run `pnpm dev` to start the extension.

##### Main Components & Their Relationships
a. **Raycast Host Application**
- The container in which all extension commands run.
b. **Extension Commands (UI Components)**
- Each TSX file under src/ represents a separate command or view.
- Example: `search-atoms.tsx` shows a list; `atom-detail.tsx` shows detail.
c. **Query Layer**
- GraphQL queries defined in `src/lib/queries/*.ts`.
- Invoked by `with-query.tsx` higher-order component or hooks.
d. **Utilities & Constants**
- Formatting helpers in `src/lib/utils/format.ts`.
- General constants (e.g., API endpoint URL) in `src/lib/consts/general.ts`.
e. **External Service**
- Intuition knowledge graph API (hosted remotely).

Data Flow:
User → Raycast UI → Invocation of a TSX Command Component → Query Hook/Wrapping HOC → GraphQL HTTP request → Intuition API → JSON Response → Formatting util → Component render → Raycast UI

##### Architectural Patterns & Design Principles
- **Modular UI Components**: One file per command/view in Raycast.
- **Separation of Concerns**:
- Presentation (`.tsx` command components)
- Data fetching (queries + `with-query`)
- Utilities (formatting)
- Constants (API endpoints, options)
- **HOC/Hook Pattern** (`with-query.tsx`) to encapsulate data-fetching logic.
- **GraphQL Query Modules** for each entity type (atoms, lists, triples).

- Clear labels for each component and directory group (src/commands, src/lib/queries, etc.).
- Notes on key technologies: Raycast SDK (TypeScript + React), GraphQL, pnpm.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Raycast Host
    subgraph "Raycast Host Application"
        direction TB
        RaycastHost["Raycast Host"]:::external
    end

    %% Extension Module
    subgraph "Extension Module (src/)"
        direction TB

        %% Commands
        subgraph "Commands (UI Components)" 
            direction TB
            IntuitionMenu["Intuition Menu"]:::ui
            SearchAtoms["Search Atoms"]:::ui
            AtomDetail["Atom Detail"]:::ui
            SearchLists["Search Lists"]:::ui
            SearchTriples["Search Triples"]:::ui
            SearchWithinList["Search Within List"]:::ui
        end

        %% Data Layer
        subgraph "Data Layer"
            direction TB
            WithQuery["with-query HOC/Hook"]:::logic

            subgraph "GraphQL Queries"
                direction TB
                AtomsQuery["atoms.ts"]:::logic
                ListsQuery["lists.ts"]:::logic
                TriplesQuery["triples.ts"]:::logic
            end
        end

        %% Utils & Consts
        subgraph "Utils & Consts"
            direction TB
            GeneralConsts["general.ts"]:::logic
            FormatUtils["format.ts"]:::logic
        end
    end

    %% External Service
    ExternalAPI["Intuition Knowledge Graph API"]:::external

    %% Connections
    RaycastHost -->|invokes| IntuitionMenu
    RaycastHost -->|invokes| SearchAtoms
    RaycastHost -->|invokes| AtomDetail
    RaycastHost -->|invokes| SearchLists
    RaycastHost -->|invokes| SearchTriples
    RaycastHost -->|invokes| SearchWithinList

    IntuitionMenu -->|uses| WithQuery
    SearchAtoms -->|uses| WithQuery
    AtomDetail -->|uses| WithQuery
    SearchLists -->|uses| WithQuery
    SearchTriples -->|uses| WithQuery
    SearchWithinList -->|uses| WithQuery

    WithQuery -->|executes| AtomsQuery
    WithQuery -->|executes| ListsQuery
    WithQuery -->|executes| TriplesQuery

    AtomsQuery -->|requests| ExternalAPI
    ListsQuery -->|requests| ExternalAPI
    TriplesQuery -->|requests| ExternalAPI

    ExternalAPI -->|responds| AtomsQuery
    ExternalAPI -->|responds| ListsQuery
    ExternalAPI -->|responds| TriplesQuery

    AtomsQuery -->|returns JSON| WithQuery
    ListsQuery -->|returns JSON| WithQuery
    TriplesQuery -->|returns JSON| WithQuery

    WithQuery -->|provides data| IntuitionMenu
    WithQuery -->|provides data| SearchAtoms
    WithQuery -->|provides data| AtomDetail
    WithQuery -->|provides data| SearchLists
    WithQuery -->|provides data| SearchTriples
    WithQuery -->|provides data| SearchWithinList

    IntuitionMenu -->|renders result| RaycastHost
    SearchAtoms -->|renders result| RaycastHost
    AtomDetail -->|renders result| RaycastHost
    SearchLists -->|renders result| RaycastHost
    SearchTriples -->|renders result| RaycastHost
    SearchWithinList -->|renders result| RaycastHost

    %% Click Events
    click IntuitionMenu "https://github.com/0xintuition/intuition-raycast/blob/main/src/intuition-menu.tsx"
    click SearchAtoms "https://github.com/0xintuition/intuition-raycast/blob/main/src/search-atoms.tsx"
    click AtomDetail "https://github.com/0xintuition/intuition-raycast/blob/main/src/atom-detail.tsx"
    click SearchLists "https://github.com/0xintuition/intuition-raycast/blob/main/src/search-lists.tsx"
    click SearchTriples "https://github.com/0xintuition/intuition-raycast/blob/main/src/search-triples.tsx"
    click SearchWithinList "https://github.com/0xintuition/intuition-raycast/blob/main/src/search-within-list.tsx"
    click WithQuery "https://github.com/0xintuition/intuition-raycast/blob/main/src/features/with-query.tsx"
    click AtomsQuery "https://github.com/0xintuition/intuition-raycast/blob/main/src/lib/queries/atoms.ts"
    click ListsQuery "https://github.com/0xintuition/intuition-raycast/blob/main/src/lib/queries/lists.ts"
    click TriplesQuery "https://github.com/0xintuition/intuition-raycast/blob/main/src/lib/queries/triples.ts"
    click GeneralConsts "https://github.com/0xintuition/intuition-raycast/blob/main/src/lib/consts/general.ts"
    click FormatUtils "https://github.com/0xintuition/intuition-raycast/blob/main/src/lib/utils/format.ts"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#0366d6,color:#0366d6
    classDef logic fill:#d4edda,stroke:#28a745,color:#28a745
    classDef external fill:#fff3cd,stroke:#ff8800,color:#ff8800
```
