Skip to content

AGENTS.md

Latest commit

 

History

History
55 lines (38 loc) · 3.85 KB

AGENTS.md

File metadata and controls

55 lines (38 loc) · 3.85 KB

Agent Instructions

Project

Graphy is an IDE that visualizes code as a graph — functions, modules, and other constructs are represented as blocks connected by edges instead of being shown as plain text files. It is built as a desktop application using TanStack Start for the web layer and Electron as the desktop shell.

Component Files

Always split components into distinct files — one component per file. Do not co-locate multiple React components inside a single route or module file.

File Tree Architecture

The codebase uses a feature-based layout. Top-level folders under src/:

Folder Purpose
src/app/ App shell: providers, global layout (sidebar, top-bar), styles.css. The chrome around the modules.
src/modules/ Self-contained feature modules (e.g. graph/, ai/). Each owns its components, hooks, state, services, and types.
src/shared/ Cross-cutting primitives: ui/ (shadcn), hooks/, lib/. No app- or feature-specific code.
src/routes/ TanStack file-based routes. Must stay at src/routes. Route files should be thin and compose module/app components.

Rules

  • Import direction is one-way: routes → app → modules → shared. Never import upward (e.g. shared must not import from modules).
  • Modules don't import from each other directly. If two modules need to share something, lift it into shared/ or expose it via the source module's index.ts barrel.
  • A module's index.ts is its public API. Internal files stay internal — outsiders import @/modules/graph, not @/modules/graph/components/code-node.
  • src/shared/ui/ is reserved for shadcn primitives. The shadcn CLI is configured to write there; do not put hand-written feature components in it.
  • New features become new modules. Create src/modules/<feature>/ rather than adding to app/ or shared/.

Icons

This project uses Lucide Icons for all icons in the app.

Do not install or use other icon libraries.

Package Commands

This project uses Bun as the package manager and runtime.

Command Description
bun run dev Build the parser bundle (watch), start Vite, launch Electron.
bun run dev:electron Start Electron pointing at the running web dev server.
bun run dev:parser Watch and rebundle the parser CLI into dist-electron/parser.cjs.
bun run build Build the parser bundle and the web app.
bun run build:parser One-shot bundle of the parser CLI into dist-electron/parser.cjs.
bun run start:desktop Build the app and launch Electron.
bun run lint Run ESLint.
bun run format Format with Prettier and auto-fix ESLint issues.
bun run check Check formatting with Prettier.
bun run tidy Run format then lint — one-shot cleanup.

Never run dev commands (dev, dev:electron, start:desktop) to launch the web server or the Electron app. The user runs these themselves.

Always run bun run tidy after any change to keep formatting and linting consistent before handing work back to the user.