# Frontend Structure Guide

Laravel + Inertia + Vue (Module-Based Architecture)

---

## Core Principle

Structure the frontend by **module first**, not by technical layer.

Each module owns:

- Pages
- Components
- Forms
- Actions
- Types

Shared/global logic lives at the root of `resources/js/`.

---

# Root Structure

resources/js/
│
├── app.ts
├── bootstrap.ts
│
├── modules/
│
├── components/ # Global reusable UI components
│ ├── ui/
│ └── layout/
│
├── composables/ # Global reusable logic
├── layouts/ # Global layouts (AppLayout, AuthLayout)
├── types/ # Global shared types
├── utils/ # Utility helpers
│
└── stores/ # Optional global state (Pinia)

---

# Small Module Structure

Use this for:

- Simple CRUD modules
- Limited forms
- Limited business logic

Example: `users`

modules/
users/
pages/
Index.vue
Create.vue
Edit.vue

components/
UserForm.vue

user.form.ts
user.actions.ts
user.types.ts

### Responsibilities

- `pages/` → Inertia page entry points
- `components/` → Module-specific components
- `user.form.ts` → useForm definition + defaults
- `user.actions.ts` → Inertia submissions
- `user.types.ts` → Module-specific types

---

# Large Module Structure

Use this for:

- Complex business modules
- Multiple forms
- Multiple workflows
- Complex mutations

Example: `transactions`

modules/
transactions/
pages/
Index.vue
Show.vue
Create.vue
Refund.vue

components/
TransactionForm.vue
ItemsTable.vue
PaymentSection.vue

forms/
sale.form.ts
refund.form.ts
payment.form.ts

actions/
sale.actions.ts
refund.actions.ts
payment.actions.ts

transactions.types.ts

### Responsibilities

- `forms/` → Multiple form definitions
- `actions/` → Business intent methods
- `components/` → UI blocks specific to this module
- `pages/` → Route-level orchestration

---

# Root-Level Shared Logic Rules

components/ → Pure reusable UI (Button, Input, Modal)
composables/ → Reusable logic (useConfirm, usePermissions)
layouts/ → App-level layouts
types/ → Shared interfaces (Pagination, ApiResponse)
utils/ → Helpers (formatDate, debounce)
stores/ → Global state (auth, ui)

### Root must:

- Contain no module-specific business logic
- Not depend on any module
- Be reusable across multiple modules

If a file imports something from `modules/`,
it does NOT belong at root.

---

# File Responsibility Guidelines

## Forms (`*.form.ts`)

- Define `useForm`
- Default values
- Optional transform logic
- No routing

## Actions (`*.actions.ts`)

- Call `form.post`, `form.put`, `router.delete`
- Express business intent (createUser, refundSale)
- No UI logic

## Pages

- Receive backend props
- Compose module components
- Trigger actions

## Components

- UI focused
- Module-scoped unless globally reusable

---

# Scaling Strategy

| Module Size | Structure Style                          |
| ----------- | ---------------------------------------- |
| Small       | Flat (form + actions as files)           |
| Medium      | Flat with growing components             |
| Large       | Separate `forms/` and `actions/` folders |

Do not enforce a single rule globally.
Structure depends on module complexity.

---

# Architectural Rule

If you delete one module folder,
the rest of the application should still compile.

That ensures:

- No cross-module coupling
- Clear ownership
- Strong boundaries

---

# Summary

- Module-first organization
- Root-level shared logic
- Flat structure for small modules
- Nested structure for large modules
- Pages orchestrate
- Forms define state
- Actions define intent