Project Structure

Project Structure

This document provides a detailed overview of the Fallout Web App's directory structure and organization.

📁 Root Directory Structure

fallout/
├── public/              # Static assets
├── src/                 # Source code
├── .claude/            # Claude AI configuration
├── .github/            # GitHub configuration and agents
├── .env.example        # Environment variables template
├── .gitignore          # Git ignore rules
├── eslint.config.js    # ESLint configuration
├── index.html          # HTML entry point
├── package.json        # Project dependencies
├── package-lock.json   # Dependency lock file
├── README.md           # Project documentation
├── tsconfig.json       # TypeScript configuration
└── vite.config.ts      # Vite build configuration

📂 Source Directory (src/)

The src directory contains all the application source code, organized by functionality:

API Layer (src/api/)

Handles all HTTP requests and API integrations.

src/api/
├── axios.ts          # Axios instance configuration with interceptors
└── services.ts       # API service functions and endpoints

Key Features:

• Centralized API configuration
• Request/response interceptors
• Token-based authentication support
• Error handling middleware
• TypeScript typed responses

Components (src/components/)

Reusable React components used throughout the application.

src/components/
├── Navigation.tsx      # Main navigation component
├── Navigation.css      # Navigation styles
├── Pagination.tsx      # Reusable pagination component
└── Pagination.css      # Pagination styles

Component Guidelines:

• Each component has its own CSS file
• Components are typed with TypeScript interfaces
• Follows React functional component patterns
• Props are validated with TypeScript

Constants (src/constants/)

Application-wide constants and configuration values.

src/constants/
└── index.ts           # Constant definitions

Custom Hooks (src/hooks/)

Reusable React hooks for common functionality.

src/hooks/
└── useInfiniteScroll.ts   # Hook for infinite scroll implementation

Available Hooks:

• useInfiniteScroll - IntersectionObserver-based infinite scrolling
• Configurable threshold and root margin
• Loading and error state management

Pages (src/pages/)

Top-level route components that represent different pages of the application.

src/pages/
├── Home.tsx              # Landing page (/)
├── Dashboard.tsx         # Dashboard with metrics (/dashboard)
├── Posts.tsx            # Paginated posts list (/posts)
├── InfinitePosts.tsx    # Infinite scroll posts (/posts/infinite)
├── Profile.tsx          # User profile page (/profile)
├── Settings.tsx         # Settings page (/settings)
├── About.tsx            # About page (/about)
└── NotFound.tsx         # 404 error page

Page Responsibilities:

• Route-level components
• Data fetching with React Query
• State management with Zustand
• Layout composition

State Management (src/store/)

Zustand stores for global state management.

src/store/
└── counterStore.ts      # Example counter store with Immer

Store Features:

• Lightweight state management with Zustand
• Immutable updates with Immer
• TypeScript typed stores
• Devtools support

TypeScript Types (src/types/)

Shared TypeScript type definitions and interfaces.

src/types/
└── index.ts            # Type definitions

Utility Functions (src/utils/)

Helper functions and utilities used across the application.

src/utils/
└── index.ts            # Utility functions

Root Files

src/
├── App.tsx            # Main app component with routing
├── App.css           # App-level styles
├── main.tsx          # Application entry point
├── index.css         # Global styles
└── vite-env.d.ts     # Vite environment type definitions

🔧 Configuration Files

TypeScript Configuration (tsconfig.json)

Defines TypeScript compiler options:

• Target: ES2020
• Module: ESNext
• Strict mode enabled
• React JSX support
• Path aliases (if configured)

Vite Configuration (vite.config.ts)

Vite build tool configuration:

• React plugin
• Development server settings
• Build optimization
• Port configuration (default: 3000)

ESLint Configuration (eslint.config.js)

Code quality and linting rules:

• TypeScript ESLint parser
• React hooks plugin
• React refresh plugin
• Custom rules for code standards

Environment Variables (.env.example)

Template for environment-specific configuration:

VITE_API_URL=https://jsonplaceholder.typicode.com

Usage:

1. Copy .env.example to .env
2. Update values for your environment
3. Access via import.meta.env.VITE_*

📝 File Naming Conventions

• Components: PascalCase (e.g., Navigation.tsx)
• Hooks: camelCase with use prefix (e.g., useInfiniteScroll.ts)
• Stores: camelCase with Store suffix (e.g., counterStore.ts)
• Utilities: camelCase (e.g., formatDate.ts)
• Types: PascalCase for interfaces/types
• CSS Files: Match component name (e.g., Navigation.css)

🎯 Best Practices

File Organization

• Group related files together
• Keep components small and focused
• Extract reusable logic into hooks
• Use barrel exports (index.ts) for cleaner imports

Import Structure

// External dependencies
import React from 'react'
import { useQuery } from '@tanstack/react-query'

// Internal components
import { Navigation } from '@/components/Navigation'

// Utilities and helpers
import { formatDate } from '@/utils'

// Types
import type { User } from '@/types'

// Styles
import './Component.css'

Component Structure

// Imports
import React from 'react'
import './Component.css'

// Types
interface ComponentProps {
  // prop definitions
}

// Component
export const Component: React.FC<ComponentProps> = (props) => {
  // Hooks
  // Event handlers
  // Render
  return <div>...</div>
}

🔍 Finding Files

Use these patterns to locate specific functionality:

• API calls: Check src/api/services.ts
• Routing: Look in src/App.tsx
• Global state: Check src/store/
• Shared types: Find in src/types/
• Page components: Located in src/pages/
• Reusable components: Check src/components/
• Custom hooks: Located in src/hooks/

📚 Related Documentation

• API Integration - Working with the API layer
• Components - Component development guide
• State Management - Using Zustand stores
• Styling - CSS and styling conventions

---

Back to: Home