Architecture

High-Level Structure

The Portal is a Laravel 11 application with two distinct UI layers:

Filament 4 panels — Modern admin UI at /internal-admin, auto-discovers resources from app/Filament/.
Legacy Livewire 3 + Blade — The original admin, landlord, moderator, and B2B panels built with Livewire components and Blade templates, using Bootstrap 5 for styling.

Both layers share the same Eloquent models, services, and database.

Directory Layout


app/
  Actions/           # Invokable action classes
  Concerns/          # Shared traits (e.g., Notifiable)
  Console/           # Artisan commands
  Constants/         # Enums: Role, FeatureFlag, DocumentType, Room, TimeZone
  Contracts/         # Interfaces
  Drivers/           # Custom driver implementations
  Enums/             # PHP 8.1 enums: HouseStatus, PerkStatus, PerkType, etc.
  Events/            # Laravel events
  Exceptions/        # Exception handlers
  Exports/           # Excel/CSV export classes (maatwebsite/excel)
  Filament/          # Filament 4 resources, widgets, exports
    Exports/         # Filament export classes (EventRSVP, PerkCode, etc.)
    Resources/       # Filament resources (13 resource modules)
    Widgets/         # Dashboard widgets (SupportWidget)
  Helpers/           # Utility helpers
  Http/
    Controllers/     # Traditional controllers (admin events, landlord leads, Uppy)
    Livewire/        # Livewire components organized by panel
      Admin/         # ~50+ components for admin panel
      Common/        # Shared components (B2B dashboard, chat, auth)
      DemoCollege/   # Demo college management
      Landlord/      # ~30+ components for landlord panel
      Moderator/     # ~15+ components for moderator panel
      PropertyOwner/ # US-mode property owner dashboard
    Middleware/       # Session-based auth middleware per panel
  Jobs/              # Queued jobs
  Listeners/         # Event listeners
  Mail/              # Mailable classes
  Managers/          # Manager pattern classes
  Models/            # 133 Eloquent models
  Providers/         # Service providers (App, Auth, Firebase, Filament, Theme, Route)
  Queries/           # Query builder classes
  Services/          # Business logic services (payments, HubSpot, DocuSign, etc.)
  Traits/            # Shared model traits (e.g., CompanyScope)
  Utils/             # Utility classes (EmailUtils, NotificationUtils, UserUtils)

config/              # Laravel + package config
database/            # Migrations, seeders, factories
deploy/              # Docker/Nginx/Supervisor deployment config
resources/
  assets/            # Static assets (images, emails, plugins, Firebase, JS)
  css/               # CSS files
  js/                # JavaScript files
  sass/              # SCSS (compiled via Vite)
  views/             # Blade templates
routes/
  web.php            # All web routes (admin, landlord, moderator, B2B, Uppy)
  api.php            # Minimal API routes (Sanctum auth only)

Multi-Panel Architecture

Filament Panel (Modern)

A single Filament panel is registered via AdminPanelProvider:

Panel ID: internal-admin
Path: /internal-admin
Auth: Uses AdminSession middleware (requires session('usertype') == 1 or session('internal_user_id'))
Resources auto-discovered from app/Filament/Resources/
Widgets auto-discovered from app/Filament/Widgets/
Features: SPA mode with prefetching, database notifications, Poppins font, dark mode disabled
Brand color: #004225 (Housr green)

Legacy Panels (Livewire + Blade)

The legacy panels are defined directly in routes/web.php using middleware groups:

Middleware Alias	Class	Access Rule
`AdminSession`	`App\Http\Middleware\Admin`	`session('usertype') == 1` OR `session('internal_user_id')`
`LandlordSession`	`App\Http\Middleware\Landlord`	`session('usertype')` is 2 or 7
`ModeratorSession`	`App\Http\Middleware\Moderator`	`session('usertype')` in [4, 5, 6, 7, 9]
`BusinessToBusinessSession`	`App\Http\Middleware\BusinessToBusiness`	`session('usertype') == 8`
`permission:{slug}`	`App\Http\Middleware\CheckPermission`	Role-based permission check via `InternalUser` roles

Each panel has its own set of Livewire components in app/Http/Livewire/{Panel}/.

Regional Configuration

The Portal supports US and UK modes via the USA env variable (config('app.USA')):

Landlord role displays as “Property Owner” in US mode
Some routes are US-only (ratings, promotions, separate dashboard)
Feature flags in the feature_flags table control feature availability per region
The CompanyScope trait scopes queries by company_name for multi-tenant operator access

Frontend Stack

Vite bundles SCSS, CSS, and JS assets
Bootstrap 5 for legacy panel layouts
Filament 4 provides its own Tailwind-based UI for the /internal-admin panel
ApexCharts / Chart.js for dashboard charts
Uppy for S3 multipart file uploads
FontAwesome 6 for icons
html2canvas for client-side screenshot/PDF generation

Service Layer

Business logic lives in app/Services/. Key services:

Service	Purpose
`StripePaymentService`	Stripe payment intents (GBP, boost credits)
`FinixPaymentService`	Finix payments (USD, boost credits)
`HubSpotService`	CRM contact lookup and updates
`DocusignService`	E-signature envelope creation and status tracking
`UppyCompanionService`	S3 presigned URLs and multipart upload management
`ConciergeService`	Enquiry management and automatic distribution
`BoostService`	Boost credit purchasing and balance management
`HouseService` / `HouseCreationService`	House CRUD operations
`FeatureFlagService`	Runtime feature flag checks
`SlackBotService`	Slack webhook notifications
`DocumentService`	Document management

Admin-Specific Services (`app/Services/Admin/`)

Additional services for admin operations including brand ambassador payments, demo colleges, freebies, huddle contracts/uploads, internal user management, lead management, perk management, and university statistics.