By 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:
- Create directory:
/src/modules/{moduleName}/ - Add subdirectories as needed:
components/,hooks/,types/ - Create container:
{Name}.cont.tsx- handles data fetching and logic - Create component:
{Name}.comp.tsx- pure presentation - 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 |