Glossary

A reference for terms and patterns used across our projects. If you encounter unfamiliar terminology in the decision records, check here first.

Architecture & Patterns

Action

A final readonly PHP class with a single execute() method that contains business logic. Actions are the authority for all mutations — creating, updating, and deleting records. See Principles.

DTO (Data Transfer Object)

A typed, immutable object that carries validated data between layers. In our pipeline, Form Requests produce DTOs, and DTOs are passed to Actions. No raw arrays.

Form Request

Laravel's built-in request validation class. In our pipeline, it validates HTTP input and converts it to a DTO before the Action sees the data.

ResourceData

A custom base class that replaces Laravel's JsonResource for API response serialization. Uses constructor-promoted readonly properties, reflection-based serialization, and runtime relation validation. See Unified ResourceData Pattern.

Architecture Tests

Automated tests written with Pest PHP that verify structural patterns across the codebase. They run on every PR and catch things like: "this delete Action doesn't handle all cascade relations" or "this Action doesn't call the audit logger."

Cascade Relations

When a parent model is deleted, its children must be cleaned up. Each model declares its children via cascadeRelations(), and the delete Action handles them explicitly. See Cascade Deletion & Soft Deletes.

GithubOAuthClient

A final readonly PHP service in App\Services\Github\ (kendo) that owns the GitHub OAuth handshake. Two methods: getAuthorizationUrl(string $state) and exchangeCodeForToken(string $code). Constructor depends on the kendo OAuth client credentials (#[Config('github.client_id')], client_secret, redirect_uri, scopes) and HttpFactory. Does not own user tokens or the GitHub API surface — that lives in GithubApiClient. See GitHub Integration Split.

GithubApiClient

A final readonly PHP service in App\Services\Github\ (kendo) that owns kendo's user-perspective GitHub REST API calls (repos, branches, file content, code search, branch creation, authenticated-user profile). Bearer-token-parametrized: every method takes string $token as its first argument. Caller-agnostic — accepts both user OAuth tokens and GitHub App installation tokens, because GitHub's REST API treats both identically at the bearer-token boundary. Constructor depends only on HttpFactory. The interface separation from GithubOAuthClient and GithubAppService makes credential acquisition explicit at every call site. See GitHub Integration Split.

Audit & Compliance

Hash Chain

A tamper-detection mechanism used in audit logs. Each log entry's hash includes the previous entry's hash, creating a chain. If any entry is modified or deleted, the chain breaks and the tampering is detectable.

Point-in-Time Snapshot

Audit log entries capture the actor's name, email, and role at the time of the action — not via a foreign key join. This ensures the audit trail remains accurate even if the user's profile changes later.

Append-Only Table

An audit log table that only supports INSERT. No UPDATE, no DELETE. Records are immutable once written.

ActorType

An enum that identifies who performed an action: User, Scheduler, Cli, or GitHubWebhook. Stored as an integer in the database.

RequestContext

A DTO that captures forensic metadata: IP address, user agent, and request URL. Built from the HTTP request and passed explicitly to Actions for audit logging.

ISO 27001

An international standard for information security management. The Kendo project operates under this certification, which requires audit trails, access controls, and data protection measures.

Authorization

Model-Based Permission

An authorization check that depends only on the user and the target resource. Enforced at the route level via Laravel's ->can() middleware. Example: "Can this user update this project?"

Interaction-Based Permission

An authorization check that requires runtime context beyond route bindings — like which role is being assigned. Enforced inside the Action via Gate::authorize(). Example: "Can this manager assign the admin role to this user?" See Two-Tier Authorization.

Multi-Tenancy

Tenant

A company that uses the application. Each tenant gets their own database for hard data isolation. See Multi-Tenancy.

Central Database

A thin registry database containing only tenant and domain records. All application data lives in tenant databases.

TenantManager

A singleton service that resolves the current tenant from the subdomain and switches the database connection at runtime.

Projects

Kendo

A project management application built with Laravel 12 + Vue 3. Operates under ISO 27001 certification. Uses MySQL.

Brick Inventory (BIO)

A LEGO inventory management system built with Laravel 12 + Vue 3. Consists of a backend (lego-storage) and frontend (lego-storage-frontend). Uses PostgreSQL.