popiart-node-canvas/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2026-01-09

Directory Layout

node-banana/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── layout.tsx          # Root layout, metadata
│   │   ├── page.tsx            # Main workflow page
│   │   ├── globals.css         # Tailwind base styles
│   │   └── api/                # API routes
│   │       ├── generate/       # Image generation
│   │       ├── llm/            # Text generation
│   │       ├── workflow/       # Save/load workflows
│   │       └── ...             # Other routes
│   ├── components/             # React components
│   │   ├── nodes/              # Node type implementations
│   │   ├── edges/              # Edge type implementations
│   │   ├── modals/             # Modal dialogs
│   │   ├── quickstart/         # Onboarding UI
│   │   └── *.tsx               # Top-level components
│   ├── store/                  # Zustand state
│   │   ├── workflowStore.ts    # Central workflow state
│   │   └── annotationStore.ts  # Drawing state
│   ├── types/                  # TypeScript definitions
│   │   ├── index.ts            # Main types
│   │   └── quickstart.ts       # Quickstart types
│   ├── utils/                  # Utilities
│   │   ├── costCalculator.ts   # Pricing calculation
│   │   ├── gridSplitter.ts     # Grid detection
│   │   ├── imageStorage.ts     # Image persistence
│   │   └── logger*.ts          # Logging
│   └── lib/                    # Feature libraries
│       └── quickstart/         # Quickstart logic + tests
├── public/                     # Static assets
├── examples/                   # Community workflows
├── .planning/                  # Project planning docs
├── package.json                # Dependencies
├── tsconfig.json               # TypeScript config
└── next.config.ts              # Next.js config

Directory Purposes

src/app/

• Purpose: Next.js App Router pages and API routes
• Contains: Page components, API handlers
• Key files: page.tsx (main entry), layout.tsx (root layout)
• Subdirectories: api/ for server routes

src/components/

• Purpose: React UI components
• Contains: All visual components
• Key files: WorkflowCanvas.tsx, Header.tsx, FloatingActionBar.tsx
• Subdirectories: nodes/, edges/, modals/, quickstart/

src/components/nodes/

• Purpose: Node type implementations (7 types)
• Contains: BaseNode.tsx (wrapper), *Node.tsx (specific types)
• Key files: NanoBananaNode.tsx, PromptNode.tsx, ImageInputNode.tsx

src/store/

• Purpose: Zustand state management
• Contains: Store definitions and actions
• Key files: workflowStore.ts (2000+ lines, central state)

src/types/

• Purpose: TypeScript type definitions
• Contains: All interfaces and type unions
• Key files: index.ts (main types), quickstart.ts

src/utils/

• Purpose: Business logic utilities
• Contains: Standalone helper functions
• Key files: costCalculator.ts, gridSplitter.ts, imageStorage.ts

src/lib/quickstart/

• Purpose: Quickstart/onboarding feature
• Contains: Templates, prompts, validation
• Subdirectories: __tests__/ for test files

Key File Locations

Entry Points:

• src/app/page.tsx - Main application entry
• src/app/layout.tsx - Root layout and providers

Configuration:

• tsconfig.json - TypeScript config (path alias: @/*)
• next.config.ts - Next.js with Turbopack
• vitest.config.ts - Test configuration
• .env.local - Environment variables (gitignored)

Core Logic:

• src/store/workflowStore.ts - All workflow state and execution
• src/components/WorkflowCanvas.tsx - Canvas orchestration
• src/types/index.ts - Type definitions

API Routes:

• src/app/api/generate/route.ts - Image generation
• src/app/api/llm/route.ts - Text generation
• src/app/api/workflow/route.ts - File operations

Testing:

• src/lib/quickstart/__tests__/*.test.ts - Unit tests

Documentation:

• README.md - User-facing documentation
• CLAUDE.md - AI assistant instructions

Naming Conventions

Files:

• PascalCase.tsx - React components (WorkflowCanvas.tsx)
• camelCase.ts - Utilities and stores (costCalculator.ts)
• kebab-case directories - API routes (save-generation/)
• *.test.ts - Test files (colocated in __tests__/)

Directories:

• camelCase - Feature directories (quickstart/)
• Plural for collections (nodes/, edges/, modals/)

Special Patterns:

• route.ts - Next.js API route handler
• index.ts - Barrel exports
• __tests__/ - Test directory

Where to Add New Code

New Node Type:

• Implementation: src/components/nodes/{Name}Node.tsx
• Types: Add to src/types/index.ts (NodeType union, data interface)
• Registration: src/components/WorkflowCanvas.tsx (nodeTypes)
• Store logic: src/store/workflowStore.ts (createDefaultNodeData, executeWorkflow)

New API Route:

• Handler: src/app/api/{route-name}/route.ts
• Export: GET, POST, etc. functions

New Utility:

• Implementation: src/utils/{name}.ts
• Tests: src/utils/__tests__/{name}.test.ts

New Component:

• Implementation: src/components/{Name}.tsx
• Or in feature directory: src/components/{feature}/{Name}.tsx

Special Directories

examples/

• Purpose: Community workflow examples
• Source: JSON workflow files
• Committed: Yes

.planning/

• Purpose: Project planning documentation
• Source: GSD planning system
• Committed: Yes

.next/

• Purpose: Next.js build output
• Source: Generated during build
• Committed: No (gitignored)

---

Structure analysis: 2026-01-09 Update when directory structure changes