architecture

name	architecture
description	Project structure and module organization. Use when creating new modules, adding new features, understanding where files should be placed, or exploring the codebase structure.
user-invocable	false

Project Architecture

Project Structure

/src
├── modules/              # Feature-based modules (domain-driven design)
│   ├── systems/         # System management features
│   ├── orders/          # Order management features
│   ├── catalogue/       # Catalogue features
│   ├── orderItem/       # Order item features
│   ├── systemItem/      # System item features
│   └── shared/          # Shared cross-domain features
│       ├── form/wizardV3/    # Multi-step form wizard
│       ├── system/           # System-related shared features
│       └── catalogue/        # Catalogue-related shared features
├── components/          # Reusable UI components
│   ├── ui/             # shadcn/ui components
│   ├── form/           # Form components
│   ├── overlays/       # Modal and slideover components
│   └── table/          # Table components
├── hooks/              # Custom React hooks
│   ├── fetch/          # Data fetching hooks
│   ├── form/           # Form-related hooks
│   ├── graphql/        # GraphQL query/mutation hooks
│   └── filter/         # Filter state hooks
├── store/              # Global Zustand stores
├── lib/                # Library utilities and helpers
│   ├── utils.ts        # General utilities (cn(), etc.)
│   └── predicates/     # Predicate functions
├── utils/              # General utility functions
├── types/              # Global type definitions
│   ├── constants/      # Global constants
│   └── gql/            # GraphQL generated types
└── server/             # Server-side code (Next.js API routes)
    ├── apollo/         # Apollo GraphQL server
    └── files/          # File handling (MinIO S3)

Module Organization Pattern

Each feature module follows this structure:

/modules/{moduleName}/
├── components/           # React components
│   ├── {feature}/       # Feature subdirectories
│   ├── filters/         # Filter components
│   └── table/           # Table components
├── hooks/               # Custom hooks (queries, mutations)
├── types/               # Module-specific types
├── utils/               # Module-specific utilities
├── store/               # Module-specific Zustand stores (if needed)
├── {Name}.cont.tsx      # Container component (logic + data)
└── {Name}.comp.tsx      # Pure component (presentation)

Where to Place New Code

Type	Location	Example
New feature module	/src/modules/{moduleName}/	/src/modules/inventory/
Shared component	/src/components/	/src/components/form/DatePicker.tsx
shadcn/ui component	/src/components/ui/	/src/components/ui/calendar.tsx
Global hook	/src/hooks/{category}/	/src/hooks/fetch/useDebounce.ts
Module-specific hook	/src/modules/{module}/hooks/	/src/modules/orders/hooks/useOrderMutation.ts
Global store	/src/store/	/src/store/useUserStore.ts
Module-specific store	/src/modules/{module}/store/	/src/modules/orders/store/useOrderFilterStore.ts
Global types	/src/types/	/src/types/common.ts
Module-specific types	/src/modules/{module}/types/	/src/modules/orders/types/order.ts
Predicate functions	/src/lib/predicates/	/src/lib/predicates/domain.ts
Utility functions	/src/utils/	/src/utils/formatters.ts
GraphQL generated types	/src/types/gql/	Auto-generated by codegen
Constants	/src/types/constants/	/src/types/constants/tableIds.ts

Creating a New Module

When creating a new feature module:

1. Create directory: /src/modules/{moduleName}/
2. Add subdirectories as needed: components/, hooks/, types/
3. Create container: {Name}.cont.tsx - handles data fetching and logic
4. Create component: {Name}.comp.tsx - pure presentation
5. Add page in /src/pages/ that imports the container

File Naming Conventions

Type	Pattern	Example
Container	{Name}.cont.tsx	OrderList.cont.tsx
Pure component	{Name}.comp.tsx	OrderList.comp.tsx
Hook	use{Name}.ts	useOrderMutation.ts
Store	use{Name}Store.ts	useOrderFilterStore.ts
Types	{name}.ts or {name}.types.ts	order.ts
Constants	{name}.ts (UPPER_CASE exports)	tableIds.ts