MyShift PHP Architecture Guide

Guide Claude Code when working with MyShift - a flat-file CMS for managing staff, shifts, time tracking, and leave requests using JSON files as the database. Built with PHP 8.3+ and a lightweight MVC architecture.

Project Architecture

MyShift uses namespace `MyShift\` mapped to `app/` directory with modern repository pattern and legacy model layer coexisting during transition.

MVC + Repository Architecture

**Controllers** (`app/Controllers/`):

Handle HTTP requests and orchestrate business logic

Domain-specific: Auth, Staff, Shifts, Timeoffs, Store, Stats, Locks, Logs

Receive dependencies via injection in `public/index.php`

**Repositories** (`app/Repositories/`) - Modern data access layer with three strategies:

1. **SimpleJsonRepository**: Single-file storage (e.g., `timeoffs.json`, `roles.json`)

- Best for small collections (<1000 items), infrequent writes

- Entire file rewritten on each update

2. **IndexedJsonRepository**: Dual-file pattern (e.g., `staff/index.json` + `staff/{id}.json`)

- Index file contains lightweight summaries for fast listings

- Detail files contain full records loaded only when needed

- Best for large collections with frequent individual updates

3. **NestedJsonRepository**: Complex nested structures (e.g., shifts by date)

- Best for hierarchical data with time-based access patterns

**Services** (`app/Services/`):

Business logic layer between controllers and repositories

`AuthorizationService`: Permission checking with caching

`StaffService`, `ShiftsService`: Domain-specific operations

`SalaryCalculator`, `ProfileImageService`: Utility services

**Value Objects / DTOs** (`app/ValueObjects/`):

Immutable data transfer objects with validation

`StaffDTO`, `ShiftDTO`, `TimeoffDTO`, etc.

Used to pass type-safe data between layers

**Models** (`app/Models/`) - Legacy layer being replaced by Repository pattern:

Still used in some areas but prefer Repositories for new code

All file I/O goes through `JsonIO` class with file locking

Data Persistence Layer

**JsonIO** (`app/Core/JsonIO.php`) provides atomic read/write operations:

Uses file locking: `LOCK_SH` for reads, `LOCK_EX` for writes

Automatic backup on write: `backup/{relativePath}.{timestamp}.bak`

Writes to `.tmp` file first, then renames for atomicity

**Critical**: Always use `JsonIO` or Repositories - never `file_get_contents()`/`file_put_contents()` directly

**Data Structure** (`database/{storeId}/`):

`store.json` - Store configuration, salary types, opening hours

`staff/index.json` - List of all staff (summary records)

`staff/{id}.json` - Individual staff full records

`shifts.json` - Array of daily shift records

`timeoffs.json` - Leave request records

`logs.json` - Audit trail

Authentication & Authorization

Authentication

Session-based auth managed by `AuthController`

Users stored in `$_SESSION['user']`

Two user types: `owner` (global admin) and `staff` (store-level)

Auto-login via "Remember Me" tokens (30-day persistent sessions)

Modern Authorization System

**Gate Facade** - Preferred approach for permission checks:

```php

use MyShift\Services\Authorization\Gate;

// Check permission

if (Gate::allows('planning.read', $storeId)) { /* ... */ }

if (Gate::denies('staff.delete', $storeId, $staff)) { /* ... */ }

// Throw 403 if denied

Gate::authorize('planning.create', $storeId);

```

**AuthorizationService** - Core permission logic:

Abilities format: `"domain.action"` or `"domain.action.scope"`

- Examples: `"planning.update.own"`, `"staff.delete.all"`

Scopes: `all` (any resource) or `own` (only user's own resources)

Permission caching via `PermissionCache` for performance

Managers get elevated permissions automatically

**Legacy Permission Function** - Being phased out:

`can_do($storeId, $domain, $action, $context)` in `public/index.php`

Prefer Gate for new code

**Permission Storage**:

Role-based permissions: `database/{storeId}/roles.json`

Manager designation: `store.json` → `staffing.manager_id`

Check manager status: `\MyShift\Helpers\AuthHelper::isManager($user, $storeId)`

Step-by-Step Development Tasks

Adding a New Field to Staff

1. **Update model**: `app/Models/Staff.php` - add field to `create()` and `update()` methods

2. **Update validation**: Check `app/Helpers/Validator.php` if validation needed

3. **Update controller**: `app/Controllers/StaffController.php` - ensure field is processed

4. **Update view**: `public/view/staff_detail.php` - add input/display element

5. **Update frontend**: `public/assets/js/app.js` - handle field in form submission

Adding a New Permission

1. **Update role structure**: Add action to `database/{storeId}/roles.json`

```json

{

"domain_name": {

"action_name": {"all": true, "own": false}

}

```

2. **Add permission check in controller** (modern approach):

```php

use MyShift\Services\Authorization\Gate;

Gate::authorize('domain.action', $storeId); // Throws 403 if denied

```

3. **For scope-based permissions** (all vs own):

```php

// Check if user can update any staff OR their own

Gate::authorize('staff.update.all', $storeId, $staffRecord);

// Fallback to own if not allowed for all

if (Gate::denies('staff.update.all', $storeId)) {

Gate::authorize('staff.update.own', $storeId, $staffRecord);

}

```

Working with Repositories

**Choose the right repository type**:

```php

// SimpleJsonRepository - Single file for entire collection

// Use for: Roles, Timeoffs, Locks

$repo = new SimpleJsonRepository($io, 'database/1/timeoffs.json');

// IndexedJsonRepository - Index file + individual detail files

// Use for: Staff (large collections with frequent individual access)

$repo = new IndexedJsonRepository($io, 'database/1/staff/index.json', 'database/1/staff');

// NestedJsonRepository - Hierarchical nested structures

// Use for: Shifts (organized by date)

```

**Basic CRUD operations**:

```php

// Create

$id = $repository->create(['name' => 'John', 'email' => '[email protected]']);

// Read

$item = $repository->findById($id);

$allItems = $repository->findAll();

// Update

$repository->update($id, ['name' => 'Jane']);

// Delete

$repository->delete($id);

```

**Using DTOs**:

```php

// DTOs are immutable value objects

$staffDTO = new StaffDTO(

id: 1,

staffCode: 'EMP001',

displayName: 'John Doe',

// ... other required fields

);

// Access properties (read-only)

$name = $staffDTO->displayName;

```

Logging Actions

Use `ActionLogger` for audit trail:

```php

$actionLogger->log(

$storeId,

current_user() ?? [],

'action_name',

'resource_type',

['context' => 'data']

);

```

Working with Shifts

Shifts are stored per-day in `shifts.json`: `[{date: 'Y-m-d', shifts: [{id, staff_id, start, end, type, cross_midnight}]}]`

Use `ShiftsController` methods; never manipulate `shifts.json` directly

Calculate salary using `SalaryCalculator` (`app/Helpers/SalaryCalculator.php`)

Resource Locking System

`LocksController` + `Locks` model implements optimistic locking:

Prevents concurrent editing conflicts

Locks timeout after 5 minutes (default)

Lock structure: `{resource: 'staff', resource_id: 5, user: {id, name}, acquired_at, timeout}`

**Always release locks after successful updates**

API Patterns

Standard CRUD Endpoints

```

GET /api/stores/{id}/staff - List all

GET /api/stores/{id}/staff/{staffId} - Get one

POST /api/stores/{id}/staff - Create

PUT /api/stores/{id}/staff/{staffId} - Update

DELETE /api/stores/{id}/staff/{staffId} - Delete

```

Same pattern for: `shifts`, `timeoffs`

Specialized Endpoints

```

POST /api/login - Authenticate

POST /api/logout - End session

GET /api/me/permissions?store_id={id} - Get current user permissions

GET /api/stores/{id}/stats?start_date=X&end_date=Y - Analytics

POST /api/stores/{id}/locks - Acquire lock

DELETE /api/stores/{id}/locks - Release lock

POST /api/stores/{id}/staff/{id}/profile-image - Upload PNG (resized to 500x500)

POST /api/stores/{id}/store/upload_shifts - Import shifts from Excel

```

Response Format

Success: `200 OK` with JSON data

Created: `201 Created` with new resource

Validation errors: `422 Unprocessable Entity` with `{_errors: {field: ['error_key']}}`

Auth required: `401 Unauthorized`

Permission denied: `403 Forbidden`

Resource locked: `423 Locked`

Store Configuration Critical Fields

**`store.json` fields requiring special handling**:

1. **salary_types**: Completely replaced via `PUT /api/stores/{id}/store`

- Structure: `{id, name, code, start_time, end_time, fixed_amount, is_active}`

- Times must be `HH:MM` format

- Staff records map codes to amounts: `employment.salary = {"MORNING": 100.0}`

2. **opening_hours.default_schedule.shifts**: Ordered array of shift templates

- Structure: `{type, start, end}` (times in `HH:MM`)

- Frontend depends on this structure

3. **staffing.manager_id**: Must reference existing `staff/{id}.json`

- Server validates file existence on update

**Frontend selectors tied to backend**: Dynamic fields in `public/view/store.php` use `.salary-type-row` and `.opening-shift-row` classes parsed by `public/assets/js/app.js`. Do not change these selectors without updating JavaScript.

Internationalization (I18n)

**Language files**: `app/lang/{code}.php` return associative arrays

Current default locale: `ja` (Japanese)

Switch language: `/?lang=fr` or `/?lang=en` (stored in cookie + session)

Helper function: `__('translation.key', ['var' => 'value'])`

Initialized in `public/index.php` via `\MyShift\Helpers\I18n::init()`

To add a new language, create `app/lang/{code}.php` with translation keys.

Development Commands

```bash

Install dependencies

composer install

Development server (built-in PHP)

php -S localhost:8000 -t public

Production: Apache configuration

- DocumentRoot → public/

- Enable mod_rewrite for routing

- Ensure write permissions for database/ and backup/

```

Critical Constraints

1. **File Locking**: Always use `JsonIO` for reads/writes - never use `file_get_contents()`/`file_put_contents()` directly

2. **Validation**: All user inputs must pass through validation before persistence

3. **Backup Directory**: Exposed `database/` is a security risk; ensure `.htaccess` blocks direct access

4. **Time Format**: All times stored as `HH:MM` strings, dates as `Y-m-d`

5. **Manager Validation**: `store.json`'s `staffing.manager_id` must reference existing staff file

6. **Salary Types**: Always replace the entire `salary_types` array; partial updates not supported

7. **Profile Images**: Must be PNG format, auto-resized to 500x500, stored as `public/assets/images/profiles/{storeId}/{staff_code}.png`

Common Pitfalls

**Architecture mixing**: Codebase is transitioning from Models to Repositories. For new code, use Repository pattern and Gate facade

**Permission checks**: Use `Gate::authorize()` for new code, not the legacy `can_do()` function

**Direct file access**: Always use `JsonIO` or Repositories

**Frontend-backend coupling**: Don't modify `public/assets/js/app.js` field selectors without updating corresponding view templates

**Resource locking**: Don't skip lock acquisition/release when editing shared resources

**Audit trail**: Don't forget to log state-changing actions with `ActionLogger`

**Error exposure**: Don't expose internal error messages to API responses in production

**Manager designation**: Remember that managers are determined by `store.json` staffing config, not just role permissions

**Repository choice**: Use IndexedJsonRepository for large collections (Staff), SimpleJsonRepository for small ones (Timeoffs, Roles)

Testing & Debugging

Basic test framework in `app/Helpers/GlobalTester.php` - expose via route:

```php

Route::add('/test', function () {

require_once __DIR__ . '/../app/Helpers/GlobalTester.php';

$tester = new MyShift\Helpers\GlobalTester();

echo '<pre>' . json_encode($tester->run(), JSON_PRETTY_PRINT) . '</pre>';

});

```

MyShift PHP Architecture Guide

MyShift PHP Architecture Guide

Project Architecture

MVC + Repository Architecture

Data Persistence Layer

Authentication & Authorization

Authentication

Modern Authorization System

Step-by-Step Development Tasks

Adding a New Field to Staff

Adding a New Permission

Working with Repositories

Logging Actions

Working with Shifts

Resource Locking System

API Patterns

Standard CRUD Endpoints

Specialized Endpoints

Response Format

Store Configuration Critical Fields

Internationalization (I18n)

Development Commands

Install dependencies

Development server (built-in PHP)

Production: Apache configuration

- DocumentRoot → public/

- Enable mod_rewrite for routing

- Ensure write permissions for database/ and backup/

Critical Constraints

Common Pitfalls

Testing & Debugging

Reviews (0)