costco-grocery-list/docs/architecture/component-structure.md

Frontend Component Organization

This document describes the organized structure of the frontend codebase, implemented to improve maintainability as the application grows.

Directory Structure

frontend/src/
├── api/                    # API client functions
│   ├── auth.js            # Authentication endpoints
│   ├── axios.js           # Axios instance with interceptors
│   ├── list.js            # Grocery list endpoints
│   └── users.js           # User management endpoints
│
├── components/            # React components (organized by function)
│   ├── common/           # Reusable UI components
│   │   ├── ErrorMessage.jsx
│   │   ├── FloatingActionButton.jsx
│   │   ├── FormInput.jsx
│   │   ├── SortDropdown.jsx
│   │   ├── UserRoleCard.jsx
│   │   └── index.js      # Barrel exports
│   │
│   ├── modals/           # All modal/dialog components
│   │   ├── AddImageModal.jsx
│   │   ├── AddItemWithDetailsModal.jsx
│   │   ├── ConfirmBuyModal.jsx
│   │   ├── EditItemModal.jsx
│   │   ├── ImageModal.jsx
│   │   ├── ImageUploadModal.jsx
│   │   ├── ItemClassificationModal.jsx
│   │   ├── SimilarItemModal.jsx
│   │   └── index.js      # Barrel exports
│   │
│   ├── forms/            # Form components and input sections
│   │   ├── AddItemForm.jsx
│   │   ├── ClassificationSection.jsx
│   │   ├── ImageUploadSection.jsx
│   │   └── index.js      # Barrel exports
│   │
│   ├── items/            # Item display and list components
│   │   ├── GroceryItem.tsx
│   │   ├── GroceryListItem.jsx
│   │   ├── SuggestionList.tsx
│   │   └── index.js      # Barrel exports
│   │
│   └── layout/           # Layout and navigation components
│       ├── AppLayout.jsx
│       ├── Navbar.jsx
│       └── index.js      # Barrel exports
│
├── constants/            # Application constants
│   ├── classifications.js # Item types, groups, zones
│   └── roles.js          # User roles (viewer, editor, admin)
│
├── context/              # React context providers
│   └── AuthContext.jsx   # Authentication context
│
├── pages/                # Top-level page components
│   ├── AdminPanel.jsx    # User management dashboard
│   ├── GroceryList.jsx   # Main grocery list page
│   ├── Login.jsx         # Login page
│   └── Register.jsx      # Registration page
│
├── styles/               # CSS files (organized by type)
│   ├── pages/           # Page-specific styles
│   │   ├── GroceryList.css
│   │   ├── Login.css
│   │   └── Register.css
│   │
│   ├── components/      # Component-specific styles
│   │   ├── AddItemWithDetailsModal.css
│   │   ├── ClassificationSection.css
│   │   ├── EditItemModal.css
│   │   ├── ImageUploadSection.css
│   │   └── Navbar.css
│   │
│   ├── theme.css        # **GLOBAL THEME VARIABLES** (colors, spacing, typography)
│   ├── THEME_USAGE_EXAMPLES.css # Examples of using theme variables
│   ├── App.css          # Global app styles
│   └── index.css        # Root styles (uses theme variables)
│
├── utils/                # Utility functions
│   ├── PrivateRoute.jsx  # Authentication guard
│   ├── RoleGuard.jsx     # Role-based access guard
│   └── stringSimilarity.js # String matching utilities
│
├── App.jsx               # Root app component
├── main.tsx              # Application entry point
├── config.ts             # Configuration (API URL)
└── types.ts              # TypeScript type definitions

Import Patterns

Using Barrel Exports (Recommended)

Barrel exports (index.js files) allow cleaner imports from component groups:

// ✅ Clean barrel import
import { FloatingActionButton, SortDropdown } from '../components/common';
import { EditItemModal, SimilarItemModal } from '../components/modals';
import { AddItemForm, ClassificationSection } from '../components/forms';

Direct Imports (Alternative)

You can also import components directly when needed:

// Also valid
import FloatingActionButton from '../components/common/FloatingActionButton';
import EditItemModal from '../components/modals/EditItemModal';

Component Categories

common/ - Reusable UI Components

• Purpose: Generic, reusable components used across multiple pages
• Examples: Buttons, dropdowns, form inputs, error messages
• Characteristics: Highly reusable, minimal business logic

modals/ - Dialog Components

• Purpose: All modal/dialog/popup components
• Examples: Confirmation dialogs, edit forms, image viewers
• Characteristics: Overlay UI, typically used for focused interactions

forms/ - Form Sections

• Purpose: Form-related components and input sections
• Examples: Multi-step forms, reusable form sections
• Characteristics: Handle user input, validation, form state

items/ - Item Display Components

• Purpose: Components specific to displaying grocery items
• Examples: Item cards, item lists, suggestion lists
• Characteristics: Domain-specific (grocery items)

layout/ - Layout Components

• Purpose: Application structure and navigation
• Examples: Navigation bars, page layouts, wrappers
• Characteristics: Define page structure, persistent UI elements

Style Organization

styles/pages/

Page-specific styles that apply to entire page components.

styles/components/

Component-specific styles for individual reusable components.

Benefits of This Structure

1. Scalability: Easy to add new components without cluttering directories
2. Discoverability: Intuitive naming makes components easy to find
3. Maintainability: Related code is grouped together
4. Separation of Concerns: Clear boundaries between different types of components
5. Import Clarity: Barrel exports reduce import statement complexity
6. Team Collaboration: Clear conventions for where new code should go

Adding New Components

When adding a new component, ask:

1. Is it reusable across pages? → common/
2. Is it a modal/dialog? → modals/
3. Is it form-related? → forms/
4. Is it specific to grocery items? → items/
5. Does it define page structure? → layout/
6. Is it a full page? → pages/

Then:

1. Create the component in the appropriate subdirectory
2. Add the component to the subdirectory's index.js barrel export
3. Create corresponding CSS file in styles/pages/ or styles/components/

Migration Notes

This structure was implemented on January 2, 2026 to organize 20+ components and 10+ CSS files that were previously in flat directories. All import paths have been updated to reflect the new structure.

Theming System

The application uses a centralized theming system via CSS custom properties (variables) defined in styles/theme.css.

Theme Variables

All design tokens are defined in theme.css including:

• Colors: Primary, secondary, semantic (success, danger, warning), neutrals
• Spacing: Consistent spacing scale (xs, sm, md, lg, xl, 2xl, 3xl)
• Typography: Font families, sizes, weights, line heights
• Borders: Widths and radius values
• Shadows: Box shadow presets
• Transitions: Timing functions
• Z-index: Layering system for modals, dropdowns, etc.

Using Theme Variables

/* Instead of hardcoded values */
.button-old {
  background: #007bff;
  padding: 0.6em 1.2em;
  border-radius: 4px;
}

/* Use theme variables */
.button-new {
  background: var(--color-primary);
  padding: var(--button-padding-y) var(--button-padding-x);
  border-radius: var(--button-border-radius);
}

Benefits

1. Consistency: All components use the same design tokens
2. Maintainability: Change once in theme.css, updates everywhere
3. Theme Switching: Easy to implement dark mode (already scaffolded)
4. Scalability: Add new tokens without touching component styles
5. Documentation: Variable names are self-documenting

Utility Classes

The theme file includes utility classes for common patterns:

<!-- Spacing -->
<div class="mt-3 mb-4 p-2">Content</div>

<!-- Text styling -->
<span class="text-primary font-weight-bold">Important</span>

<!-- Flexbox -->
<div class="d-flex justify-between align-center gap-2">Items</div>

See styles/THEME_USAGE_EXAMPLES.css for complete examples of refactoring existing CSS to use theme variables.