# mandrillxx/cursor-ninja architecture

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

- Interactive diagram: https://gitdiagram.com/mandrillxx/cursor-ninja
- Repository: https://github.com/mandrillxx/cursor-ninja

## Overview

##### Project Type and Purpose
- This is a full‑stack, single‑page web application built with Next.js (App Router) and React + TypeScript.
- Purpose: Provide a visual, node‑based editor for creating, managing, and sharing coding‑standards rules.

##### File Structure
- Top‑level config files: package.json, pnpm‑lock.yaml, tsconfig.json, eslint.config.mjs, next.config.ts, postcss.config.mjs
- “src/app”: Next.js App Router directories (server components, layout, global CSS)
- “src/components”: UI building blocks (buttons, dialogs, node renderers, selectors)
- “src/actions”: server‑side or API actions (rule generation, AI integration)
- “src/hooks”: custom React hooks (use‑mobile)
- “src/lib”: shared utilities and state management (Zustand store, type definitions, safe action wrappers)

##### Key Insights from README
- Core features: visual graph editor, multiple rule node types, import/export (JSON, natural‑language).
- Uses AI to convert text into graph nodes.
- Next.js handles both server and client logic; React Query is mentioned in example but not directly visible—likely a placeholder.

##### Main System Components
a. Client (Browser)
- React UI (pages in src/app, components in src/components)
- State Management (Zustand store in src/lib/store.ts)
- Routing and Layout (Next.js App Router)
- Custom Hooks (e.g., use‑mobile)
b. Server (Next.js)
- Server Components & API Routes (src/actions/generate-rules.ts)
- File import/export endpoints (JSON, .cursorrule)
- AI Integration (calls to external AI service for NL→graph conversion)
c. Data Storage & Management
- In‑memory or client‑side store for active editing
- Export to JSON files / download
- Optionally persist to remote storage (not in code, but could be an extension)
d. External Services
- AI/LLM endpoint (e.g., OpenAI)
- Potential static hosting/CDN for public assets

##### Relationships and Interactions
- User interacts with React UI → triggers state changes in the store.
- UI dispatches server actions (via server components or API routes) to:
- Generate rules from NL text
- Import/export JSON
- Server action calls out to the AI service → returns structured rule data.
- Server returns data to client → client updates graph and renders nodes.
- User can download/export a .json file.

##### Architectural Patterns & Design Principles
- Component‑based UI architecture (atomic UI primitives + composed dialogs + node renderers)
- Unidirectional data flow: UI → store → server actions → store → UI
- Next.js App Router pattern: separation between server and client components
- Modular code organization: “actions” for side‑effects, “lib” for shared logic, “components” for pure UI.

##### Essential Elements
- Client layer: React pages, components tree, store
- Server layer: generate-rules action, import/export routes
- Data stores: in‑memory store, file system export
- External: AI/LLM service

##### Detail
- Don’t stop at “frontend” and “backend” only—identify sub‑systems (graph engine, dialog management, project management).

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client (Browser)"
        subgraph "Next.js App Router"
            AppRouter["Next.js App Router"]:::router
        end
        subgraph "UI Components"
            NodeTypeSelector["NodeTypeSelector"]:::ui
            ProjectSelector["ProjectSelector"]:::ui
            ImportRuleTextDialog["ImportRuleTextDialog"]:::ui
            RulePreview["RulePreview"]:::ui
            DialogManager["Rule Dialogs"]:::ui
            ThemeProvider["ThemeProvider"]:::ui
        end
        subgraph "Graph Editor"
            GraphCanvas["Graph Canvas"]:::ui
        end
        Store["Zustand Store"]:::state
        Utils["Utils & Types"]:::state
        MobileHook["use-mobile Hook"]:::hooks
        Download["File Download"]:::ui
    end

    subgraph "Server (Next.js)"
        Actions["generate-rules Action"]:::api
        ImportExport["Import/Export Routes"]:::api
    end

    subgraph "External Services"
        AIService["AI/LLM Service"]:::external
    end

    subgraph "Artifacts"
        StaticAssets["Public Static Assets"]:::static
        Configs["Config & Tooling"]:::config
    end

    %% Data flows
    NodeTypeSelector -->|select node type| GraphCanvas
    ProjectSelector -->|select project| Store
    ImportRuleTextDialog -->|"onImportNLText"| Actions
    Actions -->|"calls"| AIService
    AIService -->|"returns rule data"| Actions
    Actions -->|"rule data"| Store
    Store -->|"updates UI"| GraphCanvas
    Store -->|"provides data"| RulePreview
    GraphCanvas -->|"edit events"| Store
    ThemeProvider -->|applies theme| NodeTypeSelector
    MobileHook -->|detects mobile| GraphCanvas
    Store -->|"triggers export"| ImportExport
    ImportExport -->|"response (file)"| Download
    StaticAssets -->|serves icons/logos| NodeTypeSelector

    click AppRouter "https://github.com/mandrillxx/cursor-ninja/blob/main/src/app/layout.tsx"
    click AppRouter "https://github.com/mandrillxx/cursor-ninja/blob/main/src/app/page.tsx"
    click NodeTypeSelector "https://github.com/mandrillxx/cursor-ninja/blob/main/src/components/NodeTypeSelector.tsx"
    click ProjectSelector "https://github.com/mandrillxx/cursor-ninja/blob/main/src/components/ProjectSelector.tsx"
    click ImportRuleTextDialog "https://github.com/mandrillxx/cursor-ninja/blob/main/src/components/ImportRuleTextDialog.tsx"
    click RulePreview "https://github.com/mandrillxx/cursor-ninja/blob/main/src/components/RulePreview.tsx"
    click DialogManager "https://github.com/mandrillxx/cursor-ninja/tree/main/src/components/rule-dialogs/"
    click ThemeProvider "https://github.com/mandrillxx/cursor-ninja/blob/main/src/components/theme-provider.tsx"
    click Store "https://github.com/mandrillxx/cursor-ninja/blob/main/src/lib/store.ts"
    click Store "https://github.com/mandrillxx/cursor-ninja/blob/main/src/lib/project-store.ts"
    click Utils "https://github.com/mandrillxx/cursor-ninja/blob/main/src/lib/utils.ts"
    click Utils "https://github.com/mandrillxx/cursor-ninja/blob/main/src/lib/safe-action.ts"
    click Utils "https://github.com/mandrillxx/cursor-ninja/blob/main/src/lib/types.ts"
    click MobileHook "https://github.com/mandrillxx/cursor-ninja/blob/main/src/hooks/use-mobile.ts"
    click Actions "https://github.com/mandrillxx/cursor-ninja/blob/main/src/actions/generate-rules.ts"
    click StaticAssets "https://github.com/mandrillxx/cursor-ninja/tree/main/public/"
    click Configs "https://github.com/mandrillxx/cursor-ninja/blob/main/tsconfig.json"

    classDef ui fill:#D0E7FF,stroke:#0366d6,color:#0366d6
    classDef state fill:#DFFFE0,stroke:#28a745,color:#22863a
    classDef hooks fill:#FFF5B1,stroke:#DBAB09,color:#735C0F
    classDef api fill:#FFE4B5,stroke:#F66A0A,color:#D73A49
    classDef external fill:#FFDDE0,stroke:#CB2431,color:#86181D
    classDef static fill:#F0F0F0,stroke:#6A737D,color:#6A737D
    classDef config fill:#F6F8FA,stroke:#6A737D,color:#6A737D
    classDef router fill:#E6E6FA,stroke:#6F42C1,color:#6F42C1
```
