Aiku ERP Development Guidelines

Expert-level Laravel 12 development guidelines for the Aiku open-source white-label ERP application. These rules enforce clean, self-documenting code with comprehensive test coverage.

Core Principles

**NEVER:**

**ALWAYS:**

Technology Stack

PHP Standards

Constructor Property Promotion

```php

public function __construct(public GitHub $github) { }

```

Type Declarations (Required)

```php

protected function isAccessible(User $user, ?string $path = null): bool

{

return $user->hasAccessTo($path);

}

```

Enums

Use TitleCase keys: `FavoritePerson`, `BestLake`, `Monthly`

PHPDoc

Add useful array shape definitions when appropriate. Prefer PHPDoc over inline comments.

Laravel Best Practices

Artisan Commands

Database & Eloquent

**Prefer Eloquent over raw queries:**

```php

// Good

Model::query()->with('relation')->where('active', true)->get();

// Avoid

DB::select('SELECT * FROM ...');

```

**Prevent N+1 queries with eager loading:**

```php

Post::with(['author', 'comments.user'])->get();

```

**Relationship methods with type hints:**

```php

public function posts(): HasMany

{

return $this->hasMany(Post::class);

}

```

**Migration column modifications:**

When modifying columns, include ALL previous attributes or they will be dropped.

**Laravel 12 eager loading limits:**

```php

$user->posts()->latest()->limit(10);

```

Models

Controllers & Validation

APIs

Use Eloquent API Resources with versioning unless existing routes follow different convention.

Queues

Implement `ShouldQueue` interface for time-consuming operations.

Authentication & Authorization

Use built-in features: gates, policies, Sanctum.

Routing

Configuration

```php

// Good

config('app.name')

// Bad

env('APP_NAME')

```

Inertia v2 + Vue 3

Structure

```php

Route::get('/users', function () {

return Inertia::render('Users/Index', [

'users' => User::all()

]);

});

```

Inertia v2 Features

Forms

**Recommended: `<Form>` component**

```vue

<Form @submit="handleSubmit" resetOnSuccess>

<!-- form fields -->

</Form>

```

**Alternative: `useForm` helper** (for programmatic control or existing conventions)

Use `search-docs` with queries like "form component", "useForm helper", "form component resetting" for guidance.

Pest Testing (Required)

Test Coverage

**Every change must be tested.** Write new tests or update existing ones, then run affected tests.

Creating Tests

```bash

Feature test (default)

php artisan make:test --pest UserTest

Unit test

php artisan make:test --pest --unit HelperTest

```

Test Structure

```php

it('validates user registration', function () {

$response = $this->postJson('/api/register', [

'email' => 'invalid-email'

]);

$response->assertUnprocessable();

});

```

Running Tests

```bash

All tests

php artisan test

Single file

php artisan test tests/Feature/ExampleTest.php

Filter by name (recommended after changes)

php artisan test --filter=testName

```

Assertions

Use specific methods over generic `assertStatus()`:

```php

$response->assertSuccessful();

$response->assertForbidden();

$response->assertNotFound();

```

Test Data

Mocking

```php

use function Pest\Laravel\mock;

mock(ExternalService::class)

->shouldReceive('getData')

->andReturn(['data']);

```

Never Remove Tests

Tests in `tests/` are core application assets, not temporary files. Do not delete without approval.

Laravel Pint

**Before finalizing changes:**

```bash

vendor/bin/pint

```

Do NOT use `--test` or `--dirty` flags. Just run `vendor/bin/pint` to fix formatting.

Laravel Pennant (Feature Flags)

This application uses Pennant for feature flag management across organizations and user types. Use `search-docs` for guidance.

Debugging

Tinker

Use `tinker` tool to execute PHP or query Eloquent models directly.

Database Queries

Use `database-query` tool for read-only database access.

Browser Logs

Use `browser-logs` tool to read recent browser errors and exceptions (ignore old logs).

Documentation Search (Critical)

**Use `search-docs` tool BEFORE making changes.**

This tool returns version-specific documentation for installed packages (Laravel, Inertia, Livewre, Filament, Pest, etc.).

Search Syntax

```javascript

// Multiple broad queries (recommended)

['rate limiting', 'routing rate limiting', 'routing']

// Simple word search (auto-stemming)

'authentication' // finds 'authenticate', 'auth'

// Multiple words (AND logic)

'rate limit' // finds both "rate" AND "limit"

// Exact phrases

'"infinite scroll"' // adjacent words in order

// Mixed

'middleware "rate limit"'

```

**Do NOT include package names in queries** (already filtered by version). Use `test resource table`, not `filament 4 test resource table`.

Vite Issues

If you get "Unable to locate file in Vite manifest" error:

1. Run `npm run build`, OR

2. Ask user to run `npm run dev` or `composer run dev`

Application Structure

Laravel 10 Structure (Current)

This project uses Laravel 10 structure (not migrated to Laravel 12's streamlined structure):

**Do NOT migrate to new structure** unless explicitly requested.

Directory Rules

Workflow

1. Check sibling files for conventions

2. Search documentation with `search-docs`

3. Use `php artisan make:*` with `--no-interaction`

4. Write/update tests

5. Run filtered tests: `php artisan test --filter=testName`

6. Run `vendor/bin/pint`

7. Verify tests pass

8. Ask user if they want full test suite run

Communication