PopHops / Architecture

Clean architecture.Predictable results.

Builder and mobile stay independent. Shared API rules keep their data consistent.

03 / Architecture

Shared rules. Stable experiences.

Put shared rules where every client can rely on them.

The builder and mobile app are separate presentation layers. They meet at a shared API, where access, validation, and publication rules belong. Data and published versions sit beneath that boundary. Keeping those responsibilities separate lets each interface evolve without rebuilding the product rules. Stable published passes are one consequence of that structure.

Explicit data contracts.

Builder and mobile screens need different slices of related data. The include layer translates requested relations into approved eager loads and applies model-specific constraints at the query boundary.

Stable published content.

Drafts can change while an owned pass stays tied to a published version. Treating publication as a deliberate transition keeps editing separate from the experience already obtained by a visitor.

PHP / Laravel: Declarative eager-loading with per-relation constraints

Declarative eager-loading with per-relation constraints

The sample parses an include request, checks it against allowed relations, and resolves a named constraint. It shows how that rule can stay centralized as more screens request related content.

This is one part of the data boundary. Tenant scoping, authorization, and published-version rules must still be enforced by the surrounding API.

Adapted from the API include layer used to keep eager-loading and relation constraints readable at the query boundary. This excerpt omits surrounding application code.

PHP / LaravelCurated sample

<?php

final class IncludeManager
{
    public static function apply(Builder $query, array $requested, array $allowed): Builder
    {
        $with = [];

        foreach ($requested as $path) {
            $directive = self::parseDirective($path);

            if ($directive === null || ! array_key_exists($directive->relation, $allowed)) {
                continue;
            }

            $config = is_array($allowed[$directive->relation]) ? $allowed[$directive->relation] : [];

            $with[$directive->relation] = self::buildEagerLoad($directive, $config);
        }

        return $with === [] ? $query : $query->with($with);
    }

    private static function parseDirective(string $path): ?IncludeDirective
    {
        [$relation, $constraint] = array_pad(explode(':', trim($path), 2), 2, null);

        if ($relation === '') {
            return null;
        }

        return new IncludeDirective($relation, $constraint);
    }

    private static function buildEagerLoad(IncludeDirective $directive, array $config): string|Closure
    {
        if ($directive->constraint === null) {
            return $directive->relation;
        }

        $constraints = self::constraintsFor($config);

        return static function (Builder $relationQuery) use ($directive, $constraints): void {
            $handler = $constraints[$directive->constraint] ?? null;

            if (! is_callable($handler)) {
                return;
            }

            $handler($relationQuery);
        };
    }

    private static function constraintsFor(array $config): array
    {
        $constraints = $config['constraints'] ?? [];

        return is_array($constraints) ? $constraints : [];
    }
}

final readonly class IncludeDirective
{
    public function __construct(
        public string $relation,
        public ?string $constraint,
    ) {
    }
}