Skip to content

Architecture Overview

Status: I1-B1 topology accepted; remaining technology choices pending

Logical architecture

flowchart TB
    subgraph experience["Experience"]
      MS["Managed Site App"]
      CS["Custom Sites - Custom Plan only"]
      TA["Tenant Admin App"]
      PA["Platform Admin App"]
    end

    subgraph api_runtime["Initial API Runtime"]
      PUB["Public API"]
      TEN["Tenant Admin API"]
      PLA["Platform Admin API"]
      WH["Webhooks"]
    end

    subgraph application["Modular Backend Application"]
      APP["Application Boundary"]
      P["Platform"]
      C["Capability"]
      CO["Commerce"]
      S["Site"]
      R["CRM"]
      M["Marketing"]
      CH["Channel & Advertising"]
      F["Finance"]
      I["Integration"]
      O["Operations"]
      L10N["Internationalization"]

      APP --> P
      APP --> C
      APP --> CO
      APP --> S
      APP --> R
      APP --> M
      APP --> CH
      APP --> F
      APP --> I
      APP --> O
      APP --> L10N
    end

    subgraph worker_runtime["Background Worker Runtime(s)"]
      W["Asynchronous Jobs / Consumers"]
    end

    MS --> PUB
    CS --> PUB
    TA --> TEN
    PA --> PLA

    PUB --> APP
    TEN --> APP
    PLA --> APP
    WH --> APP

    APP --> W

Infrastructure technologies are added only as their I1-B gates are accepted.

Accepted persistence infrastructure (I1-B3): PostgreSQL 18 + PostGIS 3.6.x, TypeORM 1.x with the pg driver, per-engine PostgreSQL schemas, UUIDv7 identifiers, schema-controlled JSONB, and tenant isolation through application scoping plus PostgreSQL RLS.

Accepted application topology — I1-B1

Backend

touriffique-bend
├── one API runtime initially
├── background worker runtime(s)
└── modular engine/domain application

The API and worker runtimes share the same backend repository and application/domain code. Workers may be deployed/scaled independently.

No engine is required to be a network microservice at launch.

API surfaces

The initial API runtime contains explicit logical/security surfaces:

/api/public/v1
/api/tenant/v1
/api/platform/v1
/webhooks

They may later be split into independently deployed API runtimes if operational evidence warrants it.

Frontend

touriffique-fend/
├── apps/
│   ├── tenant-admin/      # independently deployable
│   ├── platform-admin/    # independently deployable
│   └── managed-site/      # independently deployable
└── packages/
    └── shared frontend capabilities

Tenant Admin and Platform Admin are deliberately separate applications rather than one privilege-switched administrative SPA.

The exact framework, workspace/build tooling and Managed Site rendering topology remain later technology decisions.

Custom sites

Custom/headless tenant-specific implementations live outside the core touriffique-fend repository when a bespoke frontend repository is required. They consume Touriffique public/headless API contracts.

Engine ownership rule

An engine owns its authoritative domain state and exposes deliberate commands/queries/events/contracts to other engines.

Cross-engine direct persistence access is forbidden at the application layer merely because modules share a process or persistence deployment.

Cross-cutting internationalization

Internationalization remains a platform-wide invariant. Every application and engine must preserve the frozen locale contracts regardless of the concrete libraries selected later.