Appearance
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.
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| Module | What it does |
|---|---|
| Recordings | Sites, the tracking script, ingest, storage, the session list and replay, share links, downloads, live view |
| Heatmaps | Click, scroll and move heatmaps |
| Insights | Behavior insights: frustration, journeys, elements |
| Funnels | Funnels, reports, weekly regression emails |
| Forms | Form analytics |
| Events | Custom events (__sr.push(['event', …])) |
| Errors | JavaScript errors grouped by cause |
| Surveys | On-site surveys, designs, results |
| Experiments | A/B tests, the visual editor, results |
| Alerts | Email, Slack and webhook alerts |
| Summaries | AI session summaries, plain-words search, Ask AI, site digests (Claude) |
| HubSpot | Replay links on HubSpot contacts |
| Announcements | What's-new posts for users |
| Help | Help center and its AI chat |
| Installer | The installer (never part of the module pack) |
| SaaS: Plans, BillingStripe, BillingPaddle, Signup, Landing, Pages, Affiliates, Tickets | Plans 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:
- its
module.jsonis valid and itsnameequals the folder name (StudlyCase, it becomes the namespaceModules\<Name>), "enabled"is notfalse,- its
"requires"matches the running Replora version ({"replora": "^1.0"}), - it belongs to the running edition: every module in
saas/modulesis SaaS-only; a module inmodules/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"
}
}| Key | Required | Meaning |
|---|---|---|
name | Yes | Folder and namespace name. |
version | No | The module's semantic version. |
requires.replora | No | Replora versions it works with (Composer-style constraint); empty = any. |
description | No | Short description shown to administrators. |
provider | Yes | Its service provider; must be a class inside Modules\<Name>\. |
enabled | No (default true) | false: discovered but not booted. |
abilities | No | API token abilities the module checks, with a description each; they appear in the token dialog. |
edition | No | saas 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 / file | Loaded as |
|---|---|
Config/<name>.php | Merged into config('<name>') (lower-case module name) |
Routes/api.php | Under /api/v1 with the api middleware group (authentication, rate limits, roles, language) and route names api.v1.* |
Routes/web.php | Public pages with the web group (session, CSRF), registered before the dashboard's catch-all route |
Routes/embed.php | Public routes at the site root with the embed group: no session, cookies or CSRF (the tracker's endpoints) |
Database/Migrations | Migrations |
Resources/lang | __('…') translations (<locale>.json) and the <name>:: namespace |
Resources/views | Blade 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)):
| Contract | Tag | A module adds… |
|---|---|---|
Settings\SettingsSource | replora.settings | Groups 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\PersonalData | replora.personal-data | Its section of "Download my data": what it keeps about a person (never secrets). |
Plans\UsageSource | replora.usage | Its 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\HealthSource | health.sources | Checks for System › Service status: id, label, status (ok, warn, fail, off), detail; quick and never throwing. |
Admin\OverviewSource | replora.admin-overview | Numbers, daily series, breakdowns and lists for the administrators' Overview page, in the sections revenue, growth or usage. |
Users\AccountFacts | replora.account-facts | Columns on the administrators' Users page (e.g. "Sites", "Plan"). |
Users\UserTraits | replora.user-traits | Facts added to the signed-in person (GET /me → extras). |
Recordings\SessionSet | replora.session-sets | A named group of sessions the session list can filter by (set=<name>:<value>, e.g. a funnel step's drop-outs). |
Recordings\SessionMoments | replora.session-moments | Moments on a session's timeline (e.g. survey answers), seen by AI summaries. |
Updates\UpgradeStep | replora.upgrades | A 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:
| Contract | Answered by | Default without it |
|---|---|---|
Sites\SiteDirectory | Recordings | No site exists |
Sites\SiteKeys, Sites\SiteOwners | Recordings | No key / owner known |
Recordings\SessionTimeline, Recordings\SharedSessions | Recordings | No sessions / links |
Plans\PlanLimits | Plans (SaaS) | ConfigPlanLimits: the installation's limits from config |
Plans\PlanCatalog | Plans (SaaS) | No plans |
Billing\BillingGateway | BillingStripe or BillingPaddle | Nothing can be bought |
Accounts\Registration | Signup (SaaS) | Sign-up closed |
Pages\PublicPages | Pages (SaaS) | No pages |
Ai\AiAnswers | Summaries | No AI answers |
Core events
| Event | Fired by | Typical listeners |
|---|---|---|
Recordings\BatchStored | Recordings, 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\SiteDeleted | Recordings | Every module deletes its data of the site |
Accounts\AccountCreated | Sign-up | Plans starts a free trial |
Accounts\OrganizationDeleting, Accounts\UserDeleting | Core | Remove files and outside data the database can't cascade |
Accounts\EmailChanged | Core | Signup asks to confirm the new address |
Billing\EntitlementChanged, Billing\PaymentReceived | Billing 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.
| Member | Adds |
|---|---|
name | The 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 itsname/providerdoesn'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": falsein itsmodule.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/, runphp 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.
