teatea-pension/.trellis/spec/frontend/directory-structure.md

Directory Structure

This document describes the module organization and folder conventions for the frontend application.

Overview

app/                          # Next.js App Router
├── (marketing)/              # Public marketing pages (i18n)
│   └── [locale]/             # Locale-based routing
└── (app)/                    # Protected application routes
    └── app/                  # Main application routes
modules/                      # Feature modules
├── [feature]/                # Feature module
│   ├── components/           # UI components
│   ├── hooks/                # Custom hooks
│   ├── context/              # React Context
│   ├── lib/                  # Utilities and data transforms
│   └── types/                # Frontend view model types
├── shared/                   # Shared components across features
└── ui/                       # UI component library
middleware.ts                 # Authentication & routing middleware

Module Structure

Feature Module Pattern

Each feature module should follow this structure:

modules/dashboard/
├── components/
│   ├── DashboardHeader.tsx
│   ├── StatsCard.tsx
│   ├── ActivityFeed.tsx
│   └── index.ts              # Barrel export
├── hooks/
│   ├── useDashboardStats.ts
│   ├── useActivityFeed.ts
│   └── index.ts
├── context/
│   ├── DashboardContext.tsx
│   └── index.ts
├── lib/
│   ├── formatters.ts         # Data formatting utilities
│   ├── transformers.ts       # API response transformers
│   └── constants.ts          # Feature-specific constants
├── types/
│   └── index.ts              # View model types
└── index.ts                  # Public API of the module

Component Organization

components/
├── [ComponentName].tsx       # Main component file
├── [ComponentName].test.tsx  # Unit tests (if applicable)
└── index.ts                  # Barrel export

Hooks Organization

hooks/
├── useFeatureData.ts         # Data fetching hooks
├── useFeatureActions.ts      # Mutation hooks
├── useFeatureState.ts        # Local state hooks
└── index.ts

Shared Modules

modules/shared/

Components and utilities shared across multiple features:

shared/
├── components/
│   ├── Layout/               # Layout components
│   ├── Navigation/           # Navigation components
│   ├── DataTable/            # Reusable data tables
│   └── Forms/                # Form components
├── hooks/
│   ├── useUser.ts            # Current user hook
│   ├── useOrganization.ts    # Organization context
│   └── usePermissions.ts     # Permission checks
└── lib/
    ├── api.ts                # API client configuration
    └── utils.ts              # Shared utilities

modules/ui/

Low-level UI components (design system):

ui/
├── Button/
├── Input/
├── Select/
├── Dialog/
├── Toast/
└── ...

Naming Conventions

Files

Type	Convention	Example
Components	PascalCase	UserProfile.tsx
Hooks	camelCase with use prefix	useUserProfile.ts
Context	PascalCase with Context suffix	UserContext.tsx
Utilities	camelCase	formatDate.ts
Constants	camelCase or SCREAMING_SNAKE_CASE	constants.ts
Types	PascalCase	types.ts or UserTypes.ts

Exports

Use barrel exports (index.ts) for clean imports:

// modules/dashboard/components/index.ts
export { DashboardHeader } from './DashboardHeader';
export { StatsCard } from './StatsCard';
export { ActivityFeed } from './ActivityFeed';

// Usage
import { DashboardHeader, StatsCard } from '@/modules/dashboard/components';

Route-Module Mapping

Routes in app/(app)/ should map to modules in modules/:

app/(app)/
├── dashboard/
│   └── page.tsx          -> modules/dashboard/
├── users/
│   ├── page.tsx          -> modules/users/
│   └── [id]/
│       └── page.tsx      -> modules/users/ (detail view)
├── settings/
│   └── page.tsx          -> modules/settings/
└── orders/
    ├── page.tsx          -> modules/orders/
    └── [id]/
        └── page.tsx      -> modules/orders/ (detail view)

Import Path Aliases

Configure in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@/modules/*": ["./modules/*"],
      "@/components/*": ["./components/*"],
      "@/lib/*": ["./lib/*"]
    }
  }
}

Best Practices

1. Colocation: Keep related files close together
2. Single Responsibility: Each module should have one clear purpose
3. Explicit Dependencies: Import what you need, avoid implicit globals
4. Barrel Exports: Use index.ts for public APIs
5. Private by Default: Only export what needs to be shared

Anti-Patterns to Avoid

• Deeply nested folder structures (max 3-4 levels)
• Circular dependencies between modules
• Mixing feature code with shared utilities
• Importing internal module files directly (use barrel exports)
• Creating "utils" folders that become dumping grounds