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.
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 | noUnchecked, 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/ |
6 | One theme, shared VND and Vietnam-time formatters |
@yng/ over the Vercel AI SDK |
7 | Provider-agnostic per organization, one failover chain |
@yng/, AES-256-GCM |
— | Envelope encryption; versioned keys, rotation never invalidates old data |
@yng/ |
— | 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/ |
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.
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 |