Technology Baseline¶
Status: Proposed — requires explicit acceptance before implementation freeze
The choices below optimize for the team's TypeScript/NestJS/React capability, SEO-heavy public sites, relational transaction correctness and incremental migration.
| Layer | Proposed technology | Rationale |
|---|---|---|
| Language | TypeScript | Shared backend/frontend language and strong contracts |
| Backend | NestJS | Modular application architecture, guards/providers, OpenAPI, queues/integration friendliness |
| Architecture | Modular monolith initially | Lower operational complexity; explicit extraction boundaries |
| Primary DB | PostgreSQL | Relational transactions, JSONB where appropriate, indexing, RLS option |
| ORM/data access | Prisma or TypeORM decision gate before implementation | Both viable; freeze after prototype of tenancy, JSONB and transaction needs |
| Cache | Redis | cache, rate limits, ephemeral coordination |
| Jobs | BullMQ + Redis | asynchronous jobs/retries/delayed tasks |
| Tenant/Platform Admin UI | React + TypeScript (Vite or equivalent) | Fast SPA admin workflow |
| Managed public sites | Next.js + React | SSR/SSG/ISR options, SEO, routing and React component library |
| Custom sites | Client-selected frontend, contractually scoped | Decoupled frontend only under Custom plan |
| API specification | REST + OpenAPI 3.1 first | predictable public contracts/tooling; GraphQL not required initially |
| i18n standards | BCP 47 locales + ICU/CLDR-compatible formatting | interoperable locale identifiers and mature plural/date/number formatting semantics |
| Object/media storage | S3-compatible object storage | portable media abstraction |
| CDN/domain edge | Provider adapter; Cloudflare-class edge proposed | custom domains, CDN, TLS, WAF capabilities |
| Search | PostgreSQL search initially; external search engine when justified | avoid premature infrastructure |
| Observability | OpenTelemetry + structured logs + metrics/tracing backend | vendor-neutral instrumentation |
| Testing | Jest/Vitest, API integration tests, Playwright E2E | boundary + browser parity coverage |
| Containers | Docker | repeatable local/prod deployment units |
| CI/CD | GitHub Actions proposed | repository-centric validation/build/deploy |
Technology decision gates¶
Before implementation freeze, explicitly decide:
- Prisma vs TypeORM/data-access approach;
- authentication implementation/provider strategy;
- deployment/cloud target;
- edge/DNS/TLS provider;
- payment providers for launch;
- secrets-management provider;
- analytics/observability backend;
- managed-site rendering/deployment topology;
- concrete localization library/tooling for NestJS, admin React and managed Next.js while preserving BCP 47/ICU contract semantics.