Project File Organization Structure
Directory Structure
1. Components ( /src/components )
Feature-specific components should be organized in their own directories:
/src/components
/referrals
/components
[Link]
[Link]
[Link]
/hooks
[Link]
[Link]
/utils
[Link]
[Link]
Rules:
Each feature gets its own folder under /components
Use plural naming for feature folders (e.g., referrals , packages ,
promotions )
Subfolders: /components , /hooks , /utils
Component files use PascalCase with .tsx extension
Hook files use camelCase starting with use and .ts extension
Utility files use camelCase with .ts extension
2. Generic Hooks ( /src/hooks )
Global hooks that are used across multiple features:
/src/hooks
[Link]
[Link]
[Link]
[Link]
Rules:
Only for hooks used by multiple features
Use camelCase starting with use
Use .ts extension ( .tsx only if hook returns JSX)
Do NOT add feature-specific hooks here (those go in
/components/{feature}/hooks )
3. Models ( /src/models )
TypeScript type definitions and interfaces:
/src/models
[Link]
[Link]
[Link]
[Link]
Rules:
One model file per domain/feature
Use singular naming with .[Link] extension
Contains TypeScript types, interfaces, and enums
Should include validation schemas if needed
Export types using PascalCase naming
4. Services ( /src/services )
4.1 Service Files (Root Level)
Business logic and API integration:
/src/services
[Link]
[Link]
[Link]
[Link]
Rules:
One service file per domain/feature
Use singular naming with .[Link] extension
Contains API calls and business logic functions
Export functions using camelCase (e.g., fetchReferrals , createReferral )
4.2 Tanstack Query Hooks ( /src/services/hooks )
React Query hooks for data fetching:
/src/services/hooks
[Link]
[Link]
[Link]
[Link]
Rules:
Use plural naming for query hooks: use{Feature}[Link]
Use singular naming for mutation hooks: use{Action}{Feature}[Link]
All hooks should use Tanstack Query (React Query)
Import corresponding service functions
4.3 API Response Schemas ( /src/services/schemas )
Zod schemas for API response validation:
/src/services/schemas
[Link]
[Link]
[Link]
Rules:
Use plural naming with .[Link] extension
Contains Zod schemas for API response validation
Export schemas using PascalCase (e.g., ReferralSchema , ReferralsFilterSchema )
Should validate both request and response data
Example: Referral Feature Implementation
File Structure
/src
/components
/referrals
/components
[Link]
[Link]
[Link]
/hooks
[Link]
[Link]
/utils
[Link]
[Link]
/models
[Link]
/services
[Link]
/hooks
[Link]
[Link]
/schemas
[Link]
Implementation Details
/src/models/[Link]
export type Referral = {
id: string;
customerName: string;
email: string;
status: ReferralStatus;
createdAt: Date;
};
export type ReferralFilter = {
status?: ReferralStatus;
dateRange?: DateRange;
pageSize?: number;
pageNumber?: number;
};
export enum ReferralStatus {
PENDING = 'pending',
APPROVED = 'approved',
REJECTED = 'rejected'
}
/src/services/[Link]
import type { ReferralFilter } from '@/models/[Link]';
import type { Referral } from './schemas/[Link]';
import { api } from './[Link]';
export async function fetchReferrals(filters: ReferralFilter) {
// Business logic and API calls
}
export async function createReferral(data: CreateReferralData) {
// Create referral logic
}
/src/services/hooks/[Link]
import type { ReferralFilter } from '@/models/[Link]';
import { useQuery } from '@tanstack/react-query';
import { fetchReferrals } from '../[Link]';
export function useReferralsQuery(filters: ReferralFilter) {
return useQuery({
queryKey: ['referrals', filters],
queryFn: () => fetchReferrals(filters),
});
}
/src/services/schemas/[Link]
import { z } from 'zod';
export const ReferralSchema = [Link]({
id: [Link](),
customerName: [Link](),
email: [Link]().email(),
status: [Link](['pending', 'approved', 'rejected']),
createdAt: [Link](),
});
export const ReferralsFilterSchema = [Link]({
status: [Link](['pending', 'approved', 'rejected']).optional(),
pageSize: [Link]().optional(),
pageNumber: [Link]().optional(),
});
export type Referral = [Link]<typeof ReferralSchema>;
export type ReferralsFilter = [Link]<typeof ReferralsFilterSchema>;
Naming Conventions
Files and Directories
Components: PascalCase (e.g., [Link] )
Hooks: camelCase starting with use (e.g., [Link] )
Utilities: camelCase (e.g., [Link] )
Models: singular + .[Link] (e.g., [Link] )
Services: singular + .[Link] (e.g., [Link] )
Schemas: plural + .[Link] (e.g., [Link] )
Query Hooks: use{Feature}[Link] (e.g., [Link] )
Mutation Hooks: use{Action}{Feature}[Link] (e.g.,
[Link] )
Code Exports
Types/Interfaces: PascalCase (e.g., Referral , ReferralFilter )
Functions: camelCase (e.g., fetchReferrals , createReferral )
Constants: UPPER_SNAKE_CASE (e.g., DEFAULT_PAGE_SIZE )
Enums: PascalCase (e.g., ReferralStatus )