---
title: "Introduction"
description: "What this bundle does, its modules, architecture, and mental model."
type: "docs"
category: "doc"
tags: []
authors: [Anonymous]
date: "2026-09-09"
last_update: "2026-09-09"
time_minutes: 3
draft: false
unlisted: false
url: "https://www.derafu.dev/docs/symfony/platform-bundle/introduction"
---

# Introduction

Derafu Platform Bundle is a Symfony bundle that provides the foundational
infrastructure for SaaS applications: user management, authentication,
multi-tenant organizations, a plugin/app ecosystem, and an event-driven
notification system. It supplies reusable building blocks that every SaaS
needs — without imposing opinions on your business logic.

## Modules

The bundle is organized into six modules, each independently useful but
designed to work together:

| Module | What it provides |
|---|---|
| **Core** | Base resource abstraction, seeders, registry, settings infrastructure |
| **Identity** | Users, roles, permissions, organizations, teams, API keys, JWT, 2FA |
| **IdentityUi** | Ready-made web UI for auth flows and account settings |
| **Apps** | Plugin/integration ecosystem with per-user and per-organization installations |
| **Notifications** | Event-driven notifications via email, in-app, and webhooks |
| **Api** | API Platform integration helpers (query string adapters, scope enforcement) |

## Architecture pattern

Every ORM relation in the bundle targets an **interface**, not a concrete
class. Doctrine resolves interfaces to the app's concrete entities at
runtime via `resolve_target_entities`, wired automatically by the bundle's
DI extension. The bundle has zero knowledge of your `App\Entity\*` classes.

The entity pattern is **MappedSuperclass + ResolveTargetEntityListener**:

```
Bundle                               App
──────                               ───
BaseUser (MappedSuperclass)  ◄──  User (#[ORM\Entity])
UserInterface ────────────────►   resolved to User at runtime
```

All public service contracts live under `Contract/{Entity,Service,Integration}/`
folders. Services are `final` with companion interfaces — consumers inject
the interface, not the class.

## Mental model

```
User alice@example.com
 ├── personal resources (UserOwnedInterface)
 └── member of Organization "acme"
      ├── OrganizationMembership (role = org.owner)
      ├── shared resources (OrganizationOwnedInterface)
      ├── Team "backend" (subset of members → resource access)
      └── other invited members
```

App entities (Project, Invoice, Document, …) integrate with the bundle
by implementing one or more interfaces. The bundle provides traits with
ready-made Doctrine mapping.

## What it is

- A **MappedSuperclass** bundle — the bundle owns the ORM schema; the app
  owns the concrete entity classes, table names, and extra fields.
- A **cascading RBAC engine** — permissions are checked at four levels:
  resource → team → organization → global, with automatic fallback.
- A **user lifecycle toolkit** — registration, email verification, password
  reset, email change, magic links, sudo mode, and lockout.
- A **multi-tenant membership system** — GitHub-style organizations with
  roles, teams, and invitations.
- A **plugin/app system** — apps installable per user, per organization, or
  per resource, with encrypted configuration storage.
- A **notification system** — event-defined notifications delivered via
  email, in-app messages, or webhooks, with per-user preferences.
- A **built-in web UI** — controllers, templates, and routes for all auth
  and account-settings flows (IdentityUi module).

## What it is not

- Not a replacement for Symfony Security — it builds on top of it.
- Not a JWT library — it wraps Lexik JWT for convenience.
- Not a 2FA solution — it integrates Scheb 2FA Bundle.
- Not an OAuth or social-login solution.



---
Last updated on 09/09/2026