Loreax — Backend Technical Design Document#

Version: 0.1 (MVP Design) Status: Draft for implementation Last updated: April 2026 Audience: Engineering, Product, DevOps, Security

Table of Contents#

1. Executive Summary
2. Tech Stack
3. Architectural Standards & Conventions
4. Domain Map
5. Domain: Infrastructure
6. Domain: Identity
7. Domain: Ledger & Wallet
8. Domain: Payments
9. Domain: Content
10. Domain: Access & Entitlements
11. Domain: Monetization
12. Domain: Social Graph
13. Domain: Fan Club
14. Domain: Discovery & Ranking
15. Domain: Promotions
16. Domain: Notifications
17. Domain: Moderation
18. Domain: Admin & Back Office
19. Cross-Cutting: Observability
20. Cross-Cutting: Jobs, Scheduling & Events
21. Cross-Cutting: Security & Compliance
22. Cross-Cutting: Testing Strategy
23. Cross-Cutting: Deployment & Operations
24. Cross-Cutting: Documentation
25. Appendices

1. Executive Summary#

Loreax is a content platform where creators publish exclusive content (video, audio, images, text, links, polls, livestreams) and monetize via three combinable access paths: tier subscriptions, one-off purchases, and free-for-active-fans allowances. The platform handles real money end-to-end — top-ups, purchases, creator earnings, and MPESA-denominated withdrawals — through a double-entry ledger.

This document is the canonical technical design for the MVP backend. It specifies the domain-driven decomposition, entity model, contracts, endpoints, and implementation conventions that all engineers and code-generation agents must follow.

1.1 Product Pillars#

1. Creator monetization — flexible access rules per post, tier subscriptions, promotions, and fast MPESA payouts.
2. Viewer experience — discover, purchase, subscribe, save, follow, and join fan clubs with minimal friction.
3. Back-office control — Filament-powered admin with fine-grained scopes, audit trails, and configurable platform policies.
4. Real-money integrity — every cent traceable via an immutable double-entry ledger.
5. Observability by default — every request, job, and state change logged with correlation IDs.

1.2 Non-Goals (v1)#

• Native mobile apps (web + PWA only — mobile designs inform API shape)
• Tips/donations (deferred to v2)
• PayPal & bank payouts (MPESA only in v1)
• Explicit content capability (SFW by default; capability stubbed behind config flag)
• AI pre-screen and manual pre-screen moderation modes (stubbed; default is reactive_only)
• Elasticsearch / Meilisearch (custom DiscoveryService for v1)
• Multi-tenant organizations / agencies
• Internationalized content (English only; i18n infrastructure scaffolded)

1.3 Success Criteria#

2. Tech Stack#

2.1 Runtime & Language#

• PHP 8.4+ — declare(strict_types=1) on every file, final class by default. Projects are free to use PHP 8.4 language features (property hooks, asymmetric visibility, #[\Override], array_find/array_any/array_all) where they clarify intent.
• Laravel 12.x — framework (PHP 8.4 compatible)
• Composer 2.x — dependency management

2.2 Core Laravel Packages#

2.3 Data Stores#

2.4 External Services#

2.5 Infrastructure#

• AWS EC2 — self-managed, Nginx + PHP-FPM
• Ansible — idempotent server provisioning (deploy/ansible/)
• Docker — parallel container setup (Dockerfile, docker-compose.yml, docker-compose.prod.yml)
• GitHub Actions — CI (lint, static analysis, tests, coverage) + CD (build → push → deploy)
• CloudWatch — infra metrics, log aggregation
• Route 53 — DNS
• ACM — TLS certificates

2.6 Tooling#

3. Architectural Standards & Conventions#

3.1 Domain-Driven Monolith#

Loreax is a modular monolith organized by bounded context, not by technical layer. Each domain owns its entities, actions, policies, events, and API contracts. Domains communicate via:

1. Direct method calls through well-defined I* contracts (preferred for synchronous read operations).
2. Domain events (App\Domain\*\Events\*) dispatched via Laravel's event bus (for decoupled side effects).
3. Queued jobs for long-running or cross-cutting work.

No domain reaches directly into another domain's Eloquent models except through published contracts or events. Violations fail code review.

3.2 Directory Layout#

app/
├── Core/                          ← Cross-cutting infrastructure & contracts
│   ├── Contracts/                 ← I*-prefixed interfaces (IRequestLogger, IIdentityService, ...)
│   ├── Infrastructure/
│   │   ├── Logging/               ← MongoRequestLogger and siblings
│   │   ├── Storage/               ← Filesystem providers
│   │   ├── Media/                 ← Video/Audio/Image provider adapters
│   │   └── Payments/              ← Kashier-backed payment adapter
│   ├── Http/
│   │   ├── Middleware/            ← AssignRequestId, AssignTraceId, AssignConversationId, LogRequest, ResolveRealm, ...
│   │   ├── Responses/             ← Standardized API response shapes
│   │   └── Formatters/            ← camelCase ↔ snake_case translators
│   ├── Authorization/
│   │   ├── Scopes.php             ← Typed scope constants
│   │   ├── ScopeRegistry.php      ← Boot-time validator
│   │   └── PermissionGate.php
│   ├── Support/                   ← Shared helpers, enums, value objects
│   └── Exceptions/                ← Platform-wide exception hierarchy
│
├── Identity/                      ← Domain
│   ├── Contracts/                 ← IIdentityService, IMfaProvider, ...
│   ├── Models/                    ← User, AdminUser, Session, MfaChallenge, ...
│   ├── Actions/                   ← RegisterUserAction, LoginAction, EnableMfaAction, ...
│   ├── Enums/                     ← Realm, MfaProvider, ...
│   ├── Events/                    ← UserRegistered, LoginSucceeded, MfaChallenged, ...
│   ├── Listeners/
│   ├── Policies/
│   ├── Data/                      ← DTOs (RegisterUserData, LoginData, ...)
│   ├── Http/
│   │   ├── Controllers/
│   │   ├── Requests/
│   │   └── Resources/
│   └── Services/                  ← IdentityService implementation
│
├── Ledger/                        ← Domain
├── Payments/                      ← Domain
├── Content/                       ← Domain
├── Access/                        ← Domain
├── Monetization/                  ← Domain
├── Social/                        ← Domain
├── FanClub/                       ← Domain
├── Discovery/                     ← Domain
├── Promotions/                    ← Domain
├── Notifications/                 ← Domain
├── Moderation/                    ← Domain
└── AdminBackoffice/               ← Filament resources, custom admin actions

3.3 Naming Conventions#

Payload translation: API payloads are camelCase; internal DB columns are snake_case. The translation happens in:

• Incoming: FormRequest::validated() returns camelCase → DTO (spatie/laravel-data with #[MapInputName] attributes converts to snake_case where needed) → Action.
• Outgoing: Eloquent model → JsonResource transformer returns camelCase payload.

A CamelCaseResource base class and SnakeCaseRequest trait centralize this.

3.4 Thin Controllers, Laravel Actions#

Controllers are I/O adapters, nothing more. Every controller method:

1. Receives a FormRequest (validation + authorization).
2. Builds a DTO from validated input.
3. Dispatches a single Action::run(...).
4. Wraps the result in a JsonResource.
5. Returns the HTTP response.

No business logic in controllers. No direct Eloquent in controllers. No domain events dispatched in controllers.

<?php

declare(strict_types=1);

namespace App\Identity\Http\Controllers;

use App\Core\Http\Controllers\Controller;
use App\Identity\Actions\RegisterUserAction;
use App\Identity\Data\RegisterUserData;
use App\Identity\Http\Requests\RegisterUserRequest;
use App\Identity\Http\Resources\UserResource;
use Illuminate\Http\JsonResponse;
use OpenApi\Attributes as OA;

final class RegisterUserController extends Controller
{
    public function __construct(
        private readonly RegisterUserAction $registerUser,
    ) {}

    #[OA\Post(
        path: '/v1/identity/register',
        summary: 'Register a new user account',
        tags: ['Identity'],
        requestBody: new OA\RequestBody(
            required: true,
            content: new OA\JsonContent(ref: '#/components/schemas/RegisterUserRequest'),
        ),
        responses: [
            new OA\Response(response: 201, description: 'Created', content: new OA\JsonContent(ref: '#/components/schemas/UserResponse')),
            new OA\Response(response: 422, description: 'Validation error'),
        ],
    )]
    public function __invoke(RegisterUserRequest $request): JsonResponse
    {
        $data = RegisterUserData::from($request->validated());

        $user = $this->registerUser->run($data);

        return UserResource::make($user)
            ->response()
            ->setStatusCode(201);
    }
}

3.5 Actions Contract#

Every action follows this shape:

<?php

declare(strict_types=1);

namespace App\Identity\Actions;

use App\Identity\Data\RegisterUserData;
use App\Identity\Events\UserRegistered;
use App\Identity\Models\User;
use Illuminate\Support\Facades\DB;
use Lorisleiva\Actions\Concerns\AsAction;

final class RegisterUserAction
{
    use AsAction;

    /**
     * Register a new user account.
     *
     * Preconditions:
     *  - Email is not already registered (verified or unverified)
     *  - Handle is available and valid
     *
     * Postconditions:
     *  - User row created with hashed password
     *  - Email verification sent
     *  - UserRegistered event dispatched
     *  - Referral attribution applied if referral cookie present
     *
     * @throws \App\Identity\Exceptions\EmailAlreadyRegisteredException
     * @throws \App\Identity\Exceptions\HandleUnavailableException
     */
    public function run(RegisterUserData $data): User
    {
        return DB::transaction(function () use ($data): User {
            // ... implementation
            $user = User::create([...]);

            UserRegistered::dispatch($user);

            return $user;
        });
    }
}

Rules:

• One action = one use case. No multi-purpose actions.
• Actions return domain models, not responses.
• Actions throw domain exceptions; controllers/exception handlers translate to HTTP.
• Side effects (events, jobs) are dispatched inside the action's transaction via DB::afterCommit() where appropriate.
• Actions are testable in isolation (no HTTP layer needed).

3.6 Eloquent Usage#

• No repository pattern. Eloquent is the data-access primitive.
• Global scopes for universally applied filters (e.g. SoftDeletingScope, platform TenantScope when multi-tenant lands).
• Local scopes for reusable query fragments:

public function scopePublished(Builder $query): Builder
{
    return $query->where('status', PostStatus::Published);
}

public function scopeVisibleTo(Builder $query, User $viewer): Builder
{
    return $query->whereHas('accessRules', fn ($q) => $q->visibleTo($viewer));
}

• Model events via observers, not closures in boot().
• Strict mode enabled in AppServiceProvider::boot():

Model::shouldBeStrict(! app()->environment('prod'));

3.7 DTOs & Validation#

• Request validation: FormRequest classes in App\<Domain>\Http\Requests\*.
• DTOs: spatie/laravel-data classes in App\<Domain>\Data\*.
• One DTO per logical input/output shape.
• DTOs carry typed properties and can be rehydrated from array/JSON.

<?php

declare(strict_types=1);

namespace App\Identity\Data;

use Spatie\LaravelData\Attributes\MapInputName;
use Spatie\LaravelData\Attributes\Validation\Email;
use Spatie\LaravelData\Attributes\Validation\Max;
use Spatie\LaravelData\Data;
use Spatie\LaravelData\Mappers\SnakeCaseMapper;

final class RegisterUserData extends Data
{
    public function __construct(
        #[Email, Max(255)]
        public string $email,

        #[Max(72)]
        public string $password,

        #[Max(64)]
        public string $firstName,

        #[Max(64)]
        public string $lastName,

        #[Max(32)]
        public string $handle,

        public ?string $referralCode = null,
    ) {}
}

3.8 API Response Contract#

The response shape is derived from HTTP status code, not a payload flag. Three shapes exist.

A. Success (2xx status codes) — normal state or resource payload

{
  "message": "Created",
  "data": { ... },
  "meta": {
    "requestId": "01HQ...",
    "traceId": "0af7651916cd43dd8448eb211c80319c",
    "timestamp": "2026-04-20T14:05:00Z"
  }
}

message is a short human-readable summary appropriate for UI toasts. Defaults to the HTTP reason phrase ("OK", "Created", "Accepted") when not set explicitly.

B. Validation Error (422 Unprocessable Entity) — input validation failed

{
  "message": "Invalid input",
  "errors": {
    "email": ["The email field is required."],
    "amount": ["Must be a positive integer."]
  },
  "meta": {
    "requestId": "01HQ...",
    "traceId": "0af7651916cd43dd8448eb211c80319c",
    "timestamp": "2026-04-20T14:05:00Z"
  }
}

Always emitted by ValidationException (Laravel's default). The errors object maps field paths (camelCase, matching request input) to arrays of translated messages.

C. Application Error (430 Loreax Application Error + other non-validation 4xx/5xx) — business rule violation or infrastructure failure

{
  "errorCode": "INSUFFICIENT_FUNDS",
  "message": "Wallet balance is lower than the requested withdrawal amount.",
  "meta": {
    "requestId": "01HQ...",
    "traceId": "0af7651916cd43dd8448eb211c80319c",
    "timestamp": "2026-04-20T14:05:00Z"
  }
}

• errorCode is a stable SCREAMING_SNAKE_CASE identifier suitable for client-side switch statements. The catalog lives in App\Core\Exceptions\ErrorCode enum; every domain exception exposes an ErrorCode case.
• message is a human-readable, user-safe explanation (never contains stack traces or internal system detail).

Status code → response shape:

Why 430? Distinct from 422 ("your payload was malformed") and 409 ("stateful conflict") to give clients a predictable switch on "your payload was valid and parsed, but a business rule says no." 430 is an application-space status code in the 4xx range, treated as a client-addressable error by standard HTTP libraries while signaling that the response carries a stable errorCode the client branches on. The distinction lets front-ends render field-level feedback (422) versus toast-level error messaging (430) without string-sniffing.

Meta fields:

conversationId (multi-request correlation for long user journeys) remains captured internally via X-Conversation-ID header and included in RequestLog entries, but is not included in the response meta — it is a server-side observability field only.

3.9 Immutable, Idempotent Writes#

Every mutating endpoint accepts an optional Idempotency-Key header. Payment-related endpoints (/v1/top-ups, /v1/withdrawals, /v1/purchases) require it. The key + user + endpoint is stored in Redis with a 24h TTL; replays return the cached response.

3.10 Pagination#

All list endpoints return cursor-based pagination:

{
  "data": [...],
  "meta": {
    "cursor": { "next": "...", "prev": "..." },
    "perPage": 20
  }
}

Cursor encodes (sort_column, id) tuples, base64-URL-encoded.

3.11 Filament Back Office#

• Separate guard: admin
• Separate login route: /admin/login
• Every Filament resource declares its required scope:

protected static ?Scope $requiredScope = Scope::PostReadWrite;

• Destructive actions require a reason field; two-person approval on Withdrawal.Approval, Refund.Approval, Ledger.Approval.

3.12 Documentation Standards#

• PHPDoc on every public method — purpose, preconditions, postconditions, thrown exceptions.
• OpenAPI attributes on every public controller method (uses zircote/swagger-php).
• Domain README in every app/<Domain>/README.md — purpose, owned entities, key invariants, external dependencies.
• ADRs (Architecture Decision Records) in docs/adr/ for significant architectural choices.

4. Domain Map#

┌─────────────────────────────────────────────────────────────────┐
│                      Infrastructure (Core)                       │
│  Response envelopes • Middleware • Logging • Errors • Scopes     │
└─────────────────────────────────────────────────────────────────┘
                                │
                ┌───────────────┼───────────────┐
                ▼               ▼               ▼
         ┌──────────┐    ┌──────────┐    ┌──────────────┐
         │ Identity │    │ Ledger & │    │ Observability│
         │          │    │ Wallet   │    │ (cross-cut)  │
         └────┬─────┘    └─────┬────┘    └──────────────┘
              │                │
              ├────┬───────────┼───────────┬────────┐
              ▼    ▼           ▼           ▼        ▼
         ┌──────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌──────────┐
         │Social│ │Content │ │Payments│ │Admin │ │Moderation│
         └──┬───┘ └───┬────┘ └────────┘ └──────┘ └──────────┘
            │        │
            ▼        ▼
       ┌────────┐ ┌────────────┐
       │FanClub │ │ Access &   │
       │        │ │Entitlements│
       └────────┘ └──────┬─────┘
                         │
                         ▼
                  ┌──────────────┐    ┌──────────┐
                  │Monetization  │───▶│Promotions│
                  │(tiers, price)│    └──────────┘
                  └──────┬───────┘
                         │
                         ▼
                   ┌───────────┐
                   │ Discovery │
                   │ & Ranking │
                   └───────────┘
                         │
                         ▼
                  ┌──────────────┐
                  │Notifications │
                  └──────────────┘

Dependency rules:

1. Infrastructure (Core) depends on nothing in the domain layer.
2. Identity, Ledger, and Observability are foundational — depended upon by most domains.
3. Content & Access have a tight mutual relationship — Access rules are a property of a Post but live in their own domain for reuse.
4. Discovery reads from every domain but writes only to its own tables (caches + interactions).
5. Notifications is the terminal sink — receives events from every domain, emits nothing.

5. Domain: Infrastructure#

5.1 Responsibility#

Infrastructure defines the shape of the system before any business domain exists:

• Standard response envelope & error contract
• Standard middleware pipeline
• Request correlation (requestId, conversationId)
• Authentication guards & realm resolution
• Rate limiting
• Exception translation (domain → HTTP)
• CamelCase ↔ snake_case translation
• Scope dictionary & permission gate registration
• Health checks & readiness probes
• Feature flags
• Platform settings (runtime-tunable config)

This domain has no Eloquent models of its own other than PlatformSetting and FeatureFlag.

5.2 Middleware Pipeline#

In order (outermost first):

1. TrustProxies — AWS ELB forwarding
2. AssignRequestId — generate ULID if X-Request-ID absent; attach to $request->attributes as request_id
3. AssignTraceId — parse traceparent header (W3C Trace Context); if absent, generate W3C-compliant trace-id (32 hex chars) + span-id (16 hex chars); attach to $request->attributes as trace_id / span_id; set outbound traceparent header on response
4. AssignConversationId — X-Conversation-ID header or fall back to requestId (internal only; not emitted in response meta)
5. ResolveClientContext — capture X-Platform, X-Scenario, X-App-Version headers
6. HandleCors
7. ForceHttps (prod only)
8. ResolveRealm — set realm attribute based on matched route group (user or admin)
9. RateLimit — tiered limiter per route group
10. Authentication guard — auth:sanctum (user) or auth:admin (Filament)
11. VerifyEmailIfRequired — enforce email verification on write endpoints
12. EnforceMfaChallenge — challenge MFA for sensitive endpoints
13. CaptureProcessorName — route-matched Action FQCN attached to request
14. TranslateCamelToSnake — inbound payload normalization
15. Controller
16. TranslateSnakeToCamel — outbound payload normalization (via JsonResource)
17. LogRequest (terminable) — persists to MongoDB via IRequestLogger

5.3 Standard Response Envelope#

All responses pass through ApiResponse:

<?php

declare(strict_types=1);

namespace App\Core\Http\Responses;

use Illuminate\Contracts\Support\Responsable;
use Illuminate\Http\JsonResponse;
use Symfony\Component\HttpFoundation\Response as HttpStatus;

final class ApiResponse implements Responsable
{
    private function __construct(
        private readonly int $status,
        private readonly ?string $message = null,
        private readonly mixed $data = null,
        private readonly ?string $errorCode = null,
        private readonly ?array $validationErrors = null,
    ) {}

    // ─── Success ─────────────────────────────────────────────────────
    public static function ok(mixed $data = null, ?string $message = 'OK'): self
    {
        return new self(status: 200, message: $message, data: $data);
    }

    public static function created(mixed $data, ?string $message = 'Created'): self
    {
        return new self(status: 201, message: $message, data: $data);
    }

    public static function accepted(mixed $data = null, ?string $message = 'Accepted'): self
    {
        return new self(status: 202, message: $message, data: $data);
    }

    public static function noContent(): self
    {
        return new self(status: 204);
    }

    // ─── Validation Error (shape B) ──────────────────────────────────
    public static function validationError(array $errors, string $message = 'Invalid input'): self
    {
        return new self(status: 422, message: $message, validationErrors: $errors);
    }

    // ─── Application Error (shape C) ─────────────────────────────────
    public static function applicationError(string $errorCode, string $message): self
    {
        return new self(status: 430, message: $message, errorCode: $errorCode);
    }

    /** Generic non-422 error (401, 403, 404, 409, 429, 500, 502, 503). */
    public static function error(int $status, string $errorCode, string $message): self
    {
        return new self(status: $status, message: $message, errorCode: $errorCode);
    }

    public function toResponse($request): JsonResponse
    {
        if ($this->status === HttpStatus::HTTP_NO_CONTENT) {
            return response()->json(null, 204);
        }

        $meta = [
            'requestId' => (string) $request->attributes->get('request_id'),
            'traceId'   => (string) $request->attributes->get('trace_id'),
            'timestamp' => now()->toIso8601String(),
        ];

        $body = match (true) {
            $this->validationErrors !== null => [
                'message' => $this->message,
                'errors'  => $this->validationErrors,
                'meta'    => $meta,
            ],
            $this->errorCode !== null => [
                'errorCode' => $this->errorCode,
                'message'   => $this->message,
                'meta'      => $meta,
            ],
            default => [
                'message' => $this->message,
                'data'    => $this->data,
                'meta'    => $meta,
            ],
        };

        return response()->json($body, $this->status);
    }
}

5.4 Exception Handler#

App\Core\Exceptions\Handler translates exceptions into the response shapes from §3.8:

• ValidationException → shape B (422), with errors extracted from the validator
• AuthenticationException, AuthorizationException, ModelNotFoundException, ThrottleRequestsException, generic HTTP exceptions → shape C with standard status + stable errorCode
• DomainException subclasses → shape C with status 430 by default (overrideable) and errorCode from the attached ErrorCode case
• Unhandled \Throwable → shape C (500) with errorCode=INTERNAL_ERROR; message scrubbed to generic text in prod

Base domain exception:

<?php

declare(strict_types=1);

namespace App\Core\Exceptions;

abstract class DomainException extends \Exception
{
    abstract public function errorCode(): ErrorCode;

    /** Default: business rule violation → 430. Override for infra/other. */
    public function httpStatus(): int
    {
        return 430;
    }
}

ErrorCode enum (full catalog grows per domain; extract):

<?php

declare(strict_types=1);

namespace App\Core\Exceptions;

enum ErrorCode: string
{
    case Unauthenticated             = 'UNAUTHENTICATED';
    case InsufficientScope           = 'INSUFFICIENT_SCOPE';
    case NotFound                    = 'NOT_FOUND';
    case RateLimited                 = 'RATE_LIMITED';
    case IdempotencyConflict         = 'IDEMPOTENCY_CONFLICT';
    case InsufficientFunds           = 'INSUFFICIENT_FUNDS';
    case PostAlreadyPurchased        = 'POST_ALREADY_PURCHASED';
    case TierArchived                = 'TIER_ARCHIVED';
    case WithdrawalBelowMinimum      = 'WITHDRAWAL_BELOW_MINIMUM';
    case WithdrawalAboveDailyLimit   = 'WITHDRAWAL_ABOVE_DAILY_LIMIT';
    case MfaChallengeRequired        = 'MFA_CHALLENGE_REQUIRED';
    case MfaCodeInvalid              = 'MFA_CODE_INVALID';
    case HandleCooldownNotElapsed    = 'HANDLE_COOLDOWN_NOT_ELAPSED';
    case HandleUnavailable           = 'HANDLE_UNAVAILABLE';
    case EmailAlreadyRegistered      = 'EMAIL_ALREADY_REGISTERED';
    case PaymentProviderFailed       = 'PAYMENT_PROVIDER_FAILED';
    case LedgerIntegrityViolation    = 'LEDGER_INTEGRITY_VIOLATION';
    case InternalError               = 'INTERNAL_ERROR';
    // ... extended per domain; each new case PR updates this file + tests + API docs
}

Exception example:

<?php

declare(strict_types=1);

namespace App\Payments\Exceptions;

use App\Core\Exceptions\DomainException;
use App\Core\Exceptions\ErrorCode;

final class WithdrawalBelowMinimumException extends DomainException
{
    public function __construct(int $attemptedAmount, int $minimumAmount)
    {
        parent::__construct(sprintf(
            'Withdrawal of %d is below the minimum allowed (%d).',
            $attemptedAmount,
            $minimumAmount,
        ));
    }

    public function errorCode(): ErrorCode
    {
        return ErrorCode::WithdrawalBelowMinimum;
    }
}

Every domain exception must include a unit test asserting (a) the errorCode() returns the intended case and (b) a controller throwing it produces the expected 430 + shape C response.

5.5 Rate Limiting#

config/rate_limits.php:

return [
    'auth' => ['decayMinutes' => 1, 'max' => 10, 'by' => 'ip'],
    'payment' => ['decayMinutes' => 1, 'max' => 5, 'by' => 'user'],
    'write' => ['decayMinutes' => 1, 'max' => 60, 'by' => 'user'],
    'read' => ['decayMinutes' => 1, 'max' => 300, 'by' => 'user'],
    'public_read' => ['decayMinutes' => 1, 'max' => 60, 'by' => 'ip'],
    'admin' => ['decayMinutes' => 1, 'max' => 120, 'by' => 'admin'],
];

Applied via RateLimit::for('auth', fn ($req) => Limit::perMinute(10)->by($req->ip())) in RouteServiceProvider.

5.6 Platform Settings#

Runtime-tunable config keyed by dotted namespace:

platform_settings table:

Managed via Filament PlatformSetting resource (PlatformSetting.ReadWrite scope). Accessed in code via app(IPlatformSettings::class)->get('payment.platform_fee_rate') — cached in Redis with cache-tag invalidation on write.

Canonical keys (v1):

5.7 Feature Flags#

Separate from platform settings: binary toggles for in-progress features.

feature_flags table:

Accessed via app(IFeatureFlags::class)->enabled('livestream', $user).

5.8 Scope Dictionary#

Static, PHP enum–driven. The scope dictionary is a single backed string enum, which is the canonical source of truth for:

1. Application code (authorizeScope(Scope::LedgerRead))
2. The Filament admin UI (dropdowns, role editor)
3. The seeder that populates DB-backed roles (role_scopes stores the value)
4. Static analysis (custom Larastan rule forbids raw string literals matching .*\\.(Read|ReadWrite|Approval) outside the enum file)

<?php

declare(strict_types=1);

namespace App\Core\Authorization;

enum Scope: string
{
    // Identity
    case UserRead                       = 'User.Read';
    case UserReadWrite                  = 'User.ReadWrite';
    case AdminUserRead                  = 'AdminUser.Read';
    case AdminUserReadWrite             = 'AdminUser.ReadWrite';
    case RoleRead                       = 'Role.Read';

    // Creator lifecycle
    case CreatorRead                    = 'Creator.Read';
    case CreatorReadWrite               = 'Creator.ReadWrite';
    case CreatorApproval                = 'Creator.Approval';
    case VerificationRequestRead        = 'VerificationRequest.Read';
    case VerificationRequestReadWrite   = 'VerificationRequest.ReadWrite';
    case VerificationRequestApproval    = 'VerificationRequest.Approval';

    // Content
    case PostRead                       = 'Post.Read';
    case PostReadWrite                  = 'Post.ReadWrite';
    case PostApproval                   = 'Post.Approval';
    case CommentRead                    = 'Comment.Read';
    case CommentReadWrite               = 'Comment.ReadWrite';
    case CollectionRead                 = 'Collection.Read';
    case CollectionReadWrite            = 'Collection.ReadWrite';
    case TaxonomyRead                   = 'Taxonomy.Read';
    case TaxonomyReadWrite              = 'Taxonomy.ReadWrite';

    // Finance
    case LedgerRead                     = 'Ledger.Read';
    case LedgerReadWrite                = 'Ledger.ReadWrite';
    case LedgerApproval                 = 'Ledger.Approval';
    case WalletRead                     = 'Wallet.Read';
    case TopUpRead                      = 'TopUp.Read';
    case TopUpReadWrite                 = 'TopUp.ReadWrite';
    case WithdrawalRead                 = 'Withdrawal.Read';
    case WithdrawalReadWrite            = 'Withdrawal.ReadWrite';
    case WithdrawalApproval             = 'Withdrawal.Approval';
    case RefundRead                     = 'Refund.Read';
    case RefundReadWrite                = 'Refund.ReadWrite';
    case RefundApproval                 = 'Refund.Approval';

    // Monetization
    case TierRead                       = 'Tier.Read';
    case TierSubscriptionRead           = 'TierSubscription.Read';
    case PremiumSubscriptionRead        = 'PremiumSubscription.Read';
    case PremiumSubscriptionReadWrite   = 'PremiumSubscription.ReadWrite';

    // Moderation
    case ReportRead                     = 'Report.Read';
    case ReportReadWrite                = 'Report.ReadWrite';

    // Promotions
    case PromoCodeRead                  = 'PromoCode.Read';
    case PromoCodeReadWrite             = 'PromoCode.ReadWrite';
    case BoostedPostRead                = 'BoostedPost.Read';
    case BoostedPostReadWrite           = 'BoostedPost.ReadWrite';
    case BoostedPostApproval            = 'BoostedPost.Approval';
    case ReferralRead                   = 'Referral.Read';

    // Platform
    case PlatformSettingRead            = 'PlatformSetting.Read';
    case PlatformSettingReadWrite       = 'PlatformSetting.ReadWrite';
    case FeatureFlagRead                = 'FeatureFlag.Read';
    case FeatureFlagReadWrite           = 'FeatureFlag.ReadWrite';
    case NicheRead                      = 'Niche.Read';
    case NicheReadWrite                 = 'Niche.ReadWrite';
    case CategoryRead                   = 'Category.Read';
    case CategoryReadWrite              = 'Category.ReadWrite';
    case FanClubRead                    = 'FanClub.Read';
    case FanClubReadWrite               = 'FanClub.ReadWrite';

    // Observability & governance
    case AuditLogRead                   = 'AuditLog.Read';
    case RequestLogRead                 = 'RequestLog.Read';
    case ApprovalRequestRead            = 'ApprovalRequest.Read';
    case NotificationRead               = 'Notification.Read';
    case NotificationReadWrite          = 'Notification.ReadWrite';
    case SystemMaintenance              = 'System.Maintenance';

    /** Human-readable description surfaced in Filament role editor. */
    public function description(): string
    {
        return match ($this) {
            self::UserRead                     => 'View user accounts (non-PII scope)',
            self::UserReadWrite                => 'Edit user accounts, reset passwords, impersonate',
            self::CreatorApproval              => 'Grant/revoke notable verification',
            self::LedgerRead                   => 'View ledger transactions & entries',
            self::LedgerReadWrite              => 'Request manual adjustment',
            self::LedgerApproval               => 'Approve manual adjustments (two-person)',
            self::WithdrawalApproval           => 'Force-fail / manually settle withdrawals (two-person)',
            self::RefundApproval               => 'Approve refunds (two-person)',
            self::AdminUserReadWrite           => 'Create/edit admin users (Super Admin only)',
            self::SystemMaintenance            => 'Enter maintenance mode, emergency feature flag toggles',
            // ... exhaustive match arm per case, no default
        };
    }

    /** Grouping for UI / docs. */
    public function group(): ScopeGroup
    {
        return match (true) {
            str_starts_with($this->value, 'User.'),
            str_starts_with($this->value, 'AdminUser.'),
            str_starts_with($this->value, 'Role.')            => ScopeGroup::Identity,
            str_starts_with($this->value, 'Ledger.'),
            str_starts_with($this->value, 'Wallet.'),
            str_starts_with($this->value, 'TopUp.'),
            str_starts_with($this->value, 'Withdrawal.'),
            str_starts_with($this->value, 'Refund.')           => ScopeGroup::Finance,
            str_starts_with($this->value, 'Post.'),
            str_starts_with($this->value, 'Comment.'),
            str_starts_with($this->value, 'Collection.'),
            str_starts_with($this->value, 'Taxonomy.'),
            str_starts_with($this->value, 'Niche.'),
            str_starts_with($this->value, 'Category.')         => ScopeGroup::Content,
            str_starts_with($this->value, 'Report.')           => ScopeGroup::Moderation,
            str_starts_with($this->value, 'Creator.'),
            str_starts_with($this->value, 'VerificationRequest.'),
            str_starts_with($this->value, 'Tier.'),
            str_starts_with($this->value, 'PremiumSubscription.'),
            str_starts_with($this->value, 'PromoCode.'),
            str_starts_with($this->value, 'BoostedPost.'),
            str_starts_with($this->value, 'Referral.')         => ScopeGroup::Monetization,
            str_starts_with($this->value, 'AuditLog.'),
            str_starts_with($this->value, 'RequestLog.'),
            str_starts_with($this->value, 'ApprovalRequest.')  => ScopeGroup::Observability,
            default                                             => ScopeGroup::Platform,
        };
    }

    /** True for `.Approval`-suffixed scopes — must use `ApprovalRequest` workflow. */
    public function requiresDualApproval(): bool
    {
        return str_ends_with($this->value, '.Approval');
    }
}

Companion enum for UI grouping:

<?php

declare(strict_types=1);

namespace App\Core\Authorization;

enum ScopeGroup: string
{
    case Identity      = 'Identity';
    case Finance       = 'Finance';
    case Content       = 'Content';
    case Moderation    = 'Moderation';
    case Monetization  = 'Monetization';
    case Observability = 'Observability';
    case Platform      = 'Platform';
}

Usage:

// Authorize
$this->identity->authorizeScope(Scope::LedgerRead);

// Filament resource declaration
protected static ?Scope $requiredScope = Scope::PostReadWrite;

// Role seeding (role_scopes.scope column stores the string value)
Role::super_admin()->scopes()->sync(
    array_map(fn (Scope $s) => $s->value, Scope::cases())
);

// Two-person gate at runtime
if ($scope->requiresDualApproval()) {
    ApprovalRequest::open($approvable, $scope, $currentAdmin, $reason);
    return;
}

ScopeRegistry validates at boot:

1. Every enum case has a description arm (tested via ScopeRegistryTest::EveryCase_HasDescription).
2. Every role seeder references only existing enum cases (impossible to regress — enum typing).
3. DB role_scopes.scope rows all correspond to current enum values (any dangling row blocks deploy).

5.9 Health & Readiness#

Two endpoints:

• GET /health — liveness probe. Returns 200 if PHP is running. No DB check.
• GET /ready — readiness probe. Checks: PostgreSQL reachable, Redis reachable, MongoDB reachable, S3 reachable (HEAD on bucket), external payment provider reachable (cached 30s). Returns 200 only if all green.

5.10 Endpoints (Infrastructure-owned)#

6. Domain: Identity#

6.1 Responsibility#

Owns all authentication, authorization foundations, user account lifecycle, and realm resolution. Split across two realms:

• Realm user — end users (viewers and creators; the distinction is a status, not a table).
• Realm admin — Filament back-office administrators.

A Realm enum is the system-wide source of truth:

<?php

declare(strict_types=1);

namespace App\Identity\Enums;

enum Realm: string
{
    case User = 'user';
    case Admin = 'admin';
}

6.2 Entities#

6.2.1 users#

Indexes: email, handle, niche_id, is_creator, created_at, (is_creator, created_at) for creator directory.

6.2.2 admin_users#

No public signup. Provisioned via seeders (initial Super Admin) or Filament by existing Super Admin.

6.2.3 roles#

Seeded from config/roles.php. Managed via RoleSeeder — reseeding is idempotent and reverts manual drift.

6.2.4 role_scopes#

Unique on (role_id, scope). Seeded alongside roles.

6.2.5 admin_user_roles#

Unique on (admin_user_id, role_id). An admin can hold multiple roles; effective scopes = union.

6.2.6 social_accounts#

Unique on (provider, provider_user_id). One user may link multiple providers.

6.2.7 handle_history#

Queried during handle availability check: handle is unavailable if currently held by any user OR present in handle_history with released_at > now().

6.2.8 email_verifications#

6.2.9 password_reset_tokens#

Standard Laravel table, augmented with ip_address, user_agent, consumed_at.

6.2.10 mfa_challenges#

6.2.11 personal_access_tokens#

Standard Sanctum table. Augmented with device_name, last_used_ip, last_used_user_agent.

6.2.12 user_consents#

6.3 Relationships#

• User hasMany SocialAccounts
• User hasMany HandleHistory
• User hasMany UserConsents
• User hasOne Wallet (Ledger domain)
• User belongsTo Niche (Content domain)
• User hasMany Posts (Content domain — when is_creator=true)
• AdminUser belongsToMany Roles through admin_user_roles
• Role belongsToMany Scopes through role_scopes

6.4 Key Services & Actions#

IIdentityService (App\Identity\Contracts\IIdentityService)#

Single domain-facing surface. No code reaches into auth() directly.

<?php

declare(strict_types=1);

namespace App\Identity\Contracts;

use App\Identity\Enums\Realm;
use App\Identity\Models\AdminUser;
use App\Identity\Models\User;

interface IIdentityService
{
    public function currentUser(): ?User;
    public function currentAdmin(): ?AdminUser;
    public function currentRealm(): Realm;
    public function isAuthenticated(): bool;
    public function hasScope(string $scope): bool;

    /** Throws \App\Core\Exceptions\AuthorizationException if missing. */
    public function authorizeScope(string $scope): void;
}

Actions#

MFA Provider Interface#

<?php

declare(strict_types=1);

namespace App\Identity\Contracts;

use App\Identity\Models\MfaChallenge;

interface IMfaProvider
{
    public function identifier(): string; // 'totp' | 'otp_email' | ...

    /** Returns provider-specific setup payload (e.g. TOTP secret + QR). */
    public function initiate(mixed $challenger): array;

    /** Creates a challenge record and returns the challenge token. */
    public function challenge(mixed $challenger): MfaChallenge;

    /** Verifies the user-supplied code against the challenge. */
    public function verify(MfaChallenge $challenge, string $code): bool;
}

v1 implementations:

• TotpMfaProvider (active)
• EmailOtpMfaProvider (active)
• SmsOtpMfaProvider (stubbed; throws FeatureNotEnabledException)
• PasskeyMfaProvider (stubbed)

6.5 Social Login Flow#

1. GET /v1/identity/social/{provider}/redirect → returns provider authorization URL
2. User authorizes at provider
3. GET /v1/identity/social/{provider}/callback?code=...
4. LinkSocialAccountAction runs:
   • Exchanges code for provider user
   • If social_accounts row exists → log in that user
   • Else if user with same verified email exists → attach SocialAccount, log in, audit log
   • Else → create new user (social-only, password=null), dispatch UserRegistered event, log in
5. Issue Sanctum token + redirect to app

6.6 MFA Enforcement Logic#

Evaluated per-request by EnforceMfaChallenge middleware:

IF realm = admin                        → MFA required on every login session
IF realm = user:
    IF current endpoint is in SENSITIVE_ENDPOINTS (withdrawals, enable MFA, change password, delete account)
        → MFA challenge required this session
    IF user.lifetime_earnings_cents > 0 AND user.mfa_enabled = false
        → Block request with 403, error code `mfa_required_for_earnings`

SENSITIVE_ENDPOINTS is configurable in config/mfa.php.

6.7 Endpoints#

All under /v1/identity/* unless noted.

6.8 OpenAPI Example (Login)#

#[OA\Post(
    path: '/v1/identity/login',
    summary: 'Authenticate and receive access token',
    tags: ['Identity'],
    requestBody: new OA\RequestBody(
        required: true,
        content: new OA\JsonContent(
            required: ['email', 'password'],
            properties: [
                new OA\Property(property: 'email', type: 'string', format: 'email'),
                new OA\Property(property: 'password', type: 'string', format: 'password'),
                new OA\Property(property: 'deviceName', type: 'string', nullable: true),
            ],
        ),
    ),
    responses: [
        new OA\Response(response: 200, description: 'Authenticated', content: new OA\JsonContent(
            properties: [
                new OA\Property(property: 'message', type: 'string', example: 'OK'),
                new OA\Property(property: 'data', properties: [
                    new OA\Property(property: 'user', ref: '#/components/schemas/User'),
                    new OA\Property(property: 'accessToken', type: 'string'),
                    new OA\Property(property: 'mfaChallengeToken', type: 'string', nullable: true),
                ], type: 'object'),
                new OA\Property(property: 'meta', ref: '#/components/schemas/ResponseMeta'),
            ],
        )),
        new OA\Response(response: 401, description: 'Invalid credentials', content: new OA\JsonContent(ref: '#/components/schemas/ApplicationError')),
        new OA\Response(response: 422, description: 'Validation error', content: new OA\JsonContent(ref: '#/components/schemas/ValidationError')),
        new OA\Response(response: 429, description: 'Rate limited', content: new OA\JsonContent(ref: '#/components/schemas/ApplicationError')),
    ],
)]

7. Domain: Ledger & Wallet#

7.1 Responsibility#

The Ledger domain is the single source of truth for all money movement on the platform. Every cent that enters, moves within, or leaves the system is recorded as a balanced pair (or set) of ledger entries. This domain provides:

• Immutable, append-only double-entry ledger
• Per-user wallet (balance computed from ledger; denormalized for fast read)
• 3-day earnings hold (withdrawable-after semantics)
• Idempotent posting primitive
• Reconciliation job (nightly integrity check)
• Platform revenue accounting

Every other domain that moves money (Payments, Monetization, Promotions, Moderation/refunds) calls ILedgerService::post(). No direct wallet balance writes exist anywhere else in the codebase.

7.2 Entities#

7.2.1 ledger_accounts#

Represents a logical account. Balances are derived from entries.

Per-user accounts (created on user registration):

• user_wallet (spendable + settled earnings)
• user_pending_earnings (within 3-day hold)

Platform accounts (singletons, seeded):

• platform_revenue — where fees land
• platform_mpesa_float — represents money in the MPESA merchant account
• platform_mpesa_payouts — outgoing MPESA B2C float
• platform_processor_fees — MPESA transaction fees paid
• platform_marketing_expense — referral welcome credits, promotional give-backs
• platform_refund_liability — refund IOUs awaiting settlement

Unique constraint: (type, owner_type, owner_id, currency) where applicable.

7.2.2 ledger_transactions#

One row per business event. Each transaction has ≥2 entries that sum to zero.

Immutability: no updated_at. Corrections are new reversing transactions.

7.2.3 ledger_entries#

One row per account impact. Paired to balance each transaction.

Constraints:

• CHECK: amount_minor_units > 0
• CHECK: currency = (SELECT currency FROM ledger_accounts WHERE id = ledger_account_id)
• DB trigger on INSERT: forbids inserts that would cause SUM(signed_amount_minor_units) WHERE ledger_transaction_id = X to be non-zero. Enforced transactionally at commit.

Indexes: ledger_transaction_id, ledger_account_id, (ledger_account_id, created_at) for balance windows, withdrawable_after for release job.

7.2.4 wallets#

Denormalized projection for fast read. One row per user.

Maintained atomically alongside ledger writes in the same DB transaction.

Reconciliation job (nightly, ReconcileWalletsJob) recomputes each wallet from ledger_entries and logs any drift to WalletDriftIncident for admin review.

7.2.5 approval_requests#

Generic two-person-approval gate.

7.2.6 wallet_drift_incidents#

Written by reconciliation job when wallet.balance != SUM(ledger_entries). Surfaces in Filament, alerts ops.

7.3 Posting Rules Catalog#

The canonical set of double-entry postings. Every money movement matches exactly one rule.

Rule: top_up#

Viewer top-ups wallet via MPESA.

Net effect: platform's MPESA balance goes down (it owes the user now), user's wallet goes up.

Rule: post_purchase (paid via wallet)#

Viewer buys a post using their wallet.

Rule: post_purchase (paid via direct MPESA STK)#

Viewer buys a post with a fresh STK push (no wallet top-up step).

Rule: tier_subscription_payment#

Recurring tier charge.

Rule: earnings_release#

Nightly ReleaseEarningsJob sweeps pending entries with withdrawable_after <= now.

Rule: withdrawal#

Creator withdraws from wallet to MPESA.

Note: processor_fee reduces what the user ultimately receives. The full gross is debited from the user's wallet; the processor fee is shown as a transparent line item in the Withdrawal reference record.

Rule: withdrawal_failure_reversal#

MPESA B2C fails; funds return to user.

Rule: post_purchase_refund#

Admin issues refund for a past purchase.

If original purchase was via direct MPESA and platform needs to return via MPESA B2C, the CREDIT side goes to platform_refund_liability, and a subsequent withdrawal-style posting to platform_mpesa_payouts clears it.

Rule: referral_commission#

Referral attribution pays out a slice of referred user's spend.

Rule: welcome_credit#

New user referred through a referral link gets platform-funded credit.

Note: Welcome credits have a used_before expiration (30 days) enforced at spend-time via an accounting tag on the entry metadata. Unused credits are clawed back by a scheduled job that posts a reversing manual_adjustment.

Rule: premium_subscription_payment#

(No creator share — premium is platform revenue.)

Rule: manual_adjustment#

Admin-initiated, requires Ledger.Approval two-person gate, always writes an ApprovalRequest and a reason.

Entries are free-form but must balance. Used for reconciliation, compensation, correction.

7.4 Ledger Service#

<?php

declare(strict_types=1);

namespace App\Ledger\Contracts;

use App\Ledger\Data\LedgerPostingData;
use App\Ledger\Models\LedgerTransaction;

interface ILedgerService
{
    /**
     * Post a balanced transaction. All entries committed in a single DB transaction.
     * Idempotent on `idempotencyKey` — replays return the existing transaction.
     *
     * @throws \App\Ledger\Exceptions\UnbalancedLedgerException
     * @throws \App\Ledger\Exceptions\InsufficientFundsException
     * @throws \App\Ledger\Exceptions\CurrencyMismatchException
     */
    public function post(LedgerPostingData $posting): LedgerTransaction;

    public function availableBalance(int $userId, string $currency = 'KES'): int;
    public function pendingBalance(int $userId, string $currency = 'KES'): int;

    /** For reconciliation jobs only. */
    public function recomputeBalance(int $accountId): int;
}

LedgerPostingData DTO:

<?php

declare(strict_types=1);

namespace App\Ledger\Data;

use App\Ledger\Enums\LedgerPurpose;
use Spatie\LaravelData\Data;
use Spatie\LaravelData\DataCollection;

final class LedgerPostingData extends Data
{
    public function __construct(
        public LedgerPurpose $purpose,
        /** @var DataCollection<LedgerEntryData> */
        public DataCollection $entries,
        public ?string $idempotencyKey = null,
        public ?string $referenceType = null,
        public ?int $referenceId = null,
        public ?string $memo = null,
        public ?array $metadata = null,
        public ?string $platformFeeRateSnapshot = null,
        public ?int $postedByAdminId = null,
        public ?int $approvalRequestId = null,
    ) {}
}

final class LedgerEntryData extends Data
{
    public function __construct(
        public int $ledgerAccountId,
        public string $direction, // 'debit' | 'credit'
        public int $amountMinorUnits,
        public string $currency = 'KES',
        public ?\DateTimeImmutable $withdrawableAfter = null,
    ) {}
}

Example usage (inside PurchasePostAction):

$this->ledger->post(new LedgerPostingData(
    purpose: LedgerPurpose::PostPurchase,
    entries: LedgerEntryData::collect([
        ['ledgerAccountId' => $viewerWallet->id, 'direction' => 'debit', 'amountMinorUnits' => $grossCents],
        ['ledgerAccountId' => $platformRevenue->id, 'direction' => 'credit', 'amountMinorUnits' => $feeCents],
        ['ledgerAccountId' => $creatorPending->id, 'direction' => 'credit', 'amountMinorUnits' => $netCents, 'withdrawableAfter' => now()->addDays($holdDays)],
    ], DataCollection::class),
    idempotencyKey: $idempotencyKey,
    referenceType: 'post_purchase',
    referenceId: $postPurchase->id,
    memo: "Purchase of post {$post->public_id}",
    platformFeeRateSnapshot: (string) $feeRate,
));

7.5 Endpoints#

7.6 Invariants (enforced by tests and DB constraints)#

1. Zero-sum per transaction. SUM(signed_amount_minor_units) GROUP BY ledger_transaction_id = 0 for every transaction. Enforced via deferred DB trigger + unit tests.
2. Currency consistency. Every entry in a transaction shares the same currency. Enforced in application layer (enum + checks).
3. Wallet consistency. wallet.available_balance = SUM(signed_amount WHERE account=user_wallet AND user=X). Reconciled nightly.
4. Pending held. Entries in user_pending_earnings always have non-null withdrawable_after.
5. Immutability. No UPDATE or DELETE on ledger_transactions or ledger_entries. Enforced via DB privileges (app role has INSERT/SELECT only; DELETE requires a separate ledger_admin role not used at runtime).

8. Domain: Payments#

8.1 Responsibility#

Payments owns the external money movement — the bridge between the platform and MPESA (and, in v2, PayPal/Bank). It does not own the ledger; it calls ILedgerService::post() after successful external settlement.

Responsibilities:

• MPESA C2B (top-ups, direct post-purchase STK pushes)
• MPESA B2C (creator withdrawals)
• Payment method management (withdrawal destinations)
• Webhook/callback handling from the configured payment gateway via Kashier
• Polling & timeout for stuck payments
• Retry logic for failed B2C
• Refund execution path (coordinating with Ledger)

8.2 Entities#

8.2.1 payment_intents#

Represents a pending external money movement in either direction.

8.2.2 withdrawal_methods#

For MPESA: encrypted_details = {"phone": "254712345678"}, masked_display = "Phone ending in 678".

8.2.3 withdrawals#

8.2.4 top_ups#

8.3 Payment Provider Interface#

<?php

declare(strict_types=1);

namespace App\Payments\Contracts;

use App\Payments\Data\C2bStkRequestData;
use App\Payments\Data\C2bStkResponseData;
use App\Payments\Data\B2cRequestData;
use App\Payments\Data\B2cResponseData;
use App\Payments\Data\ProviderTransactionStatus;

interface IPaymentProvider
{
    public function identifier(): string;

    public function initiateC2bStk(C2bStkRequestData $data): C2bStkResponseData;

    public function initiateB2c(B2cRequestData $data): B2cResponseData;

    public function queryTransaction(string $providerTransactionId): ProviderTransactionStatus;

    public function verifyCallback(array $callbackPayload): bool;
}

Implementations:

• KashierPaymentProvider (v1 active)
• Stubs reserved for PaypalPaymentProvider, BankTransferPaymentProvider

8.4 Top-up Flow#

Client → POST /v1/payments/top-ups { amount, phoneNumber, idempotencyKey }
   ↓
InitiateTopUpAction
   ├── Validate amount (within min/max from platform_settings)
   ├── Check rate limit (5 top-ups per 5 min)
   ├── Create PaymentIntent (status=pending)
   ├── Create TopUp (status=pending)
   ├── IPaymentProvider::initiateC2bStk(...)
   │    └── Kashier SDK initiates the provider-side STK / collection request
   ├── PaymentIntent.provider_transaction_id = provider reference
   ├── Dispatch PollPaymentIntentStatusJob (delay=5s)
   └── Return PaymentIntent payload to client

PollPaymentIntentStatusJob (runs every 5s up to 120s):
   ├── IPaymentProvider::queryTransaction(provider reference)
   ├── IF status=success:
   │      └── SettleTopUpAction
   │           ├── LedgerService::post(top_up rule)
   │           ├── Update PaymentIntent.status=succeeded, TopUp.status=succeeded
   │           ├── Dispatch TopUpSucceeded event
   │           └── Send notification
   ├── IF status=failure:
   │      └── FailTopUpAction (PaymentIntent.status=failed, Notify user)
   └── ELSE re-queue self until timeout

MpesaCallbackController (if Safaricom calls us back first):
   ├── Verify callback signature
   ├── Lookup PaymentIntent by CheckoutRequestID
   ├── SettleTopUpAction (idempotent — if already settled, noop)
   └── 200 OK

Polling and callback are both wired; whichever arrives first settles the intent. Settlement itself is idempotent by payment_intent_id.

8.5 Post-Purchase Direct STK Flow#

Same primitives as top-up, but at settlement also writes the post_purchase ledger rule with the creator as the earning party. PurchasePostAction decides the payment source:

IF data.paymentMethod = 'wallet':
    check wallet.available_balance >= amount
    LedgerService::post(post_purchase via wallet)
    return PostPurchase

IF data.paymentMethod = 'mpesa_direct':
    InitiateTopUpAction-like flow BUT with purpose=post_purchase
    PaymentIntent carries reference to post_purchase intent
    Settlement runs the post_purchase rule (not top_up)

8.6 Withdrawal Flow#

Client → POST /v1/payments/withdrawals { amount, withdrawalMethodId, idempotencyKey }
   ↓
RequestWithdrawalAction
   ├── Enforce MFA challenge (middleware)
   ├── Validate amount within [min, max_per_txn]
   ├── Enforce daily limits (count + cumulative)
   ├── Lock wallet row (SELECT ... FOR UPDATE)
   ├── Check wallet.available_balance >= amount
   ├── Create PaymentIntent (direction=outbound, status=pending)
   ├── Create Withdrawal (status=queued)
   ├── Dispatch ProcessWithdrawalJob (queue=transactional)
   └── Return Withdrawal payload (status=queued)

ProcessWithdrawalJob:
   ├── Withdrawal.status=processing
   ├── IPaymentProvider::initiateB2c(...)
   ├── PaymentIntent.provider_transaction_id = ConversationID
   ├── Wait for callback OR poll (30s up to 5min) since B2C is slower
   ├── IF success:
   │      └── SettleWithdrawalAction
   │           ├── Record processor_fee (from callback)
   │           ├── LedgerService::post(withdrawal rule)
   │           ├── Update Withdrawal.status=succeeded, settled_at
   │           ├── Mark WithdrawalMethod.is_verified=true (if first success)
   │           └── Notify user
   └── IF failure:
          └── FailWithdrawalAction
              ├── LedgerService::post(withdrawal_failure_reversal rule)
              ├── Update Withdrawal.status=failed
              └── Notify user (+ Filament visibility)

All B2C callbacks are signed/verified. Failures surface in Filament under the Withdrawal resource with a Retry action (requires Withdrawal.ReadWrite; auto-completed retries don't require approval).

8.7 Endpoints#

8.8 Safety Rails#

• Row locking on wallet during withdrawal request prevents concurrent withdrawal of same balance.
• Rate limits: 5 top-ups per 5 min, 3 withdrawals per day (6 for premium), enforced by RateLimit middleware keyed by user.
• Minimum/maximum enforced per platform setting; configurable live.
• MFA challenge required before withdrawal endpoint is accepted.
• Idempotency key required on top-up, purchase, withdrawal endpoints.

9. Domain: Content#

9.1 Responsibility#

Content owns the lifecycle of creator-published material:

• Posts (seven formats: text, video, audio, image, link, poll, livestream)
• Media assets & transcoding pipeline
• Categorization taxonomy (Niche → Category → Tag)
• Collections (creator-curated groupings)
• Comments on posts
• Post state machine (draft → processing → published → hidden/removed)

Content does not own: access rules (see §10 Access & Entitlements), pricing (see §11 Monetization), or saved-posts/bookmarks (see §12 Social Graph).

9.2 Entities#

9.2.1 niches#

Seeded from config/taxonomy.php. Managed via Filament Niche resource.

9.2.2 categories#

Unique on (niche_id, slug).

9.2.3 tags#

9.2.4 taggables (polymorphic pivot)#

Unique on (tag_id, taggable_type, taggable_id).

9.2.5 posts#

Indexes: (creator_id, status, published_at), (status, published_at) for feeds, category_id, type.

9.2.6 post_media#

Represents media files attached to a post (a post can have multiple — e.g. image gallery).

9.2.7 livestreams#

9.2.8 livestream_viewer_pings#

Ephemeral — written to Redis as sorted sets with TTL, materialized to table only for post-stream analytics:

Unique on (livestream_id, user_id, minute_bucket).

9.2.9 livestream_chat_messages#

Also broadcast via Redis pubsub → SSE stream.

9.2.10 polls#

9.2.11 poll_options#

9.2.12 poll_votes#

Unique on (poll_id, user_id) when !is_multiple_choice; on (poll_option_id, user_id) always.

9.2.13 collections#

Unique on (creator_id, slug).

9.2.14 collection_posts#

Unique on (collection_id, post_id).

9.2.15 comments#

9.3 Post State Machine#

                ┌─────┐
        (save)  │draft│
       ◄────────┤     │
       │        └──┬──┘
       │           │ submit (may upload media)
       │           ▼
       │     ┌──────────┐
       │     │processing│── media failed ──► draft (with error)
       │     └────┬─────┘
       │          │ media ready AND moderation=reactive_only
       │          ▼
       │   ┌─────────────┐
       │   │  published  │── creator removes ──► removed_by_creator
       │   └──────┬──────┘
       │          │ admin takedown
       │          ▼
       │   ┌────────────────┐
       │   │hidden_by_admin │
       │   └────────────────┘
       │
       │          ┌──────────────┐
       │◄─────────┤pending_review│  (moderation=manual_prescreen)
                  └──────┬───────┘
                         │ approve
                         ▼
                     published

                  ┌────────────┐
                  │quarantined │  (AI auto-hide)
                  └──────┬─────┘
                         │ admin approve → published
                         │ admin confirm violation → hidden_by_admin

State transitions are methods on Post via a HasPostState trait, each fires a domain event.

9.4 Media Provider Interfaces#

<?php

declare(strict_types=1);

namespace App\Content\Contracts;

interface IVideoProvider
{
    public function identifier(): string;

    /** Upload and enqueue transcoding. Returns provider asset ID + polling contract. */
    public function uploadFromPath(string $localPath): VideoProviderAsset;

    /** Check transcoding status. */
    public function status(string $providerAssetId): VideoProviderStatus;

    /** Signed playback URLs (HLS, mp4 variants). */
    public function playbackUrls(string $providerAssetId, ?int $ttlSeconds = 300): array;

    public function delete(string $providerAssetId): void;
}

interface IAudioProvider { /* similar shape */ }
interface IImageProvider { /* resize + variant generation */ }
interface ILivestreamProvider
{
    public function createStream(array $options): LivestreamAsset;
    public function endStream(string $streamId): void;
    public function signedPlaybackUrl(string $streamId, int $ttlSeconds = 120): string;
    public function fetchRecording(string $streamId): ?string;
}

v1 default adapters (self-hosted):

• FFmpegLocalVideoProvider — transcodes to HLS via queued TranscodeVideoJob
• FFmpegLocalAudioProvider — normalizes to AAC
• InterventionImageProvider — resizes to thumb, small, medium, large preset variants
• MuxLivestreamProvider — livestream via Mux Live (the one provider that's external in v1 per Q12/Q13)

Env-driven: VIDEO_PROVIDER, AUDIO_PROVIDER, IMAGE_PROVIDER, LIVESTREAM_PROVIDER.

Package readiness note:

• spatie/laravel-medialibrary is already installed via Composer and available through Laravel package discovery, so Content-domain media models can begin integrating it without additional package bootstrap work.
• pbmedia/laravel-ffmpeg is already installed via Composer and available through Laravel package discovery; runtime binary paths are scaffolded in .env.example through FFMPEG_BINARY_PATH and FFPROBE_BINARY_PATH.
• bervant/laravel-sms is already installed via Composer and available through Laravel package discovery; project env documentation should use SMS_DRIVER, SMS_API_USERNAME, SMS_API_KEY, SMS_SHORTCODE, and the optional Twilio/Bonga/Envisage variables exposed by the package.
• bervant/kashier-laravel-sdk is already installed via Composer and available through Laravel package discovery; project env documentation should use KASHIER_ENABLED, KASHIER_URL, KASHIER_MERCHANT_KEY, KASHIER_MERCHANT_SECRET, KASHIER_SERVICE_ID, KASHIER_PAYBILL_NO, and KASHIER_PAYBILL_ACCOUNT.

9.5 Post Upload Flow (Video Example)#

Client → POST /v1/content/posts (body: type=video, title, metadata)
   ↓
CreatePostDraftAction
   ├── Create Post (status=draft, no media yet)
   ├── Generate signed upload URL for direct upload (S3 presigned)
   └── Return { post, uploadUrl, uploadFields }

Client → PUT uploadUrl (binary video bytes direct to S3)

Client → POST /v1/content/posts/{id}/media (registers uploaded file)
   ↓
AttachPostMediaAction
   ├── Validate file exists in S3
   ├── Create PostMedia (kind=video, status=pending)
   ├── Dispatch TranscodeVideoJob
   └── Update Post.status=processing, return Post

TranscodeVideoJob:
   ├── IVideoProvider::uploadFromPath(s3_path) → providerAssetId (v1 self-hosted: transcodes locally, writes HLS to S3)
   ├── Poll IVideoProvider::status()
   ├── When ready: update PostMedia.variants, status=ready
   ├── Mark Post.status=published (if moderation=reactive_only) or pending_review
   └── Dispatch PostPublished event

Client → POST /v1/content/posts/{id}/publish (finalizes: sets access rules, tags, category)
   ↓
PublishPostAction
   ├── Validate post is in publishable state
   ├── Attach tags (normalizes slugs, increments use_count)
   ├── Attach AccessRules (handled by Access domain — see §10)
   ├── If livestream: create Livestream + ingest
   └── Post.status=published, published_at=now

Note: publish is a separate step from create + attach media because content can be edited (access rules, tags, title) until published.

9.6 Polls#

Polls are a post type with an embedded Poll and PollOptions. Vote submission goes through:

POST /v1/content/posts/{id}/poll/vote { optionIds: [...] }
   ↓
SubmitPollVoteAction
   ├── Verify post type is 'poll', not closed
   ├── Verify user has access to post (Access domain)
   ├── Verify isMultipleChoice compliance
   ├── Upsert vote (idempotent — change vote allowed until close)
   ├── Update vote_counts atomically
   └── Return PollResults

9.7 Endpoints#

public* = access-gated read: post returns full content if user has access; a sanitized teaser (title, cover, price) otherwise.

10. Domain: Access & Entitlements#

10.1 Responsibility#

Access is the authoritative decision point for "Can user X view/interact with post Y?" It owns:

• AccessRule polymorphic model (per-post, per-collection access declarations)
• The three access rule types: tier_gated, one_off_purchase, free_for_active_fans, plus the implicit public_free
• PostPurchase records
• FanEngagementScore (computed)
• IAccessService — the single API other domains call to check access

Every read of a gated resource funnels through IAccessService::canView($user, $post). There is no other path.

10.2 Entities#

10.2.1 access_rules#

Multiple rules can exist per post (per Q1: combinable access models). Access is granted if any applicable rule grants it. The public_free rule is the lowest-privilege bypass (if present, everyone can view).

Globally toggling rule types via content.access_rules_enabled setting — if one_off_purchase is disabled platform-wide, those rules are ignored in access checks (and hidden in creator UI).

10.2.2 post_purchases#

Unique on (post_id, buyer_user_id) where status='completed'. A refunded purchase can be re-bought.

10.2.3 fan_engagement_scores#

Unique on (user_id, creator_id).

10.2.4 tier_subscriptions (lives in Monetization §11 but referenced here)#

IAccessService queries this to check "is user X currently subscribed to creator Y at level ≥ N."

10.3 Access Check Algorithm#

function canView(User viewer, Post post): bool {
    if viewer.id == post.creator_id:
        return true // own post

    if post.status != 'published':
        return false

    rules = post.access_rules.where(is_active=true)
    enabled_rule_types = PlatformSettings::get('content.access_rules_enabled')
    rules = rules.filter(r => r.rule_type in enabled_rule_types)

    for rule in rules:
        if rule.rule_type == 'public_free':
            return true

        if rule.rule_type == 'one_off_purchase':
            if PostPurchase::exists(post.id, viewer.id, status=completed):
                return true

        if rule.rule_type == 'tier_gated':
            sub = TierSubscription::activeFor(viewer.id, post.creator_id)
            if sub && sub.tier.level >= rule.min_tier_level:
                return true

        if rule.rule_type == 'free_for_active_fans':
            if FanStatusService::isActiveFan(viewer, post.creator):
                return true

    return false
}

Access checks are cached per (user, post) pair for 60 seconds in Redis. Invalidation triggered by: new purchase, tier sub change, engagement score recomputation.

10.4 Active Fan Status#

Weighted engagement score per (user, creator) pair. Computed by:

score = w_like × likes_last_30d
      + w_comment × comments_last_30d
      + w_share × shares_last_30d
      + w_save × saves_last_30d
      + w_purchase × purchase_count_last_30d
      + w_spend × (spend_cents_last_30d / 100)
      + w_tenure × min(tenure_days / 30, 12)  // caps at 1 year worth of tenure weight
      + w_recency × recency_factor(days_since_last_interaction)

Weights in discovery.active_fan_weights:

{
  "w_like": 1.0,
  "w_comment": 3.0,
  "w_share": 4.0,
  "w_save": 2.0,
  "w_purchase": 15.0,
  "w_spend": 0.5,
  "w_tenure": 2.0,
  "w_recency": 5.0
}

Threshold discovery.active_fan_threshold = 50.0 (default).

Tier subscribers auto-qualify — if TierSubscription::activeFor(user, creator) !== null, isActiveFan() returns true regardless of score.

Recomputation:

• Incremental: every interaction bumps the score for that (user, creator) pair (small update)
• Full: scheduled job RecomputeFanEngagementScoresJob runs every 4h for any pair with recent activity; nightly full rebuild for all active pairs

10.5 Service Contracts#

<?php

declare(strict_types=1);

namespace App\Access\Contracts;

use App\Content\Models\Post;
use App\Identity\Models\User;

interface IAccessService
{
    public function canView(User $viewer, Post $post): bool;
    public function canComment(User $viewer, Post $post): bool;
    public function canInteract(User $viewer, Post $post): bool; // like, share, save
    public function priceFor(User $viewer, Post $post): ?int; // null if free or already has access
    public function accessReason(User $viewer, Post $post): AccessReason; // enum explaining why granted/denied
}

interface IFanStatusService
{
    public function isActiveFan(User $viewer, User $creator): bool;
    public function score(User $viewer, User $creator): float;
    public function recompute(User $viewer, User $creator): FanEngagementScore;
}

10.6 Endpoints#

11. Domain: Monetization#

11.1 Responsibility#

Owns the creator-side revenue primitives:

• Tiers (ordered subscription levels, one active sub per user per creator)
• TierSubscriptions + renewals + grace period
• Premium (platform-side subscription with badge + perks)
• Earnings aggregation (materialized views)
• Fee calculation (delegates to config + platform_settings)

Does not own: ledger (§7), payment rails (§8), or promotions (§15).

11.2 Entities#

11.2.1 tiers#

Unique on (creator_id, level) where archived_at is null.

11.2.2 tier_subscriptions#

Unique partial: WHERE user_id = X AND creator_id = Y AND status IN ('active','past_due','grace_period') — at most one per (user, creator).

11.2.3 tier_subscription_payments#

One row per billing cycle.

11.2.4 premium_subscriptions#

Unique on user_id (at most one active).

11.2.5 verification_requests#

11.3 Subscription Lifecycle#

Create tier → Creator owns Tier
Subscribe → TierSubscription (status=active, first payment via payment_intent)
Monthly cron → BillActiveTierSubscriptionsJob (day of current_period_end)
   ├── Attempt charge (wallet preferred → mpesa_direct fallback with OTP)
   ├── IF success: extend current_period by 1 month, create TierSubscriptionPayment
   └── IF fail: status=past_due, grace_period_ends_at=now+3d, notify user
Grace period → User has 3 days to fix payment method
   └── Daily retry job until grace ends
Grace end without success → status=expired, lose access
Cancel → status=cancelled, cancels_at=current_period_end. Access continues until period end.

11.4 Endpoints#

12. Domain: Social Graph#

12.1 Responsibility#

Lightweight social primitives:

• Follow (User follows Creator)
• Like (Post)
• Share (Post — outbound share event tracking)
• Save (bookmark a Post)
• List (user-curated grouping of creators)

12.2 Entities#

12.2.1 follows#

Unique on (follower_user_id, followed_user_id).

12.2.2 post_likes#

Unique on (post_id, user_id). Increment/decrement posts.like_count via observer.

12.2.3 comment_likes#

Same shape as post_likes for comments.

12.2.4 post_shares#

12.2.5 saved_posts#

Unique on (user_id, post_id).

12.2.6 lists#

Unique on (user_id, slug).

12.2.7 list_members#

Unique on (list_id, user_id).

12.3 Endpoints#

13. Domain: Fan Club#

13.1 Responsibility#

Community hub per creator, auto-populated from fan engagement + tier subscriptions. Provides:

• Per-creator community space with channels
• Redis + SSE-based real-time chat (reusing livestream chat primitive)
• Creator moderation tools (pin, delete, timeout)
• Creator-side dashboard view (engagement analytics, top fans, bulk message)
• Automatic membership based on Access domain's isActiveFan + tier subscription status

13.2 Entities#

13.2.1 fan_clubs#

Auto-created via CreateFanClubOnCreatorStatus listener on UserBecameCreator event.

13.2.2 fan_club_channels#

Default general channel created with fan club.

13.2.3 fan_club_memberships#

Unique on (fan_club_id, user_id).

SyncFanClubMembershipsJob runs every 30 minutes:

• Adds members for users who newly cross isActiveFan threshold OR have new tier subscription
• Removes members whose engagement fell below threshold AND no active tier sub (after 7-day grace)

13.2.4 fan_club_messages#

13.2.5 fan_club_timeouts#

User-with-active-timeout cannot post. Enforced in PostFanClubMessageAction.

13.3 Chat Delivery#

Reuses livestream chat primitive:

• Write: POST /v1/fanclubs/{id}/channels/{slug}/messages
  • Persists FanClubMessage row
  • Publishes to Redis channel fanclub:{id}:{channelSlug}
• Read (real-time): GET /v1/fanclubs/{id}/channels/{slug}/stream → SSE
  • Subscribes to Redis channel, streams events
• Read (historical): GET /v1/fanclubs/{id}/channels/{slug}/messages?cursor=... paginated

13.4 Endpoints#

14. Domain: Discovery & Ranking#

14.1 Responsibility#

Custom primitive ranking + search service. No external search engine in v1. Provides two entry points:

• Search — keyword query, returns scored posts/creators/collections
• Rank — personalized or global-trending feed

Both share a pipeline: candidate generation → scoring → filtering → diversification → pagination.

14.2 Entities#

14.2.1 interactions#

Append-only event log powering every ranker signal.

Partitioned by month via PostgreSQL declarative partitioning for write scaling. Indexes on (user_id, occurred_at), (interactable_type, interactable_id, occurred_at).

14.2.2 post_signal_cache#

Denormalized per-post features refreshed every 10 minutes.

Rebuilt by RefreshPostSignalsJob every 10 min.

14.2.3 user_affinity_cache#

Per-user denormalized affinities.

Rebuilt nightly by RefreshUserAffinityJob. Incremental updates on each interaction via a debounced queued job (coalesces into one rebuild per user per 30 min).

14.2.4 user_post_impressions (Redis-backed, not a table)#

Sorted set per user, capped at 500 most recent post IDs for already-seen suppression. TTL 7 days.

14.3 Ranker Configuration#

discovery.ranker_weights:

{
  "w_recency": 3.0,
  "w_engagement_rate": 2.5,
  "w_creator_affinity": 4.0,
  "w_niche_affinity": 2.0,
  "w_category_affinity": 1.5,
  "w_tag_overlap": 1.0,
  "w_trending_boost": 1.5,
  "w_text_match": 3.0,
  "w_premium_boost": 0.05,
  "w_boosted_post": 2.0,
  "w_already_seen_penalty": -2.0,
  "w_cold_start_bootstrap": 1.2,
  "recency_half_life_hours": 48,
  "max_per_creator_in_top_20": 2,
  "candidate_pool_size": 500
}

Every weight live-tunable via Filament.

14.4 Service Contracts#

<?php

declare(strict_types=1);

namespace App\Discovery\Contracts;

use App\Discovery\Data\DiscoveryQuery;
use App\Discovery\Data\DiscoveryResult;

interface IDiscoveryService
{
    public function search(DiscoveryQuery $query): DiscoveryResult;
    public function feed(DiscoveryQuery $query): DiscoveryResult;
    public function trending(DiscoveryQuery $query): DiscoveryResult;
}

interface ISignalContributor
{
    public function identifier(): string;
    public function contribute(DiscoveryCandidate $candidate, DiscoveryContext $context): float;
}

DiscoveryService is composed of an ordered array of ISignalContributor implementations, each returning a float. Final score = weighted sum.

Signal contributors (v1):

• RecencyDecaySignal
• EngagementRateSignal
• CreatorAffinitySignal
• NicheAffinitySignal
• CategoryAffinitySignal
• TagOverlapSignal
• TrendingBoostSignal
• TextMatchSignal (only when DiscoveryQuery::$keyword is present)
• PremiumBoostSignal
• BoostedPostSignal (promotions)
• AlreadySeenPenaltySignal
• ColdStartBootstrapSignal

14.5 Pipeline#

IDiscoveryService::feed(query):
  ├── 1. Candidate Generation
  │     ├── Posts from followed creators (last 14d)           → up to 200
  │     ├── Trending posts in user's top niches (last 48h)     → up to 200
  │     ├── Boosted posts (active, budget remaining)           → up to 50
  │     ├── Recent posts globally (cold start fallback)        → up to 100
  │     └── Dedupe, cap at 500, exclude already-dismissed
  ├── 2. Access Filter
  │     └── Drop posts viewer can't see the existence of (tier-gated by a private creator, etc.)
  ├── 3. Scoring
  │     └── Foreach candidate: sum of weighted signals
  ├── 4. Diversification
  │     └── Round-robin to respect max_per_creator_in_top_20
  ├── 5. Slot for Promoted
  │     └── Insert BoostedPosts at prescribed positions (e.g. positions 3, 8, 15)
  ├── 6. Sort by score DESC
  ├── 7. Paginate via cursor (score, postId)
  └── Return + log impressions (bulk `InteractionType::Impression` inserts)

For search, candidate generation uses Postgres FTS:

SELECT id, ts_rank(search_vector, websearch_to_tsquery('simple', :keyword)) as text_score
FROM posts
WHERE search_vector @@ websearch_to_tsquery('simple', :keyword)
  AND status = 'published'
ORDER BY text_score DESC
LIMIT 500

search_vector is a GENERATED tsvector column indexed with GIN:

ALTER TABLE posts ADD COLUMN search_vector tsvector
GENERATED ALWAYS AS (
  setweight(to_tsvector('simple', coalesce(title, '')), 'A') ||
  setweight(to_tsvector('simple', coalesce(body, '')), 'B')
) STORED;

CREATE INDEX posts_search_vector_idx ON posts USING GIN(search_vector);

Tags joined in via a separate subquery to boost text match when tags align.

14.6 Endpoints#

15. Domain: Promotions#

15.1 Responsibility#

Creator growth & revenue-accelerating primitives:

• Boosted posts (paid ranker boost)
• Promo codes (discount codes for purchases & subscriptions)
• Referral program (personal link → commission on referred user's spend)

15.2 Entities#

15.2.1 boosted_posts#

DebitBoostedPostImpressionsJob runs every minute aggregating impressions (from interactions) and debiting spent_minor_units. When spent >= budget → status=exhausted.

15.2.2 promo_codes#

15.2.3 promo_code_redemptions#

Unique on (promo_code_id, user_id, subject_type, subject_id).

15.2.4 referral_links#

15.2.5 referral_attributions#

15.2.6 referral_commissions#

15.3 Flows#

Promo code redemption happens inline at purchase/subscribe time:

PurchasePostAction (if promoCode provided):
  ├── Resolve PromoCode (by code, not expired, active)
  ├── Check applies_to compatibility
  ├── Check max_uses_per_user (redeemed by this user already?)
  ├── Calculate discount
  ├── Final gross = original - discount (but not less than 0)
  ├── Fee calculation uses discounted gross
  ├── Post-settlement: insert PromoCodeRedemption, increment uses_count
  └── Return PostPurchase with discount fields populated

Referral attribution captured at signup:

User clicks loreax.com/r/{slug} → AttributeReferralAction
  ├── Set HttpOnly cookie `loreax_ref=<slug>` for 30 days
  └── Increment ReferralLink.clicks

User signs up (RegisterUserAction):
  ├── Read cookie; if present:
  │     ├── Resolve ReferralLink
  │     ├── Create ReferralAttribution (referred_user_id = new user)
  │     ├── Issue welcome_credit ledger transaction
  │     └── Increment ReferralLink.signups
  └── Proceed with registration

Commission on spend — every PostPurchased, TierSubscriptionPaid, PremiumSubscriptionPaid event listened by CreditReferralCommissionListener:

If referred user has active ReferralAttribution (attribution_expires_at > now):
  commission = spend * attribution.commission_rate
  LedgerService::post(referral_commission rule)
  Create ReferralCommission row

15.4 Endpoints#

16. Domain: Notifications#

16.1 Responsibility#

Delivers notifications across in-app, email, web push, and SMS channels. Leverages Laravel's notification system with a centralized preferences layer. Terminal sink — no notification triggers another domain.

16.2 Channels#

16.3 Entities#

16.3.1 notifications (Laravel default)#

Laravel's database channel table with id (UUID), type, notifiable_type, notifiable_id, data (jsonb), read_at, created_at.

16.3.2 notification_preferences#

Unique on (user_id, notification_type, channel).

16.3.3 web_push_subscriptions#

Standard schema from laravel-notification-channels/webpush.

16.3.4 failed_notifications#

16.4 Notification Types (v1 catalog)#

App\Notifications\Enums\NotificationType:

• account.email_verified
• account.password_changed
• account.mfa_enabled
• account.handle_changed
• account.suspicious_login
• social.new_follower
• social.new_fan_club_member
• social.comment_mention
• social.comment_reply
• content.new_post_from_followed (digested)
• content.saved_post_now_free
• content.post_you_bought_removed
• commerce.top_up_succeeded
• commerce.top_up_failed
• commerce.purchase_receipt
• commerce.tier_charged
• commerce.tier_renewal_upcoming_7d
• commerce.tier_renewal_upcoming_1d
• commerce.tier_payment_failed
• commerce.withdrawal_requested
• commerce.withdrawal_succeeded
• commerce.withdrawal_failed
• commerce.refund_issued
• creator.new_purchase
• creator.new_tier_subscriber
• creator.new_fan_club_member
• creator.tier_subscriber_cancelled
• creator.boost_budget_exhausted
• creator.promo_code_redeemed
• creator.moderation_action
• creator.verification_status
• system.maintenance_scheduled
• system.policy_update
• system.policy_violation_warning

Each has default channel routing in config/notifications.php:

return [
    'types' => [
        'commerce.top_up_succeeded' => [
            'default_channels' => ['in_app', 'email'],
            'user_overridable' => ['email'],
            'digest' => false,
        ],
        'content.new_post_from_followed' => [
            'default_channels' => ['in_app', 'email'],
            'user_overridable' => ['in_app', 'email', 'web_push'],
            'digest' => 'daily_8am',
        ],
        'account.suspicious_login' => [
            'default_channels' => ['in_app', 'email', 'sms'],
            'user_overridable' => [], // Non-optional
            'digest' => false,
        ],
    ],
];

16.5 Digest Delivery#

DigestNotificationsJob runs daily at user's local 8am (batched by timezone):

• Collects all pending digest notifications for the user from the last 24h
• Groups by notification_type
• Renders one digest email with the groups
• Clears the pending digest queue

"Pending digest" is maintained in a Redis list per user: notifications:digest:{userId}.

16.6 Endpoints#

17. Domain: Moderation#

17.1 Responsibility#

Enforces content policy in three configurable modes (reactive_only default; ai_prescreen and manual_prescreen stubbed and activatable via platform setting). Owns:

• User reports
• Review queue
• Takedown workflow
• AI moderation provider stubs (OpenAI Moderation, Claude review notes)
• Creator warnings & suspensions

17.2 Entities#

17.2.1 reports#

Uniqueness constraint relaxed: multiple reports on same subject allowed (counted in duplicate_count on a canonical primary row via service).

17.2.2 moderation_actions#

Audit trail of moderator decisions beyond report resolution.

17.2.3 creator_warnings#

Three strikes → automatic 7-day suspension (configurable).

17.2.4 user_suspensions#

Active suspensions block login and write endpoints; read-only browsing continues.

17.2.5 ai_moderation_results#

Stubbed; only populated when moderation.mode != reactive_only.

17.3 Provider Interface#

<?php

declare(strict_types=1);

namespace App\Moderation\Contracts;

interface IModerationAiProvider
{
    public function identifier(): string;
    public function evaluatePost(Post $post): AiModerationResult;
}

v1 stubs: OpenAiModerationProvider, ClaudeReviewNotesProvider. Wired but never called when moderation.mode = reactive_only.

17.4 Endpoints#

18. Domain: Admin & Back Office#

18.1 Responsibility#

Filament-powered back office, separate admin guard, RBAC via static scope dictionary + DB-backed roles.

18.2 Key Modules (Filament Panel /admin)#

• Dashboard — system-wide KPIs (MAU, DAU, GMV, platform revenue, top creators, pending review count)
• Users — search, impersonate (with audit), suspend, unsuspend
• Creators — creator directory, notable verification queue, earnings summary, warning history
• Admin Users — provision new admins (Super Admin only), assign roles
• Roles — read roles and scopes (immutable from UI; modified via code + seeders for safety)
• Posts — moderation, bulk takedown
• Comments — moderation
• Reports — review queue with filters, bulk resolve
• Ledger — transactions browser, manual adjustment (with Ledger.Approval two-person gate)
• Withdrawals — ops queue, retry, force-fail, CSV export
• Top-ups — view, manually reconcile stuck ones
• Promotions — boosts, promo codes, referral stats
• Tiers — read-only view of creator tiers
• Niches & Categories — edit taxonomy
• Platform Settings — all runtime-tunable keys
• Feature Flags — toggle & rollout %
• Audit Log — activity_log browser with rich filters
• Request Log — Mongo-backed log browser (read-only)
• Failed Notifications — retry queue
• Jobs — Horizon embedded
• Wallet Drift Incidents — reconciliation alerts
• Approval Requests — pending two-person approvals across the system

18.3 Role Definitions (seeded)#

Full mapping in Appendix A. Summary:

18.4 Two-Person Approval Pattern#

Scopes ending in .Approval on destructive financial actions require a distinct second admin to approve via the ApprovalRequest workflow.

Admin A → InitiateLedgerAdjustmentAction → creates ApprovalRequest (status=pending)
Admin B → ApproveAction → executes the adjustment inside DB::transaction
         → ApprovalRequest.status=approved, sets approved_by

Admin A cannot approve their own request. Enforced in ApproveAction.

18.5 Audit Logging#

spatie/laravel-activitylog wired on every Eloquent model through a base LogsActivityStrict trait:

• causer_type/causer_id polymorphic to User or AdminUser
• subject_type/subject_id polymorphic to affected model
• event — e.g. post.published, withdrawal.succeeded, user.suspended
• properties — before/after diff
• request_id — correlation to RequestLog
• reason — required on destructive events

Activity log table is append-only enforced by revoking DELETE privilege from the application DB role.

19. Cross-Cutting: Observability#

19.1 Goals#

Every request, every job, every state change must be reconstructible from logs. Three observability streams correlate via requestId and conversationId:

1. RequestLog (MongoDB) — every inbound HTTP request
2. ActivityLog (Postgres, via spatie/laravel-activitylog) — every domain state change
3. JobLog (Mongo) — every queued job execution
4. FileLog (local/runtime) — size-rotated files where sequence 0 is always newest (laravel.0.log, laravel-YYYY-MM-DD.0.log)
5. Database query log (PHP runtime sampling → CloudWatch) — slow queries only

Correlation flow:

Inbound request → assign requestId → attach to Log context
                → any job dispatched inherits requestId via JobMiddleware
                → any activity log entry records requestId in properties
                → downstream HTTP calls propagate X-Request-ID header

19.2 RequestLogger#

Follows the user-provided MongoRequestLogger blueprint. The contract:

<?php

declare(strict_types=1);

namespace App\Core\Contracts;

use App\Identity\Enums\Realm;

interface IRequestLogger
{
    /**
     * Persist a single request log entry.
     *
     * @throws \App\Core\Exceptions\RequestLogWriteException on unrecoverable failure
     */
    public function log(RequestLogEntry $entry): void;
}

RequestLogEntry value object carries:

• requestId — ULID, mandatory
• conversationId — propagated from client or defaults to requestId
• traceId — W3C Trace Context trace-id (32 hex chars), mandatory
• spanId — W3C Trace Context span-id (16 hex chars), mandatory
• realm — user | admin | system (system for job-triggered requests)
• processorName — matched controller action or job class FQCN
• platform — from X-Platform header (web, ios, android, admin_web)
• scenario — from X-Scenario header (e.g. onboarding, purchase_flow)
• appVersion — from X-App-Version header
• backendVersion — from config (app.version, git sha)
• method — HTTP method
• path — route pattern (not raw URI, to avoid cardinality explosion)
• statusCode
• durationMs
• isSuccessful — status < 400 AND no unhandled exception
• userId — nullable
• adminId — nullable
• requestPayload — jsonb, redacted (passwords, tokens, MPESA details stripped)
• responsePayload — jsonb, redacted, only if 4xx/5xx or explicitly opted-in via route config
• errorCode — from exception, if any
• errorMessage — safe-to-log, never PII
• userAgent, ipAddress, referer
• occurredAt — UTC timestamp

Implementation (MongoDB, strict-by-design):

<?php

declare(strict_types=1);

namespace App\Core\Infrastructure\Logging;

use App\Core\Contracts\IRequestLogger;
use App\Core\Contracts\RequestLogEntry;
use App\Core\Exceptions\RequestLogWriteException;
use MongoDB\Client as MongoClient;
use MongoDB\Collection;
use MongoDB\Driver\Exception\Exception as MongoException;
use Psr\Log\LoggerInterface;

final class MongoRequestLogger implements IRequestLogger
{
    private readonly Collection $collection;

    public function __construct(
        MongoClient $client,
        private readonly LoggerInterface $fallbackLogger,
        string $database,
        string $collectionName,
    ) {
        $this->collection = $client->selectCollection($database, $collectionName);
    }

    public function log(RequestLogEntry $entry): void
    {
        $document = [
            'requestId' => $entry->requestId,
            'conversationId' => $entry->conversationId,
            'traceId' => $entry->traceId,
            'spanId' => $entry->spanId,
            'realm' => $entry->realm->value,
            'processorName' => $entry->processorName,
            'platform' => $entry->platform,
            'scenario' => $entry->scenario,
            'appVersion' => $entry->appVersion,
            'backendVersion' => $entry->backendVersion,
            'method' => $entry->method,
            'path' => $entry->path,
            'statusCode' => $entry->statusCode,
            'durationMs' => $entry->durationMs,
            'isSuccessful' => $entry->isSuccessful,
            'userId' => $entry->userId,
            'adminId' => $entry->adminId,
            'requestPayload' => $entry->requestPayload,
            'responsePayload' => $entry->responsePayload,
            'errorCode' => $entry->errorCode,
            'errorMessage' => $entry->errorMessage,
            'userAgent' => $entry->userAgent,
            'ipAddress' => $entry->ipAddress,
            'referer' => $entry->referer,
            'occurredAt' => new \MongoDB\BSON\UTCDateTime($entry->occurredAt->getTimestamp() * 1000),
        ];

        try {
            $this->collection->insertOne($document);
        } catch (MongoException $e) {
            $this->fallbackLogger->error('RequestLog write failed', [
                'requestId' => $entry->requestId,
                'error' => $e->getMessage(),
            ]);

            throw new RequestLogWriteException(
                'Unable to persist request log for ' . $entry->requestId,
                previous: $e,
            );
        }
    }
}

Registered in a custom LoggingServiceProvider, wired from config/app.php custom namespace (app.custom.request_logger.*).

Terminable middleware ensures the log write happens after response send — it never blocks response latency:

final class LogRequestMiddleware
{
    public function handle(Request $request, Closure $next): Response
    {
        $start = hrtime(true);
        $request->attributes->set('request_start_hrtime', $start);

        return $next($request);
    }

    public function terminate(Request $request, Response $response): void
    {
        try {
            $entry = RequestLogEntryFactory::fromRequestResponse($request, $response);
            app(IRequestLogger::class)->log($entry);
        } catch (Throwable $e) {
            Log::error('Terminal request log failed', ['exception' => $e]);
            // Do not re-throw — terminable middleware swallows.
        }
    }
}

19.3 Redaction Rules#

RequestLogEntryFactory applies field-level redaction:

• Request paths containing password, passwordConfirmation, currentPassword, mfaCode, mfaBackupCode, otp, token, providerToken, providerIdToken → replaced with [REDACTED]
• Authorization headers stripped entirely
• MPESA phoneNumber masked to last 3 digits: xxxxx678
• Credit card-like patterns regex-stripped
• Request body for /v1/payments/* → only non-sensitive fields kept (amount, currency, idempotencyKey)
• Response body persisted only for 4xx/5xx or when route declares logResponsePayload=true

Redaction list centralized in config/request_logger.php — editable without code change.

19.4 JobLog#

Every queued job wraps in LogsJobExecution middleware (via Horizon/Laravel job middleware):

• Job class, payload hash, attempt, queue, requestId (if dispatched in request context), duration, success/failure, exception class + message
• Written to Mongo job_logs collection via IJobLogger sibling of IRequestLogger
• Failed jobs also live in standard Laravel failed_jobs table for Horizon UI

19.5 ActivityLog#

spatie/laravel-activitylog augmented:

• properties.requestId always populated if activity happens within a request scope (read from context via AssignRequestId middleware)
• Log names segmented by domain: identity, ledger, content, etc. — filterable in Filament
• Sensitive models (e.g. MfaChallenge) excluded from activity log via $logAttributes = false

19.6 Metrics#

CloudWatch namespace Loreax/:

• HTTP: request_count, request_duration (p50/p95/p99), error_rate by path pattern & status class
• Ledger: transactions_per_minute, unbalanced_transaction_attempts (should always be zero), wallet_drift_count
• Payments: top_up_success_rate, withdrawal_success_rate, mpesa_callback_lag
• Queues: queue_depth per Horizon queue, job_duration per job class, failed_job_count
• DB: connection_count, slow_query_count
• Discovery: feed_latency, candidate_pool_size

Emitted via spatie/laravel-server-monitor equivalent + a lightweight custom MetricsRecorder shim wrapping CloudWatch PutMetricData calls.

19.7 Alerts#

CloudWatch alarms (v1 baseline):

20. Cross-Cutting: Jobs, Scheduling & Events#

20.1 Queue Configuration#

Horizon queues (configured in config/horizon.php):