Skip to content
MSO CloudDocumentation

System architecture

On this page

In short#

A web app and a worker over Postgres, Redis and object storage; rules live in packages, tenant queries run in a database-enforced scope, and model calls pass through one package. Every organization runs the same build.

Production containers and storesBrowserOrg host or platform hostpeopleTraefik edge (external)Classifies the host before any page runs/oauth2, /.well-known to idp; rest to webOutside servicesVendor APIs, model providers, emailoutbound-only networkweb (2 replicas)Next.js 16, tRPCPlatform API v1launch, handoffidp sidecarOIDC issuerJWKS, token, logoutreads key table onlyworkerBullMQ queuesSchedulers, VN timeWebhook sweeparchive-workerBackup, restoreOwn DB identitypdf-browserHeadless renderPDF exports onlycubeSemantic layeroptional profileInternal network: no route in from outsidePostgres 16FORCE row-level securityWarehouse, outbox tablesauth_sessions, issuer keysRedis 7Queues, rate limits, cacheIssuer grants under own prefixObject storeUploads, backup archivesS3-compatible, never public
Production containers and stores. Cube is an optional profile; the data layer has no route from outside.

The box around it: System context.

Containers#

Container Role
apps/web Next.js App Router: server components for reads, client islands, one tRPC API
apps/worker BullMQ over Redis: named per-concern queues, schedulers pinned to Vietnam time; the minute sweep that delivers platform webhooks
Archive worker A second worker process for backup and restore, under its own database identity
apps/idp OIDC issuer sidecar: discovery, JWKS, authorize, token, end-session; reads only the signing-key table and asks web for the session
Cube Optional semantic-layer service, started with a deploy flag
apps/mcp-server Bridges MCP clients to the assistant's tools through the web app; in no production compose file
PDF browser Headless browser the web app drives for PDF exports
apps/ml Experimental Python workspace for offline prototypes; not a production service

The API takes named Zod input schemas over a superjson transport, one feature router per domain under a single root.

apps/web also serves /api/platform/v1, the internal routes the issuer calls (/api/internal/idp/*, guarded by a bearer token) and the launch and handoff routes. The web service runs one replica, and a rolling deploy briefly scales it to two behind the proxy. Design: App family and identity hub; contract: Platform API and events.

Workspace packages#

Package Owns
@yng/schema Drizzle model, migrations, RLS policy SQL, runtime privilege manifest
@yng/metrics Metric definitions, materializers, decision-engine math
@yng/connectors-* One package per source, plus a shared core for mapping templates and transforms
@yng/ai The only path to a language model
@yng/plugin-host Plugin and domain registries
@yng/ui, @yng/charts, @yng/i18n Presentation: component kit, ECharts theme, copy
@yng/crypto, mask, notify, storage, exports, alerts Cross-cutting concerns
@younetgroup/platform-contract Claims, Platform API, webhook and logout schemas shared with connected apps

Request lifecycle#

Request path: one organization is pinned before any query runsBrowserRSC or tRPCAuthRLS scopePostgres1request on org host2resolve session once3org from host, brand4pin org and brand5queries under RLS6this org's rows only7commit or roll back8RSC payload or JSON

The organization comes from the host, not the cookie. The procedure wraps the whole resolver in one transaction carrying the tenant pin, so every query it makes is already scoped; the data assistant follows the same path and re-pins the scope on each tool call. Mechanism: Tenancy and security. First-party data then moves through Bronze, Silver and Gold, and asynchronous work is an outbox row committed with its business row: Ingest pipeline.

Composability#

What an organization sees is decided by rows read at request time:

Mechanism How it works Fails how
Plugins Declarative manifests in a compiled catalog; features and connectors alike A malformed manifest fails the build
Enablement A written row per organization; dependencies resolve to a fixed point Turning off a parent turns off its children
Pillars Six, derived per request from enabled plugins plus a commerce data probe Empty result when the owning plugin is off
Navigation Plugin, pillar, role policy, hidden items, then order and labels Hiding is never enforcement; pages guard
Widgets One registry declares every widget type; other lists derive from it An unclassified report page fails the build

Contract: Plugin development.

AI layer#

Concern Rule
Configuration Per organization: ordered connections, each with ordered models; keys in AES-256-GCM envelopes
Own keys A bring-your-own-key organization never falls back to platform credentials
Failover One resolver, one chain; only prompt and type validation errors are fatal
Streaming Fails over only before the first content token
Prompts Named slots overridable per industry; output language re-pinned on every resolution
Anti-fabrication A sentence with a numeral not bound to a supplied fact is dropped, never rewritten
Truncation A non-streaming completion is never cached or published without a truncation check
Usage Tokens and cost written to a per-organization ledger in integer units

A drafting model proposes shape, never a threshold.

Observability#

Job processors log structured records (job, connector, organization, duration, row counts) and classify every failure as permanent or transient. A vendor rate limit parks the connector as degraded instead of alerting, platform-infrastructure alerts reach super admins only, and the audit log is append-only. The gates each change passes: Quality gates.

Where it stops#

Plugins are compiled into the build and toggled per organization; there is no dynamic or third-party plugin loading. The platform recommends and records; it does not act on marketplaces or ad accounts. Readiness per capability: Project status.

Decisions#

Decision Why Enforced by
Rules, schemas, formatting and connectors live in packages; apps/web routes and renders Logic in a page gets reimplemented by the worker and assistant, and the copies drift Bundle-boundary audit, ratcheted per-route JS budgets, single-source metric audits
Every optional feature and connector is a manifest in one compiled catalog Hand-kept visibility lists drift from entitlement: hidden paid features or exposed ones Strict schema parsed at load; validity audit (ids, both locales, acyclic dependencies)
@yng/ai is the only path to a model: one resolver, one failover implementation A second path skips the org's key, failover order, truncation guard and name hiding Single-source audit, truncation-guard audit, copy audit on vendor and model names