# 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:

```javascript
// ✅ 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:

```javascript
// 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

```css
/* 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:

```html
<!-- 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.