Skip to content

Architecture & modules ​

The Replora server is a small Laravel core plus feature modules. Recordings, heatmaps, funnels, surveys, A/B tests, alerts and every other feature is a folder in modules/ (or saas/modules/ for the SaaS edition) with its own routes, migrations, dashboard pages, translations and tests. Modules never import each other: they cooperate through contracts and events in the core, so each one can be switched off or removed on its own.

10 minutesDevelopersSingle user · SaaS

The layout ​

text
apps/standalone/
├── app/                     the core: accounts, team, tokens, settings, updates, licensing
│   ├── Contracts/           interfaces modules implement or use
│   ├── Events/              events modules fire or listen to
│   └── Modules/             module discovery (ModuleRepository) and ModuleServiceProvider
├── modules/                 modules of both editions
│   ├── Recordings/          sites, tracker script, ingest, storage, sessions, replay
│   ├── Heatmaps/ Funnels/ Forms/ Events/ Errors/ Insights/
│   ├── Surveys/ Experiments/ Alerts/ Summaries/ HubSpot/
│   ├── Announcements/ Help/
│   └── Installer/           the web and command-line installer
├── saas/                    SaaS edition only (deleting it leaves the Single user edition)
│   ├── modules/             Plans, BillingStripe, BillingPaddle, Signup, Landing, Pages, Affiliates, Tickets
│   └── resources/js/        the SaaS modules' dashboard entry
└── resources/js/            the dashboard shell (React): layout, account pages, the module registry
ModuleWhat it does
RecordingsSites, the tracking script, ingest, storage, the session list and replay, share links, downloads, live view
HeatmapsClick, scroll and move heatmaps
InsightsBehavior insights: frustration, journeys, elements
FunnelsFunnels, reports, weekly regression emails
FormsForm analytics
EventsCustom events (__sr.push(['event', …]))
ErrorsJavaScript errors grouped by cause
SurveysOn-site surveys, designs, results
ExperimentsA/B tests, the visual editor, results
AlertsEmail, Slack and webhook alerts
SummariesAI session summaries, plain-words search, Ask AI, site digests (Claude)
HubSpotReplay links on HubSpot contacts
AnnouncementsWhat's-new posts for users
HelpHelp center and its AI chat
InstallerThe installer (never part of the module pack)
SaaS: Plans, BillingStripe, BillingPaddle, Signup, Landing, Pages, Affiliates, TicketsPlans and limits, payments, sign-up, the public website and its pages, the affiliate program, the support desk

How modules are found ​

At start-up ModulesServiceProvider scans modules/*/module.json and, when the saas/ folder exists (REPLORA_SAAS_PATH), saas/modules/*/module.json. A module boots when:

  1. its module.json is valid and its name equals the folder name (StudlyCase, it becomes the namespace Modules\<Name>),
  2. "enabled" is not false,
  3. its "requires" matches the running Replora version ({"replora": "^1.0"}),
  4. it belongs to the running edition: every module in saas/modules is SaaS-only; a module in modules/ may say "edition": "saas" or "single"; without it, it runs in both.

Modules of the other edition don't boot (no routes, pages, abilities or bindings); only their migrations load, so switching the edition never leaves tables missing. Classes are autoloaded by the module loader (Modules\<Name>\… from the module folder), no Composer change needed.

module.json ​

json
{
    "name": "Recordings",
    "version": "1.0.0",
    "requires": {
        "replora": "^1.0"
    },
    "description": "Session recording: sites, the tracking script, ingest, storage, session list and replay.",
    "provider": "Modules\\Recordings\\RecordingsServiceProvider",
    "enabled": true,
    "abilities": {
        "recordings:read": "List sites and sessions, replay recordings",
        "recordings:write": "Create, change and delete sites and recordings"
    }
}
KeyRequiredMeaning
nameYesFolder and namespace name.
versionNoThe module's semantic version.
requires.reploraNoReplora versions it works with (Composer-style constraint); empty = any.
descriptionNoShort description shown to administrators.
providerYesIts service provider; must be a class inside Modules\<Name>\.
enabledNo (default true)false: discovered but not booted.
abilitiesNoAPI token abilities the module checks, with a description each; they appear in the token dialog.
editionNosaas or single for a module in modules/ that belongs to one edition only.

ModuleServiceProvider ​

Every module's provider extends App\Modules\ModuleServiceProvider and names its folder. The base class wires the standard folders by convention:

Folder / fileLoaded as
Config/<name>.phpMerged into config('<name>') (lower-case module name)
Routes/api.phpUnder /api/v1 with the api middleware group (authentication, rate limits, roles, language) and route names api.v1.*
Routes/web.phpPublic pages with the web group (session, CSRF), registered before the dashboard's catch-all route
Routes/embed.phpPublic routes at the site root with the embed group: no session, cookies or CSRF (the tracker's endpoints)
Database/MigrationsMigrations
Resources/lang__('…') translations (<locale>.json) and the <name>:: namespace
Resources/viewsBlade views (<name>::view)
php
namespace Modules\Events;

use App\Contracts\Plans\UsageSource;
use App\Events\Recordings\BatchStored;
use App\Modules\ModuleServiceProvider;
use Illuminate\Support\Facades\Event;
use Modules\Events\Listeners\RecordCustomEvents;
use Modules\Events\Support\EventsUsage;

class EventsServiceProvider extends ModuleServiceProvider
{
    protected function moduleName(): string
    {
        return 'Events';
    }

    public function register(): void
    {
        parent::register();                                   // config
        $this->app->tag([EventsUsage::class], UsageSource::TAG); // a plan feature
    }

    public function boot(): void
    {
        parent::boot();                                       // routes, migrations, translations, views
        Event::listen(BatchStored::class, RecordCustomEvents::class);
    }
}

Scheduled commands are registered by the module that owns them (callAfterResolving(Schedule::class, …)), so removing a module removes its schedule too.

Contracts ​

Modules share behaviour only through interfaces in app/Contracts. Two kinds:

Tagged contracts — any number of modules contribute; the core collects them with the container tag ($this->app->tag([MyClass::class], Contract::TAG)):

ContractTagA module adds…
Settings\SettingsSourcereplora.settingsGroups of installation settings administrators change in Settings › Installation instead of .env: each field sets a config value (text, email, secret, bool, int, select; hint, options, min/max, required, when, max_length, public).
Users\PersonalDatareplora.personal-dataIts section of "Download my data": what it keeps about a person (never secrets).
Plans\UsageSourcereplora.usageIts plan-limited features with labels (events.enabled, funnels.count…) and an account's current use; the SaaS plan editor and "Plan & usage" page are built from these.
Health\HealthSourcehealth.sourcesChecks for System › Service status: id, label, status (ok, warn, fail, off), detail; quick and never throwing.
Admin\OverviewSourcereplora.admin-overviewNumbers, daily series, breakdowns and lists for the administrators' Overview page, in the sections revenue, growth or usage.
Users\AccountFactsreplora.account-factsColumns on the administrators' Users page (e.g. "Sites", "Plan").
Users\UserTraitsreplora.user-traitsFacts added to the signed-in person (GET /me → extras).
Recordings\SessionSetreplora.session-setsA named group of sessions the session list can filter by (set=<name>:<value>, e.g. a funnel step's drop-outs).
Recordings\SessionMomentsreplora.session-momentsMoments on a session's timeline (e.g. survey answers), seen by AI summaries.
Updates\UpgradeStepreplora.upgradesA data change a release needs beyond migrations; runs once after an update.

Single-implementation contracts — one module answers, the core has a harmless default when it is missing:

ContractAnswered byDefault without it
Sites\SiteDirectoryRecordingsNo site exists
Sites\SiteKeys, Sites\SiteOwnersRecordingsNo key / owner known
Recordings\SessionTimeline, Recordings\SharedSessionsRecordingsNo sessions / links
Plans\PlanLimitsPlans (SaaS)ConfigPlanLimits: the installation's limits from config
Plans\PlanCatalogPlans (SaaS)No plans
Billing\BillingGatewayBillingStripe or BillingPaddleNothing can be bought
Accounts\RegistrationSignup (SaaS)Sign-up closed
Pages\PublicPagesPages (SaaS)No pages
Ai\AiAnswersSummariesNo AI answers

Core events ​

EventFired byTypical listeners
Recordings\BatchStoredRecordings, after each stored batch: site, session, visitor facts, page views, custom events (signals)Heatmaps, Funnels, Forms, Events, Errors, Insights, Alerts, Experiments and HubSpot build their own data from it
Recordings\SiteDeletedRecordingsEvery module deletes its data of the site
Accounts\AccountCreatedSign-upPlans starts a free trial
Accounts\OrganizationDeleting, Accounts\UserDeletingCoreRemove files and outside data the database can't cascade
Accounts\EmailChangedCoreSignup asks to confirm the new address
Billing\EntitlementChanged, Billing\PaymentReceivedBilling modules (from signed webhooks)Plans records what the account may use; Affiliates credits commissions

Events carry plain values only, so listeners never depend on another module's classes.

Dashboard extensions ​

The dashboard is one React app. Each module may ship Resources/js/index.tsx that default-exports a DashboardModule (resources/js/lib/extensions.ts). The core never imports a module's files by name: Vite finds modules/*/Resources/js/index.tsx at build time (and the SaaS ones through saas/resources/js/index.ts), and at runtime only the modules the server lists as enabled register.

MemberAdds
nameThe module's folder name (must match module.json).
page(path, user)A dashboard page for a path, or null.
guestPage(path, appName)A page for signed-out visitors (e.g. /signup).
nav(user)Sidebar entries (label, icon, href, group: workspace, account or admin, badge, children).
home(user)The account's first page (/ redirects there).
siteLinks(siteId)Buttons on a site's pages (e.g. Heatmaps, Events).
sessionTabs(session)Tabs in the replay's side panel; get the session id, start time, current time and seek().
sessionsToolbar(siteId)Something above a site's session list (e.g. the plain-words search).
settings(user)Cards at the bottom of the Settings page (e.g. HubSpot).
installationCard(group, onSaved)Its own card for one of its installation settings groups.
userActions()Row actions on the administrators' Users page (e.g. "Change plan").
notice(user), topbar(user), overlay(user)A notice above every page, a top-bar button, something floating over every page.
tsx
import { defineModule } from '@app/lib/extensions';

export default defineModule({
  name: 'Events',
  siteLinks: (siteId) => [{ label: 'Events', icon: 'bolt', href: `/sites/${siteId}/events` }],
  page(path) {
    const m = path.match(/^\/sites\/(\d+)\/events$/);
    return m ? <EventsPage siteId={m[1]!} /> : null;
  },
});

planAllows('<feature>') (@app/lib/plan) hides a page or link when the account's plan doesn't include the feature.

The rules (composer check) ​

tools/check-modules.php fails the build when:

  • a module references another module's classes (Modules\Other\…, also in strings and docblocks),
  • a module folder has no module.json, or its name / provider doesn't match the folder,
  • shared code (app, bootstrap, config, database, routes, resources/views, tests) names a SaaS module: it must use a contract.

So deleting any module folder (or the whole saas/ folder) leaves a working application. Other checks in composer check: tools/check-imports.php (no inline fully-qualified class names), tools/check-docs.php (every class and public method has a PHPDoc), Pint, PHPUnit with 100 % line coverage (tools/check-coverage.php).

Enabling and disabling a module ​

  • Switch off: set "enabled": false in its module.json. Its routes, abilities, schedule and dashboard pages disappear at once (the dashboard asks the server which modules run). Data stays in the database.
  • Remove: delete the folder, then rebuild the dashboard (pnpm build) so its pages leave the bundle.
  • Add: copy the folder into modules/, run php artisan migrate, rebuild the dashboard, and clear cached routes and config if you cache them (php artisan optimize:clear).

GET /api/v1/app lists the modules that run.

Replora: see what your visitors see.