# 3. Meet mORMot 2 - Unit Structure

Enter the new territory

mORMot 2 represents a complete restructuring of the original framework. The monolithic units (SynCommons.pas, mORMot.pas) have been split into focused, layered units following SOLID principles.

This chapter introduces the new unit organization and helps you understand which units to include for your specific needs.

3.1. Layered Architecture Overview

mORMot 2 organizes its ~130 units into 6 dependency layers:

┌─────────────────────────────────────────────────────────────────────┐
│  Layer 5: Application & Tools                                       │
│  ┌─────┬─────┬────────┬──────┬───────┬─────┐                        │
│  │ app │ ui  │ script │ misc │ tools │ ddd │                        │
│  └─────┴─────┴────────┴──────┴───────┴─────┘                        │
└─────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 4: ORM / REST / SOA                                          │
│  ┌─────┬──────┬─────┐                                               │
│  │ orm │ rest │ soa │                                               │
│  └─────┴──────┴─────┘                                               │
└─────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 3: Database Access                                           │
│  ┌────┐                                                             │
│  │ db │                                                             │
│  └────┘                                                             │
└─────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 2: Networking                                                │
│  ┌─────┐                                                            │
│  │ net │                                                            │
│  └─────┘                                                            │
└─────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 1: System Libraries & Cryptography                           │
│  ┌─────┬────────┐                                                   │
│  │ lib │ crypt  │                                                   │
│  └─────┴────────┘                                                   │
└─────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 0: Foundation (RTL-Only)                                     │
│  ┌──────┐                                                           │
│  │ core │  (24 units - no mORMot dependencies)                      │
│  └──────┘                                                           │
└─────────────────────────────────────────────────────────────────────┘

Key Principle: Lower layers never depend on higher ones. This ensures:

• Incremental compilation
• Selective deployment
• Modular testing
• Clear separation of concerns

3.2. Unit Naming Convention

All units follow a consistent naming pattern:

mormot.<layer>.<feature>.pas

Examples:

• mormot.core.json.pas - Core layer, JSON feature
• mormot.orm.core.pas - ORM layer, core functionality
• mormot.db.sql.postgres.pas - Database layer, PostgreSQL SQL connector

Location Rules

Units are located in folders matching their layer:

• src/core/mormot.core..pas
• src/orm/mormot.orm..pas
• src/db/mormot.db..pas
• etc.

3.3. Layer 0: Core Foundation (mormot.core.)

24 units providing RTL-level functionality with zero mORMot dependencies.

Dependency Chain

mormot.core.base (RTL types, ASM stubs, no dependencies)
  └─► mormot.core.os (OS abstraction, threading)
      └─► mormot.core.unicode (charset/encoding)
          └─► mormot.core.text (text parsing, formatting)
              └─► mormot.core.datetime (ISO-8601, TTimeLog)
                  └─► mormot.core.rtti (RTTI wrapper)
                      └─► mormot.core.buffers (compression, base64)
                          └─► mormot.core.data (TDynArray, serialization)
                              └─► mormot.core.json (JSON parsing)
                                  └─► [higher units: variants, log, etc.]

Key Core Units

Minimal Core Usage

uses
  mormot.core.base,    // Foundation types
  mormot.core.os,      // OS abstraction
  mormot.core.text,    // Text utilities
  mormot.core.json;    // JSON support

var
  doc: TDocVariantData;
begin
  doc.InitJson('{"name":"John","age":30}');
  WriteLn(doc.U['name']);  // Output: John
end;

3.4. Layer 1: Libraries & Cryptography

External Libraries (mormot.lib.)

Cryptography (mormot.crypt.)

10 units for cryptographic operations:

Cryptography Factory Pattern

uses
  mormot.crypt.secure;

// High-level factories (recommended)
var
  h: ICryptHash;
  c: ICryptCipher;
begin
  // Hashing
  h := Hash('sha256');
  digest := h.Full(@data[1], length(data));

  // Encryption
  c := Cipher('aes-256-ctr', @key[1], {encrypt:}true);
  c.Process(plain, encrypted, '');
end;

3.5. Layer 2: Networking (mormot.net.)

3.6. Layer 3: Database Access (mormot.db.)

27 units for SQL and NoSQL database access:

Core Database

Raw Database APIs

SQL Connectors

NoSQL

RAD Adapters

3.7. Layer 4: ORM / REST / SOA

ORM Layer (mormot.orm.)

REST Layer (mormot.rest.)

8 units for RESTful services:

SOA Layer (mormot.soa.)

Application (mormot.app.)

UI Components (mormot.ui.)

Scripting (mormot.script.)

3.9. Common Usage Patterns

Minimal HTTP Server with ORM

uses
  mormot.core.base,
  mormot.core.os,
  mormot.orm.core,
  mormot.orm.sqlite3,
  mormot.rest.sqlite3,
  mormot.rest.http.server;

type
  TOrmPerson = class(TOrm)
  private
    fName: RawUtf8;
    fAge: Integer;
  published
    property Name: RawUtf8 read fName write fName;
    property Age: Integer read fAge write fAge;
  end;

var
  Model: TOrmModel;
  Server: TRestServerDB;
  HttpServer: TRestHttpServer;
begin
  Model := TOrmModel.Create([TOrmPerson]);
  Server := TRestServerDB.Create(Model, 'data.db3');
  Server.Server.CreateMissingTables;

  HttpServer := TRestHttpServer.Create('8080', [Server], '+', useHttpAsync);
  try
    WriteLn('Server running...');
    ReadLn;
  finally
    HttpServer.Free;
    Server.Free;
    Model.Free;
  end;
end.

Interface-Based Service

uses
  mormot.core.base,
  mormot.core.interfaces,
  mormot.soa.core,
  mormot.soa.server,
  mormot.rest.server;

type
  ICalculator = interface(IInvokable)
    ['{...GUID...}']
    function Add(A, B: Integer): Integer;
  end;

  TCalculator = class(TInjectableObjectRest, ICalculator)
  public
    function Add(A, B: Integer): Integer;
  end;

function TCalculator.Add(A, B: Integer): Integer;
begin
  Result := A + B;
end;

// Registration
Server.ServiceDefine(TCalculator, [ICalculator], sicShared);

Database-Only (No REST)

uses
  mormot.core.base,
  mormot.db.core,
  mormot.db.sql,
  mormot.db.sql.postgres;

var
  Props: TSqlDBPostgresConnectionProperties;
  Conn: TSqlDBConnection;
  Stmt: TSqlDBStatement;
begin
  Props := TSqlDBPostgresConnectionProperties.Create(
    'localhost:5432', 'mydb', 'user', 'pass');
  Conn := Props.ThreadSafeConnection;

  Stmt := Conn.NewStatementPrepared('SELECT * FROM users WHERE id=?', true);
  try
    Stmt.Bind(1, 42);
    Stmt.ExecutePrepared;
    while Stmt.Step do
      WriteLn(Stmt.ColumnUtf8(0));
  finally
    Stmt.Free;
  end;
end;

3.10. Migration from mORMot 1

Unit Mapping Summary

Type Mapping Summary

Backward Compatibility

By default, mORMot 2 provides type aliases for compatibility:

type
  TSQLRecord = TOrm;
  TSQLModel = TOrmModel;
  // etc.

Define PUREMORMOT2 to disable these and use only new names:

{$DEFINE PUREMORMOT2}

Next Chapter: Core Units (mormot.core.)*

Navigation