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:
- application/repository queries are tenant-scoped; and
- 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