Skip to content

Technology Decision Baseline

Status: I1-B IN PROGRESS
Foundation dependency: Foundation v1.0 FROZEN

Technology decisions are frozen incrementally. A row marked Accepted is authoritative. A row marked Proposed is only a candidate until its named gate is explicitly accepted.

Decision-gate status

Gate Decision area Status
I1-B1 Application architecture & repository topology ACCEPTED — 2026-09-21
I1-B2 Backend runtime/framework & package strategy ACCEPTED — 2026-09-21
I1-B3 Persistence / database / ORM / migrations / tenant isolation ACCEPTED — 2026-09-21
I1-B4 Authentication, authorization & identity implementation ACCEPTED — 2026-09-21
I1-B5 Cache, queues, events & background processing Pending
I1-B6 Frontend application architecture/tooling Pending
I1-B7 Managed Site runtime & rendering/deployment model Pending
I1-B8 API contracts & generated clients Pending
I1-B9 Internationalization implementation stack Pending
I1-B10 Media/object storage & search Pending
I1-B11 Integrations, secrets & payment-provider architecture Pending
I1-B12 Observability, auditing & analytics Pending
I1-B13 Infrastructure, hosting, edge, DNS & CI/CD Pending
I1-B14 Testing strategy & quality gates Pending
I1-B15 Consolidated technology baseline freeze Pending

Accepted I1-B1 decisions

Repository topology

DataKYND/
├── touriffique-bend
├── touriffique-fend
└── touriffique-docs

No separate contracts repository is created initially.

Backend application topology

  • modular monolith initially;
  • explicit engine/application boundaries;
  • one API runtime initially;
  • separately deployable background worker runtime(s) from the same backend repository;
  • no engine is required to be a launch microservice;
  • later extraction requires demonstrated operational/organizational justification.

Frontend application topology

touriffique-fend is a workspace/monorepo with at least:

  • Tenant Admin — independently deployable;
  • Platform Admin — independently deployable;
  • Managed Site — independently deployable;
  • shared frontend packages.

Tenant Admin and Platform Admin are distinct applications, not one role-switched administrative application.

Custom sites

Bespoke Custom/headless tenant sites live outside the core platform frontend repository when a separate implementation is needed. They consume Touriffique public/headless contracts.

Contract ownership

The backend HTTP/API contract is authoritative. Frontend clients will be generated and/or validated from a machine-readable API contract. Exact standards/tooling are deferred to I1-B8.

Accepted I1-B2 decisions

The following backend stack choices are accepted for I1-B2:

Concern Decision
Runtime Node.js 24
Language TypeScript with strict mode
Framework NestJS 12
Initial HTTP adapter Express
Future extracted HTTP services Fastify preferred when services are independently deployed and HTTP-based
Package manager pnpm
JavaScript module format Native ESM

The Fastify direction is not interpreted as "all microservices use Fastify." Services that communicate over non-HTTP transports use the transport appropriate to their role. The rule is that the current modular-monolith HTTP runtime starts on Express, while future independently deployed HTTP services should prefer Fastify unless a concrete compatibility requirement argues otherwise.

Node/Nest major lines are frozen; normal compatible patch/minor/security upgrades within the accepted major line remain allowed unless they introduce a breaking platform constraint.

TypeScript strictness is mandatory for application code. Exact compiler flags beyond the strict baseline are implementation details unless a later quality gate promotes them to a formal requirement.

Accepted I1-B3 decisions

Persistence stack

Concern Decision
Primary database PostgreSQL 18
Spatial extension PostGIS 3.6.x
ORM TypeORM 1.x + @nestjs/typeorm
PostgreSQL driver pg
ORM style Data Mapper / repository style; Active Record / BaseEntity is not the platform pattern
Migration authority Explicit versioned migrations
Schema synchronization synchronize: true forbidden outside disposable local/test environments
Tenant model Shared PostgreSQL database/cluster; tenant-owned rows carry tenant_id
Tenant isolation Application-level tenant scoping + PostgreSQL Row-Level Security (RLS)
DB tenant context Transaction-local PostgreSQL tenant context, using SET LOCAL / set_config(..., true) semantics
DB privilege separation Tenant-scoped runtime credentials separated from privileged migration/platform access
Primary aggregate IDs UUIDv7
Flexible attributes Schema-controlled/versioned JSONB
Engine persistence ownership Separate PostgreSQL schemas per engine in one physical database initially
Point geospatial data geography(Point, 4326) by default for earth-distance/location points
Area/boundary geospatial data PostGIS geometry/geography chosen by operation; geometry(..., 4326) is the baseline for topology/boundaries
Spatial indexes GiST where spatial query patterns require them

Initial engine schemas

The initial logical schema ownership map is:

platform.*
capability.*
commerce.*
site.*
crm.*
marketing.*
channel.*
finance.*
integration.*
operations.*
i18n.*

These schemas are ownership boundaries inside one database, not separate services/databases. Application code must not use shared physical storage as justification for ad-hoc cross-engine repository access.

Cross-schema references needed for platform invariants such as tenant_id are permitted when deliberately modeled. General cross-engine reads/writes still flow through owned contracts rather than becoming arbitrary joins in application services.

Tenant isolation contract

Tenant-owned tables carry tenant_id and are protected twice:

  1. application/repository queries are tenant-scoped; and
  2. PostgreSQL RLS acts as defense in depth.

The runtime establishes trusted tenant context inside the database transaction/unit of work. Tenant identity is never derived solely from an arbitrary request body/query parameter.

Privileged migration/platform operations use separate credentials/paths and must never silently become the default tenant runtime connection.

Migration policy

Production schema state is migration-driven.

  • migration files are version-controlled;
  • PostgreSQL-specific SQL is allowed when required for RLS, PostGIS, indexes, constraints, triggers/functions or extension features;
  • destructive migrations require explicit rollout/backfill planning;
  • automatic ORM schema synchronization is not a production deployment mechanism;
  • engine schema ownership must remain visible in migrations.

UUID policy

UUIDv7 is the default identifier form for major platform/domain aggregates.

Opaque UUIDs remain authorization-neutral: possession of an identifier never grants access.

JSONB policy

JSONB is reserved for schema-controlled extensibility and provider/document-shaped data where relational columns would create artificial rigidity.

JSONB payloads must have an owning schema/version/validation contract. Transaction-critical canonical state is not moved into unvalidated JSON for convenience.

PostGIS policy

PostGIS is part of the baseline persistence platform.

For ordinary real-world locations and proximity queries, point data should normally use:

geography(Point, 4326)

Typical uses include properties, marinas, pickup/return points, meeting points and other physical locations.

Boundaries/service areas/geofences use an appropriate PostGIS geometry/geography type according to required operations; WGS84 / SRID 4326 is the default external coordinate reference unless a documented spatial requirement needs another projection.

Spatial query logic belongs in PostGIS rather than duplicated application-side Haversine implementations. Spatial indexes are added according to query requirements instead of indexing every spatial value blindly.

Accepted I1-B4 decisions

Authentication and identity

Concern Decision
Identity provider Keycloak 26.x
Human authentication protocol OpenID Connect / OAuth 2.0
Federation OIDC and SAML supported through Keycloak where required
Browser sign-in Authorization Code Flow + PKCE (S256)
Password/direct grant Forbidden for Touriffique applications
Implicit flow Forbidden
Realm strategy One Touriffique human-identity realm per environment; never realm-per-tenant
External identity mapping OIDC issuer + subject (iss + sub) mapped to a global Touriffique User
Identity-provider persistence Separate from Touriffique application schemas and migrations
Social/enterprise login Keycloak identity brokering/federation; exact launch providers deferred
Machine-to-machine auth OAuth 2.0 Client Credentials
Provider webhooks Provider-specific signature verification; not treated as human OAuth sessions

Keycloak authenticates principals. Touriffique remains authoritative for application identity, tenants, memberships, roles, permissions, scopes, customers, entitlements and business authorization.

Tenant records are not represented as Keycloak realms. Keycloak roles/groups are not the source of truth for Touriffique tenant authorization.

Touriffique identity model

The application identity hierarchy is:

External Identity (issuer + subject)
          ↓
Global Touriffique User
          ├── TenantMembership(s)
          ├── PlatformStaffAssignment(s)
          └── optional CustomerAccountLink(s)
                       ↓
              tenant-scoped CRM Customer

A global User represents an authenticated platform principal. A CRM Customer remains tenant-owned.

The same User can therefore:

  • be a Customer of several tenants;
  • hold staff membership in one or more tenants;
  • hold a platform-staff assignment independently of tenant membership.

Email address is not the primary identity key and must not be used as an automatic merge authority.

Authorization model

Touriffique authorization uses:

authenticated principal
+ active User state
+ active Tenant state
+ active TenantMembership / PlatformStaffAssignment
+ permission grant
+ resource scope
+ entitlement/capability state
+ domain policy
= authorization decision

Permissions are stable machine-readable capabilities. Roles are bundles of permissions, never hard-coded authorization branches.

Initial authorization is allow-only/default-deny. Explicit DENY grants are not part of the baseline.

Role assignments can be scoped to:

  • Tenant;
  • Business Unit;
  • Site;
  • Location.

Platform-staff authorization is separate from TenantMembership authorization.

Permissions and commercial entitlements are evaluated independently.

MFA

MFA is mandatory for:

  • Platform Administrators;
  • Platform Support;
  • Tenant Owners;
  • Tenant Administrators;
  • all other tenant staff accounts.

Customer MFA is optional initially.

Preferred factors are WebAuthn/passkeys, with TOTP as an acceptable fallback and recovery codes supported.

Sensitive operations may require step-up authentication when the implementation supports the required assurance context.

Browser credential handling

Durable refresh/session credentials must not be persisted in JavaScript-readable browser storage such as:

  • localStorage;
  • sessionStorage;
  • IndexedDB.

Privileged admin applications must use an architecture in which durable authentication credentials are protected from normal frontend JavaScript access. The exact BFF/server-session implementation is deferred to I1-B6.

Guest/customer flows

Guest enquiry, quote and eligible booking/checkout flows remain supported.

Anonymous/guest CRM records may later be linked to an authenticated User only through an explicit verified linking process.

Matching email text alone never authorizes an automatic customer merge.

Invitations

Staff membership onboarding uses one-time, short-lived, auditable invitations.

Invitation secrets are stored hashed where the application owns them. Acceptance requires authentication/identity verification before the membership becomes active.

Support impersonation

Support access uses explicit delegated/impersonation sessions.

Audit records preserve both:

  • the real actor; and
  • the effective subject/context.

Support impersonation never transfers or exposes another user's Keycloak credentials/session.

Current candidates — not yet accepted

The following remain proposals only:

Layer Current candidate Gate
Frontend language TypeScript I1-B6
Cache Redis I1-B5
Jobs BullMQ + Redis I1-B5
Tenant Admin UI React + TypeScript I1-B6
Platform Admin UI React + TypeScript I1-B6
Managed Site Next.js + React I1-B7
API specification REST + OpenAPI 3.1 first I1-B8
i18n standards/tooling BCP 47 + ICU/CLDR-compatible tooling I1-B9
Object/media storage S3-compatible object storage I1-B10
Search PostgreSQL-backed search initially I1-B10
Observability OpenTelemetry + structured telemetry I1-B12
Containers Docker I1-B13
CI/CD GitHub Actions I1-B13

Do not treat a candidate in this table as implementation authority until its gate is accepted.

Next gate

I1-B5 — Cache, queues, events & background processing