Skip to content
MSO CloudDocumentation

Technology and deployment

On this page

In short#

MSO Cloud is one TypeScript stack deployed as a self-hosted container stack: a stateless web app and workers in front, Postgres, Redis and object storage behind them on a network with no route in from outside.

IngressTLS, tenant hostsReverse proxyPlatform host and every tenant subdomainWeb and APIStateless replicasNext.js 16App Router, ServerComponentstRPC 11 and Zod 4Typed boundary,superjsonNextAuth v5Passkeys, TOTP,LDAP, OIDCShared packagesBusiness rules@yng/metricsOne definitionper metric@yng/aiPer-organizationfailover chain@yng/chartsECharts 6,one theme@yng/cryptoEnvelopeencryptionWorkersBullMQ 6WorkerSync, AI, alerts,reports, rollupsBackup workerArchive and restore,own identityHeadless browserPDF export,low priorityData layerNo internet routePostgres 16FORCE row-level securityRedis 7Append-only fileObject storageS3-compatible

Each layer is chosen against a constraint the platform must hold: many tenants in one database, exact VND amounts, and one metric definition shared by dashboards, the data assistant and alerts.

Stack and versions#

Major versions pinned in the repository:

Technology Version Why
Node 26 One language from browser to worker
TypeScript, strict 6 noUncheckedIndexedAccess, no any
pnpm, Turborepo 12, 2 One workspace, cached task graph
Next.js App Router, React 16, 19 Read-heavy dashboards render server-first
tRPC, Zod, superjson 11, 4, 2 Typed boundary without code generation; Date and bigint survive the wire
Postgres, Drizzle ORM 16, 0.45 Tenancy enforced inside the database with FORCE row-level security
BullMQ on Redis 6, 7 Durable, idempotent, rate-limited jobs
NextAuth, WebAuthn, TOTP, LDAP, OIDC 5 pre-release Platform sign-in plus per-organization directory login
ECharts through @yng/charts 6 One theme, shared VND and Vietnam-time formatters
@yng/ai over the Vercel AI SDK 7 Provider-agnostic per organization, one failover chain
@yng/crypto, AES-256-GCM — Envelope encryption; versioned keys, rotation never invalidates old data
@yng/i18n — Vietnamese is the source of truth, English in key parity

Why each layer#

Choice What it buys
Server Components Small shipped JavaScript; heavy helpers load on click; per-route budgets
FORCE RLS, non-bypass roles A policy per organization-scoped table, a brand leg where partitioned; grants from one default-deny manifest
BullMQ Watermarks advance only on success, content-hash dedupe, one dead-letter, shared per-marketplace token bucket
Directory login Bind fails closed, encrypted transport by default, email matching without auto-create, restricted outbound
Envelope encryption Each write stamped with its key version; a key retires only after a proven rewrap
Medallion warehouse Bronze keeps raw bytes; a transformer fix replays from Bronze without calling the vendor again
@yng/ai One resolver and one failover primitive; failover only before the first content token

Schedulers are declared in code and pinned to Vietnam time; Redis persists with an append-only file, so queued jobs survive a restart. Detail: Tenancy and security, Ingest pipeline, System architecture.

Runtime topology#

Component Behaviour
Ingress Terminates TLS, routes platform and tenant hosts to web; never routes to the data layer
Web No local state, read-only filesystem; one replica, and a rolling deploy starts a second that joins after its health check
Issuer sidecar OIDC issuer for connected apps; reads signing keys under its own SELECT-only role; started with a deploy flag
Cube Optional semantic-layer service, started with a deploy flag
Worker Connector sync, AI tasks, alerting, scheduled reports, materialization
Archive worker Archive and restore under its own database identity, staging on a disk volume
Headless browser Dashboard and deck PDFs on a low-priority path; internal protocol endpoint, outbound network for page assets
Data layer Postgres 16, password-protected Redis 7 and S3-compatible storage on an internal network with no internet access

Application containers reach vendor APIs and model providers over a separate outbound-only network. Web and worker hold no durable state and can be replaced without data loss; Postgres, Redis and object storage are the only places state persists. Tenant isolation is enforced by the database on every query, not by network segments or a database per tenant, so it holds the same on one node or many. An organization archive excludes secret material by construction.

Deployment#

A deployment is a versioned compose template plus one environment file. A placeholder or missing security-relevant variable stops the deploy instead of falling back to a default; a live compose file whose rendered topology differs from the tracked template is refused.

1 · Validateenv placeholders, security vars,topology vs tracked templatestop: stops on drift2 · Preflightproxy network present,60 GiB free for imagesstop: refuses before building3 · Buildone image per command:migrate, web, worker, archive, pdfstop: build error stops4 · Data planePostgres, Redis, storage up,never recreated herestop: health timeout stops5 · Migratemigrations, RLS, ledger guards,roles and grantsstop: fails: old code serves6 · Adminintended super admin validated,create-onlystop: placeholder email stops7 · Rolling webnew replica beside the old;healthy, then old drainedstop: never healthy: removed8 · Backgroundworker, archive, PDF browser,issuer if enabled; in placestop: queued jobs wait in Redis9 · Healthevery container healthywithin the timeoutstop: timeout stops10 · Templatesplugins, templates, alerts,CDN warm, cache reclaimstop: cannot fail the deploythe running application is untouched up to hereA deployment is one tracked compose template plus one environment file; the live file is never edited in place.
One deploy, in order. Everything before 'Rolling web' leaves the running application untouched; a failed new replica is removed and the old one keeps serving.

With the issuer flag, the script enables the issuer database role after migrate, creates the first signing key and starts the sidecar after web already serves the new token. After the health check it disables org alert rules nobody configured, fills the CDN edge with the new hashed assets and verifies the cache headers. The migrate step applies migrations, the row-level policies, the append-only ledger guards and the runtime roles with their grant manifest; in production a missing role artifact fails the step rather than warning. After the new web replica is healthy, plugin-installation rows are reconciled from each organization's shape. A refusal, including one that would switch off an active credential's connector, is tallied without failing the deploy; that organization keeps its current rows. The operator can rerun the reconcile command for those organizations.

Self-hosted posture#

Application, database, cache and object storage run on infrastructure the platform administrator controls; no third-party application platform serves the product, and no third-party analytics or telemetry is embedded. Outbound calls are a declared set: transactional email, each organization's chosen model providers, connected data-source APIs, and enabled notification transports. A single deployment co-locates compute and data today, and PDF output does not follow the organization's skin; readiness of optional components and the scaling direction are on Project status.

Where it stops#

The stack describes one self-hosted deployment. A multi-node cluster is a proposal, not the deployed topology. Readiness per capability: Project status.

Decisions#

Decision Why Enforced by
All tenants share one database; row-level security separates them Per-tenant databases or networks multiply migrations and leave isolation to configuration drift The tenancy gate in CI against a freshly migrated database, as the non-bypass runtime roles
Topology comes from one tracked template and one environment file A hand-edited host runs unreviewed configuration; a defaulted security variable ships a weak secret Compose verification in CI and before every deploy; the security scan refuses defaulted secrets
Sync, materialization, AI, archive and PDF work run off the request path A request waiting on a vendor or a render holds a connection and tenant scope An outbox audit, a heavy-import audit, and per-route JavaScript budgets ratcheted in CI