PROJECT_STRUCTURE.md

Project Structure

This project has been refactored to follow best practices with a modular component-based architecture.

Directory Structure

non-react-app/
├── index.html                  # Main HTML entry point (minimal, loads components)
├── main.js                     # Main JavaScript entry point (orchestrates app initialization)
├── src/
│   ├── components/             # Component modules (separated by concern)
│   │   ├── button/
│   │   │   ├── button.html     # Button component markup
│   │   │   ├── button.css      # Button-specific styles
│   │   │   └── (no JS needed)  # Static component
│   │   ├── dialog/
│   │   │   ├── dialog.html     # Dialog component markup
│   │   │   ├── dialog.css      # Dialog-specific styles
│   │   │   └── dialog.js       # Dialog initialization logic
│   │   └── sidebar/
│   │       ├── sidebar.html    # Sidebar navigation markup
│   │       ├── sidebar.css     # Sidebar-specific styles
│   │       └── sidebar.js      # Navigation logic
│   ├── styles/
│   │   ├── base.css            # Base styles, theme variables, layout
│   │   └── global.css          # Global styles (imported from main.js)
│   └── utils/
│       ├── loadComponent.js    # Utility to dynamically load HTML partials
│       └── theme.js            # Theme switching functionality
├── package.json
└── PROJECT_STRUCTURE.md        # This file

Architecture Principles

1. Separation of Concerns

Each component is isolated in its own directory with:

• HTML - Component markup
• CSS - Component-specific styles
• JS - Component-specific logic (if needed)

2. Component Independence

• Each component is self-contained
• Components can be easily added, removed, or modified
• No tight coupling between components

3. Modular JavaScript

• JavaScript modules use ES6 imports/exports
• Each module has a single responsibility
• Utility functions are separated from component logic

4. Clean Entry Point

• index.html is minimal and clean
• Component HTML is loaded dynamically
• Styles are organized and imported separately

Component Loading Flow

1. index.html loads with basic structure and style imports
2. main.js initializes:
   • Web components library
   • Theme system
   • Component loader
3. Component HTML files are dynamically loaded into containers
4. Component JavaScript initializes interactivity after HTML loads

Adding a New Component

To add a new component (e.g., "card"):

1. Create component directory:

   src/components/card/
   

2. Create component files:

   • card.html - Component markup
   • card.css - Component styles
   • card.js - Component logic (if needed)

3. Import styles in index.html:

   <link rel="stylesheet" href="/src/components/card/card.css" />

4. Load component in main.js:

   import { initCard } from './src/components/card/card.js';
   
   await loadComponents([
     // ... existing components
     {
       url: '/src/components/card/card.html',
       target: '#content-container'
     }
   ]);
   
   initCard(); // Initialize after HTML loads

5. Add navigation link (if needed) in sidebar.html:

   <li class="nav-item">
     <a class="nav-link" data-section="cards">Cards</a>
   </li>

Benefits of This Structure

✅ Maintainability - Easy to find and modify specific components ✅ Scalability - Simple to add new components without affecting existing ones ✅ Reusability - Components can be easily reused or extracted ✅ Testability - Each module can be tested independently ✅ Collaboration - Multiple developers can work on different components ✅ Performance - Components can be lazy-loaded as needed ✅ Clean Code - Clear organization following industry best practices

Best Practices Followed

1. Single Responsibility Principle - Each file/module has one clear purpose
2. Don't Repeat Yourself (DRY) - Shared utilities are extracted
3. Separation of Concerns - HTML, CSS, and JS are properly separated
4. Modular Design - Components are independent and self-contained
5. Clear Naming - Descriptive file and function names
6. Documentation - Code comments explain purpose and usage