How 0xintuition/intuition-raycast works
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.