docs/folder-pattern.md

Folder & Naming Pattern Guide

This document defines the folder structure and naming conventions used in this codebase.

File Naming Convention

All files use kebab-case (lowercase with hyphens):

✅ add-feature-dialog.tsx
✅ use-board-actions.ts
✅ board-view.tsx

❌ AddFeatureDialog.tsx
❌ useBoardActions.ts
❌ BoardView.tsx

Export Naming Convention

While files use kebab-case, exports use PascalCase for components and camelCase for hooks/functions:

// File: add-feature-dialog.tsx
export function AddFeatureDialog() { ... }

// File: use-board-actions.ts
export function useBoardActions() { ... }

View Folder Structure

Each complex view should have its own folder with the following structure:

components/views/
├── [view-name].tsx              # Entry point (exports the main view)
└── [view-name]/                 # Subfolder for complex views
    ├── components/              # View-specific reusable components
    │   ├── index.ts             # Barrel export
    │   └── [component].tsx      # Individual components
    ├── dialogs/                 # View-specific dialogs and modals
    │   ├── index.ts             # Barrel export
    │   └── [dialog-name].tsx    # Individual dialogs/modals
    ├── hooks/                   # View-specific hooks
    │   ├── index.ts             # Barrel export
    │   └── use-[name].ts        # Individual hooks
    ├── shared/                  # Shared utilities between components
    │   ├── index.ts             # Barrel export
    │   └── [name].ts            # Shared code
    ├── constants.ts             # View constants
    ├── types.ts                 # View-specific types (optional)
    ├── utils.ts                 # View utilities (optional)
    └── [main-component].tsx     # Main view components (e.g., kanban-board.tsx)

Example: board-view

components/views/
├── board-view.tsx                           # Entry point
└── board-view/
    ├── components/
    │   ├── index.ts
    │   ├── kanban-card.tsx
    │   └── kanban-column.tsx
    ├── dialogs/
    │   ├── index.ts
    │   ├── add-feature-dialog.tsx
    │   ├── edit-feature-dialog.tsx
    │   ├── follow-up-dialog.tsx
    │   ├── delete-all-verified-dialog.tsx
    │   ├── delete-completed-feature-dialog.tsx
    │   ├── completed-features-modal.tsx
    │   ├── agent-output-modal.tsx
    │   └── feature-suggestions-dialog.tsx
    ├── hooks/
    │   ├── index.ts
    │   ├── use-board-actions.ts
    │   ├── use-board-features.ts
    │   └── use-board-drag-drop.ts
    ├── shared/
    │   ├── index.ts
    │   ├── model-constants.ts
    │   └── model-selector.tsx
    ├── constants.ts
    └── kanban-board.tsx

Global vs View-Specific Code

Global (src/hooks/, src/lib/, etc.)

Code that is used across multiple views:

• src/hooks/use-auto-mode.ts - Used by board-view, agent-view, etc.
• src/hooks/use-keyboard-shortcuts.ts - Used across the app
• src/lib/utils.ts - Global utilities

View-Specific ([view-name]/hooks/, [view-name]/components/)

Code that is only used within a single view:

• board-view/hooks/use-board-actions.ts - Only used by board-view
• board-view/components/kanban-card.tsx - Only used by board-view

Barrel Exports

Use index.ts files to create clean import paths:

// board-view/hooks/index.ts
export { useBoardActions } from './use-board-actions';
export { useBoardFeatures } from './use-board-features';

// Usage in board-view.tsx
import { useBoardActions, useBoardFeatures } from './board-view/hooks';

When to Create a Subfolder

Create a subfolder for a view when:

1. The view file exceeds ~500 lines
2. The view has 3+ related components
3. The view has 2+ custom hooks
4. Multiple dialogs/modals are specific to the view

Dialogs Folder

The dialogs/ folder contains all dialog and modal components specific to a view:

What goes in dialogs/:

• Confirmation dialogs (e.g., delete-all-verified-dialog.tsx)
• Form dialogs (e.g., add-feature-dialog.tsx, edit-feature-dialog.tsx)
• Modal overlays (e.g., agent-output-modal.tsx, completed-features-modal.tsx)
• Any component that renders as an overlay/popup

Naming convention:

• Use -dialog.tsx suffix for confirmation/form dialogs
• Use -modal.tsx suffix for content-heavy modals

Barrel export pattern:

// dialogs/index.ts
export { AddFeatureDialog } from './add-feature-dialog';
export { EditFeatureDialog } from './edit-feature-dialog';
export { AgentOutputModal } from './agent-output-modal';
// ... etc

// Usage in view entry point
import { AddFeatureDialog, EditFeatureDialog, AgentOutputModal } from './board-view/dialogs';

Quick Reference

Location	File Naming	Export Naming
Components	kebab-case.tsx	PascalCase
Dialogs	*-dialog.tsx or *-modal.tsx	PascalCase
Hooks	use-kebab-case.ts	camelCase
Utils/Lib	kebab-case.ts	camelCase
Types	kebab-case.ts	PascalCase
Constants	constants.ts	SCREAMING_SNAKE_CASE