Most of this file described the repo as it was around v1.0: three domain
packages, two database tables, twenty-one classes. There are now eleven
packages, fifteen tables, and well over a hundred classes, so those
sections were not just redundant with `ls` and Schema.php — they were
teaching the wrong shape of the codebase. Same for the CI section, which
had drifted past the build job.

Cut the command list (composer.json has the scripts), the bootstrap
description, the directory tree, the table list, the Key Classes table,
and the CI job summary. Kept every rule the code can't explain on its
own: package-by-domain, no $wpdb outside repositories, capability checks
rather than role names, and the Schema.php version-bump gotcha.

Moved the Brain\Monkey and Mockery gotchas to tests/CLAUDE.md, which
loads only when working under tests/ instead of in every session.

Co-Authored-By: Claude Opus 5 <[email protected]>

2026-07-29 16:39:43 -03:00

1.9 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Run composer test after every code change before considering a task complete.

Architecture

Code organisation

Code is organised package-by-domain. Each domain package under src/<Domain>/ contains everything related to that domain: value objects, repositories, controllers, REST endpoints, and shortcode pages. Cross-cutting wiring classes (Plugin, AdminMenu, RestRegistrar, ShortcodeRegistrar, Schema) live directly under src/.

Data Storage

Custom database tables are created via dbDelta on activation; Schema.php holds the SQL.

All database access goes through repository classes within their domain package. No direct $wpdb calls outside repositories.

REST API Namespace

All endpoints live under /wp-json/us-scheduler/v1/. Permissions are enforced via permission_callback using capability checks (manage_availability, book_lesson), never role name checks.

Testing Approach

Tests stub WordPress with Brain\Monkey rather than booting a real WP install. The setup and the Brain\Monkey/Mockery API gotchas are in tests/CLAUDE.md.

Adding a Feature

If the feature touches Schema.php, bump both the Version: header and USC_VERSION in unsupervised-schedular.php. Plugin::boot() only re-runs Installer/dbDelta when the stored us_schedular_version differs, so a schema change without a version bump never reaches existing sites and inserts into new columns fail silently.
Write the feature doc in docs/features/<feature-name>.md (data model, API, classes, test paths).
Create a domain package under src/<Domain>/ containing all classes for that feature.
Add template(s) under templates/ if needed.
Write unit tests under tests/Unit/<Domain>/ mirroring the src/<Domain>/ structure.
Run composer test — all tests must pass before the feature is complete.

1.9 KiB Raw Blame History