TenantXTenantX
Docs
Backend layout — Tenantx kernel

Backend layout — Tenantx kernel

This document describes how **HTTP controllers** and **Eloquent models** are organized so the kit stays navigable as buyers extend it.

Backend layout — Tenantx kernel

This document describes how HTTP controllers and Eloquent models are organized so the kit stays navigable as buyers extend it.

HTTP controllers (app/Http/Controllers/)

FolderPurposeNamespace prefix
(root)Controller.php — base class with workspace helpersApp\Http\Controllers
Concerns/Traits shared by controllers (help center, Spatie, subscription admin)App\Http\Controllers\Concerns
Auth/Login, register, 2FA, password reset, Google OAuth (SocialAuthController)App\Http\Controllers\Auth
Public/Unauthenticated or marketing-facing API (landing contact, public help center)App\Http\Controllers\Public
Stripe/Stripe Checkout + webhooksApp\Http\Controllers\Stripe
Platform//api/platform/* operator console (plans, orgs, payments, help CRUD, …)App\Http\Controllers\Platform
Tenant/Authenticated tenant/org API (dashboard, orgs, workspaces, users, subscription tenant surface, …)App\Http\Controllers\Tenant

Rule: Controllers in subfolders must use App\Http\Controllers\Controller; because extends Controller would otherwise resolve to e.g. Auth\Controller.

Routes: routes/api.php and routes/web.php import concrete classes (e.g. App\Http\Controllers\Tenant\ActivityLogController).

Inventory & refactors

  • Inventory (paths + use App\Http\Controllers\… references):
    php scripts/inventory-kernel-structure.php
    php scripts/inventory-kernel-structure.php --json > build/kernel-inventory.json
  • Controller tree moves + rewrite imports (already applied in repo; re-run only on a clean tree):
    php scripts/reorganize-kernel-controllers.php --dry-run
    php scripts/reorganize-kernel-controllers.php --apply
    Then if needed: php scripts/fix-controller-base-import.php (adds base Controller import).

If --dry-run reports 0 moves, controllers are already under Auth/, Platform/, Public/, Stripe/, Tenant/ (only Controller.php remains at Http/Controllers/ root). To see the full move list again, run the script from a git worktree checked out at a commit before the reorganization.

VS Code / Cursor workspace + git worktree

  • Open tenantx-kernel.code-workspace (repo root) for a multi-root window: main clone + ../tenantx-reorg-dryrun worktree (create/remove the worktree as below).
  • Create worktree (sibling folder, new branch): 
    git worktree add ../tenantx-reorg-dryrun -b workspace/reorg-dryrun
    Optional: pin an old commit so dry-run is non-empty:
    git worktree add ../tenantx-reorg-dryrun -b workspace/reorg-dryrun <commit-before-reorg>
  • Dry-run inside worktree: 
    php ../tenantx-reorg-dryrun/scripts/reorganize-kernel-controllers.php --dry-run
    Or cd into ../tenantx-reorg-dryrun and run php scripts/reorganize-kernel-controllers.php --dry-run.
  • Remove worktree when finished: 
    git worktree remove ../tenantx-reorg-dryrun

Models (app/Models/)

Target layout uses subfolders (bounded contexts), e.g. App\Models\Identity\User → app/Models/Identity/User.php.

  • Inventory: php scripts/inventory-kernel-structure.php (lists all model FQCNs).
  • Move models + rewrite App\Models\… across backend/ (including database/, config/, tests/): 
    php scripts/reorganize-kernel-models.php --dry-run
php scripts/reorganize-kernel-models.php --apply
cd backend && composer dump-autoload
    The map is defined in scripts/reorganize-kernel-models.php (Identity, Workspace, Organization, Subscription, HelpCenter, Permission, etc.).

Do not run --apply on a dirty tree without review; commit or stash first. After moving, run php artisan test and fix any dynamic references (rare).

Related

  • Permissions & routes: AGENTS.md, docs/PERMISSIONS.md, routes/api.php
Org adminOrganization (frontend)