File Organization

This guide explains the file and directory organization standards for LamaPress projects. Consistent organization improves maintainability and makes the codebase easier to navigate.

Table of Contents

• Directory Structure
• Component Organization
• Function Files
• Configuration Files
• Asset Organization
• Best Practices

Directory Structure

Root Structure

lamapress/
├── components/          # All reusable components
├── config/              # Configuration files
├── dist/                # Compiled assets (generated)
├── functions/           # PHP functions and WordPress hooks
├── src/                 # Source files
├── tailwind/            # Tailwind configuration
├── public/              # Public assets
├── vendor/              # Composer dependencies
├── main.js              # Main JavaScript entry point
├── admin.js             # Admin JavaScript entry point
├── functions.php        # Theme entry point
└── package.json         # Node.js dependencies

Components Directory

components/
├── blocks/              # Reusable UI components
│   ├── accordion/
│   ├── image/
│   └── video/
├── parts/               # Atomic components
│   ├── buttons/
│   ├── icon/
│   └── img/
├── sections/            # Full-width page sections
│   ├── hero_basic/
│   ├── rich_content/
│   └── flexible/
└── templates/           # Page templates
    ├── home.php
    ├── flex.php
    └── contentpage.php

Functions Directory

functions/
├── admin/               # Admin-specific functions
├── bunny/               # Bunny.net integration
├── admin.php            # Admin setup
├── bootstrap.php        # Bootstrap and includes
├── helpers.php          # Helper functions
├── includes.php         # Component loading functions
└── vite.php             # Vite asset loading

Config Directory

config/
├── fields/              # Global ACF field definitions
│   ├── company.php
│   └── employee.php
├── aliases.php          # Path aliases
├── post-types.php       # Custom post types
├── taxonomies.php       # Custom taxonomies
└── media.php            # Image size definitions

Source Directory

src/
├── js/                  # JavaScript source
│   ├── components/      # Component JavaScript
│   ├── core/            # Core system files
│   └── scripts.js       # Main script
└── scss/                # SCSS source
    ├── base/            # Base styles
    ├── sections/        # Section styles
    └── styles.scss      # Main stylesheet

Component Organization

Section Structure

components/sections/hero_basic/
├── index.php            # Required: Main template
├── acf.php              # Required: ACF field definitions
├── index.js             # Optional: JavaScript class
├── style.scss           # Optional: Component styles
└── functions.php        # Optional: Component functions

Block Structure

components/blocks/accordion/
├── index.php            # Required: Main template
├── acf.php              # Optional: ACF fields (if reusable)
├── index.js             # Optional: JavaScript class
└── style.scss           # Optional: Component styles

Part Structure

components/parts/buttons/default/
├── index.php            # Required: Main template
├── index.js             # Optional: JavaScript class
└── style.scss           # Optional: Component styles

File Naming

Standard Names:

• index.php - Always use index.php for templates
• index.js - Always use index.js for JavaScript
• acf.php - Always use acf.php for ACF fields
• style.scss - Always use style.scss for styles
• functions.php - Always use functions.php for component functions

Don't use:

• accordion.php - Use index.php instead
• accordion.js - Use index.js instead
• fields.php - Use acf.php instead
• styles.scss - Use style.scss instead

Function Files

Organization

Functions are organized by purpose:

functions/
├── admin.php            # Admin area setup
├── bootstrap.php        # Bootstrap and includes
├── helpers.php          # Helper functions
├── includes.php         # Component loading functions
├── vite.php             # Vite asset loading
├── advanced-custom-fields.php  # ACF setup
├── register-section-fields.php # ACF field registration
└── ...

File Naming

Format: snake_case.php

// ✅ Good
functions/register-section-fields.php
functions/advanced-custom-fields.php
functions/post-types.php

// ❌ Bad
functions/registerSectionFields.php  // camelCase
functions/RegisterSectionFields.php  // PascalCase

Function Grouping

Group related functions in the same file:

// functions/helpers.php
function llSvg($filename) { }
function llConfig($file) { }
function slugify($text) { }

// functions/includes.php
function llSection($name, $key) { }
function llBlock($name, $props) { }
function llPart($name, $props) { }

Configuration Files

Config Directory

config/
├── aliases.php          # Path aliases
├── post-types.php       # Custom post types
├── taxonomies.php       # Custom taxonomies
├── media.php            # Image sizes
├── menus.php            # Menu locations
├── fields/              # Global ACF fields
│   ├── company.php
│   └── employee.php
└── ...

File Structure

Return Arrays:

<?php
// config/post-types.php
return [
    [
        'name' => 'employee',
        'label' => 'Employees',
        // ...
    ],
];

Include in Bootstrap:

// functions/bootstrap.php
include_once $templateDirectory.'/config/post-types.php';

Asset Organization

Public Assets

public/
├── fonts/               # Font files
│   ├── SuisseIntl-Regular.woff2
│   └── SuisseIntl-Bold.woff2
├── images/              # Static images
│   └── logo.png
└── svg/                 # SVG icons
    ├── arrow-right.svg
    └── arrow-left.svg

Dist Directory

dist/                    # Generated - Don't edit directly
├── .vite/
│   └── manifest.json
├── assets/
│   ├── main-[hash].js
│   └── main-[hash].css
├── fonts/               # Copied from public/
└── svg/                 # Copied from public/

Source Assets

src/
├── js/                  # JavaScript source
│   ├── components/      # Component JavaScript
│   ├── core/            # Core system
│   └── scripts.js       # Entry point
└── scss/                # SCSS source
    ├── base/            # Base styles
    ├── sections/        # Section styles
    └── styles.scss      # Main stylesheet

Best Practices

1. Consistent Structure

Maintain consistent structure across components:

// ✅ Good - Consistent
components/blocks/accordion/
├── index.php
├── index.js
└── acf.php

components/blocks/image/
├── index.php
├── index.js
└── acf.php

2. Logical Grouping

Group related files together:

// ✅ Good - Related files together
functions/
├── admin.php
├── admin/
│   └── icon-select.php

3. Clear Naming

Use clear, descriptive names:

// ✅ Good
functions/register-section-fields.php
config/post-types.php

// ❌ Bad
functions/reg.php
config/pt.php

4. Avoid Deep Nesting

Keep directory depth reasonable:

// ✅ Good
components/blocks/accordion/index.php

// ❌ Bad
components/blocks/ui/interactive/accordion/component/index.php

5. Separate Concerns

Keep different types of files separate:

// ✅ Good
components/blocks/accordion/
├── index.php    # Template
├── index.js     # JavaScript
├── acf.php      # ACF fields
└── style.scss   # Styles

// ❌ Bad - Everything in one file
components/blocks/accordion.php  // Template, JS, CSS all mixed

Related Documentation

• Naming Conventions - File naming rules
• Component Guidelines - Component structure
• Coding Standards - General standards

---

Next Steps:

• Review Naming Conventions for naming rules
• Check Component Guidelines for component structure
• See Component System for component architecture