Portal platform — product requirements

Three tenant types: riversync (RiverSync users) · customer · partner.

One organization can hold the partner and customer roles at once (e.g. Nera services customer devices and runs RiverSync units of their own).

The riversync tenant manages no organization — unlike customer and partner tenants, it has no org profile, users-and-sites administration of its own in the Account portal. It carries the tenant's user accounts only; staff work in the Admin and Operations consoles and act inside customer tenants via audited view-as sessions.

A user account belongs to exactly one tenant — never several.

One email address may hold a separate account per tenant. Sign-in offers an account chooser when an email resolves to more than one account.

Identity providers: Google · Microsoft · LinkedIn · email & password. Org-level SSO: Microsoft Entra ID.

Sessions are federated — one RiverSync ID moves between every app the account is entitled to without re-authentication.

Every user holds a role per application (e.g. Account: Member, Portal: Administrator).

Partner and riversync apps are membership-gated: Partners requires a partner-tenant account; Pipeline, Admin and Field require a riversync-tenant account (Field additionally to the engineer role). Gated apps never appear in the product switcher of an unentitled account.

Access surfaces: User detail → Application access · Users list "Apps" column · Roles page (role definitions) · Permissions page (per-application matrix).

The riversync tenant's Account portal carries no organization management — no organization overview, departments, sites, partners, billing or invoices (TEN-3). Its users are managed like any tenant's — the standard Users, Roles and Permissions surfaces behind the tenant's overview landing; user accounts carry nothing staff-special.

Default role set of the riversync tenant: admin · support · sales · accounting · engineer — ordinary roles in the standard role model, owned by the tenant exactly as customer and partner role sets are.

Removed in v0.13. There is no separate multi-role riversync mechanic — riversync accounts follow the standard model (AUTH-1): one role per application. admin is the tenant's fixed full-permission role, the customer-Owner analogue.

Roles are configurable on the standard Roles and Permissions pages — the same surfaces every tenant uses — over the riversync tenant's own permission catalog (tenants & provisioning, support & service, sales, billing & accounting, device operations, user management). The admin column is fixed: always every permission.

A customer can be linked to many partners at once. A link exists because that partner sold the customer devices or holds an active maintenance agreement on at least one of them. Agreements are per device — a partner link aggregates every device that partner covers.

Each device carries its own agreement period. Every device renews on its own schedule; at renewal the customer can move that device to a different partner, whose access starts with the new period.

The customer controls each partner's access scope — telemetry, service tickets, sites & visit info, invoices & agreements, optionally limited by region — and can change or revoke it at any time, effective immediately.

Every partner action lands in the customer's audit log, attributed to the partner organization.

Maintenance agreement tiers: Silver (8×5, next business day) · Gold (24×7, next day). Reseller program tiers (reseller subtype only — see PRT-14…17): Authorized · Gold · Platinum.

RiverSync is the manufacturer and platform owner, never a partner. Factory telemetry and engineer dispatch are on by default for every device — RiverSync does not appear in a customer's partner list and this access is not customer-managed, though every action is still audited.

The customer manages each link through a partner detail page — Devices (every covered device with its own agreement, tier and renewal), Access (scope controls) and Activity (the partner's audited actions). The partner list itself stays light: organization, partner tier, scope, status.

No self-links. An organization never appears in its own partner list — a tenant holding both partner and customer roles (e.g. Nera) keeps them separate, and a partner link can only exist between two different tenants.

Every partner organization is exactly one subtype, platform-wide: distributor or reseller. The subtype lives on the partner profile beside the program tier and is set by RiverSync users — never self-selected, never both at once.

Resellers source through distributors under registered distribution agreements. The reseller ↔ distributor relationship must be registered on the platform to count; a reseller can hold several at once (e.g. per region or product line), and only distributors holding an active agreement are selectable when the reseller registers a deal. Never between the same organization.

The channel is decided per deal. A reseller-registered deal routes through exactly one distributor — chosen by the reseller from its registered distributors, or allocated by RiverSync — or goes direct to RiverSync under a per-deal exception granted by staff case by case (no standing direct flag per partner). RiverSync can overrule and reallocate any deal to another distributor as it sees fit; every channel change is audited.

A partner's other tenant roles are never disclosed to a customer. When a customer views a linked partner — partner list, partner detail, audit log, invitations — the surface shows only the partnership itself: organization name, program tier, access scope, status, covered devices and the partner's audited actions. The fact that the same organization also holds a customer (or any other) tenant role — as Nera does — is never surfaced to the customer. Each tenant relationship is visible only inside its own context: dual-role membership is disclosed only to the organization's own members and to RiverSync.

A distributor sees the whole pipeline of the resellers it handles — every registered deal and its stage — but deal value and quote details are masked on deals not channeled through it (direct deals and deals routed via another distributor). Partners get this funnel inside the Partners app; the Pipeline app stays staff-only (AUTH-2) and shows the full channel chain on every deal.

The program tier is a reseller-only attribute. Authorized · Gold · Platinum (ordered Authorized < Gold < Platinum) live on the partner profile and apply only when the subtype is reseller. A distributor carries no tier — it is a distinct partnership RiverSync grants directly and reviews on channel performance, not a rank on this ladder. Tier is RiverSync-set, never self-selected.

A reseller's tier gates its capabilities in the Partners app, resolved by one tier→entitlements map: concurrent registered-deal cap (Authorized 5 · Gold 20 · Platinum unlimited), pricing level on quotes (list · −8% · −15%), deal-registration protection window (30 · 60 · 90 days), RiverSync lead sharing (Gold and above), direct-from-RiverSync exception eligibility (none · by request · Platinum streamlined), co-marketing (assets · MDF · full) and early / beta hardware access (Platinum). The channel-and-agreement model (PRT-1…12) is unaffected by tier.

Tier qualification is a balanced scorecard RiverSync reviews and grants. Three pillars — certifications (certified engineers on staff), revenue (trailing-12-month closed-deal volume) and service quality (customer satisfaction, on-time SLA). A reseller is eligible only when every pillar meets the next level's thresholds; RiverSync reviews eligible resellers at a quarterly channel review and grants the tier, recorded as a tier-review with a grant · hold · downgrade decision. The reseller sees its progress only — it never sets its own level; benefits unlock the day the tier is granted, and the tier never changes without a recorded review.

RiverSync may convert a reseller into a distributor — a manual, RiverSync-initiated subtype change, typically for a strong Platinum reseller with the logistics, volume and regional coverage to supply others. On conversion the organization's program tier is cleared (a distributor holds no tier, PRT-14), its open reseller-attributed deals are reconciled under RiverSync supervision, and RiverSync registers the distribution agreements (PRT-10) that make it a distributor. The change is audited and never self-initiated; the organization keeps any separate customer-tenant role it holds.

RiverSync products are organized into families, each with a product class: frigo and koelkast are edge micro data centers; nevera is the modular micro data center line — a separate, newer line. A family is a product line, not a single unit.

Each family holds one or more models — Frigo 20 · Frigo 30, Koelkast 20 · Koelkast 30, nevera-30 · nevera-40. The model is a catalog entity, not a free-text field — every device and every quote line references a model, so a device's product identity is unambiguous and reportable. For frigo / koelkast the model number is the unit's usable rack height (20U / 30U) with paired fixed capacity; for nevera the model names the chassis form factor (30U / 40U) and the makeup is the configuration beneath it (PRO-7).

Devices across the fleet emit telemetry in several distinct shapes. The platform maintains a telemetry-schema registry of these shapes: refrigeration is the established 60-field schema (family #1); the others were discovered from the live fleet (a fixed-width 15-digit form, a dashed four-segment form, and an unknown bucket). Each product model declares the schema family it speaks.

Every device is classified: its IoT-Hub identity resolves to exactly one schema family + version, with a confidence score. This resolution is the single join that makes a device's telemetry readable and storable in the right shape — the model declares the expected schema, the classification is ground truth.

Classification never guesses silently. A low-confidence match goes to a needs-review queue for a RiverSync user to confirm or correct; an unrecognized shape is quarantined, not dropped — so no device's data is lost just because its family is not yet modeled.

Telemetry is stored per family in a typed store with a JSONB escape hatch for rare fields; the time-series data lives outside the relational model (it shares the PTL-1 boundary). A new family or a schema version is additive — registered, never destructive to existing data.

The nevera line is configure-to-order. A unit is a chassis (30U or 40U) populated with modules chosen from a compatible catalog. The catalog models, beneath the model, a module catalog and configuration rules, and a device records its as-built module loadout, not only its model. frigo and koelkast remain fixed-configuration models; configurability is a nevera-introduced capability of the catalog.

Modules are catalog entities. Two kinds: controller modules — CM1V (master, required) and slaves CS1V · CS1F · CS2F · CSVF, each with a compressor mix and a rack constraint — and cooling modules — six SKUs across inverter (2500V · 3500V) and fixed (1500F · 2000F · 2500F · 3500F), each with rated capacity (W / BTU), coils and power draw. Every module is a priced, serial-tracked catalog item; quote lines and the device loadout reference its SKU, never free text.

Configuration rules are catalogued and enforced at quote time and at provisioning: a master controller (CM1V) is required; per-chassis cooling-module ceiling (30U: max 2; 40U: max 3); redundancy class (30U: N+1; 40U: N+2); max 2 inverter modules either chassis; CS2F and CSVF are 40U-only; capacity envelope base 2,500 W, max 5,000 W (30U) / 7,500 W (40U) — the RiverSync-confirmed system maxima. An invalid combination is rejected, not silently accepted.

Pay-as-you-grow: the loadout is mutable across the unit's life. Cooling and controller modules are added or swapped in the field as demand grows, within the chassis ceiling. The platform tracks installed vs maximum capacity (headroom); every loadout change is an audited event that may originate as a Pipeline expansion quote and complete as a Field install visit. The chassis (model) is fixed for the unit's life; the configuration is not.

Telemetry reflects the loadout. A nevera is a multi-controller system — each cooling module has its own controller, a master (CM1V) synchronizing slaves — so the telemetry a device emits scales with its installed modules (N controllers under one device identity). Classification (PRO-4) still resolves the device to one schema family + version; the modular composition is read within that family, not as a separate family.

frigo and koelkast are fixed-configuration edge micro data centers. Each unit is a single sealed enclosure whose cooling capacity is set by its model — no module catalog, no loadout, no field expansion. They are the non-modular counterpoint to nevera (PRO-7): a device record carries only model + serial, never an installed-module list.

Model numbers encode usable rack height; the family axis is the compressor. Frigo / Koelkast 20 = 20U · 2,500 W, 30 = 30U · 3,500 W — same capacity points in both families. frigo and koelkast differ by compressor type: frigo = fixed-speed screw, koelkast = inverter variable-speed (load-modulating). Catalog stores UsableRackUnits, CoolingCapacityWatts, CompressorType per model.

Both edge families speak the refrigeration telemetry schema (family #1, the established 60-field shape — PRO-3), each a single-controller system. The koelkast inverter reports variable compressor speed / modulation the frigo fixed-speed screw does not exercise — within the refrigeration family, never a separate family.

Service is keyed to the model and differs by compressor. With no loadout to track, a frigo / koelkast Field visit is a service visit, never a configuration-change visit (contrast PRO-10); wear parts and compressor-service procedures differ between the fixed-speed screw (frigo) and inverter (koelkast) lines.

Only 2nd-generation frigo / koelkast models are supported online. Frigo 20 / 30 and Koelkast 20 / 30 are the supported catalog; the 1st-generation capacity-named units (frigo 2500 / 3500, koelkast 4500 / 5500) are legacy and unsupported — they do not onboard, classify, sell or report on the platform (a 1st-generation identity is out of scope, not a quarantine case).

Centralized contact management — the relationship graph. We keep one record of every person and company we deal with: a Contact of kind organization (a legal entity) or person (a human). Organizations form a group-of-companies hierarchy (parent ⇄ subsidiaries); a person has an employer organization and a manager (the reporting line); and a general relationship graph captures the wider network (influences, introduced-by, advises). The graph is queryable top-down so we can deep-dive a prospect and drive the sale.

The contact graph is distinct from tenancy. It records prospects and the wider buying network — parties that need no login and are not billed — and is never merged with the operational Tenant / Organization / ApplicationUser model. A contact bridges to that model only on conversion: an organization contact may link to a customer Tenant, a person contact to a user account. An unconverted prospect lives wholly in the graph.

The lead is the single inbound front door. Every net-new inquiry enters as a Lead raised off a contact, owned by a RiverSync sales user; we qualify it, then either convert it (SAL-5) or disqualify it. A renewal or direct opportunity RiverSync opens itself is the only exception.

Leads carry their source. One of six: online registration form, telephone, showroom walk-in, trade show, social network, or partner referral. Trade-show and social leads may attach to a marketing Campaign for attribution; deeper marketing automation is out of scope — we model attribution, not a marketing suite.

A lead converts to an opportunity, not straight to a deal. Conversion resolves the customer — matching an existing customer organization or creating one (joining hands with customer onboarding) — and opens an Opportunity. It is one-way and recorded; the lead is never re-opened.

The opportunity is where the deal is shaped. It holds one or more variants — quantified configurations (models, quantities, maintenance tier) we compare — and the customer-validated variant is confirmed into a Deal, which carries §5's channel and proceeds to quote and close. The deal is the committed, quotable commitment; the exploratory, multi-option work lives on the opportunity.

RiverSync can share a lead or opportunity to a partner. Assigning it hands follow-up to that partner — gated by the partner's program tier (lead sharing, PRT-15); the partner works it in the Partners app and, on a win, registers the deal through its channel (PRT-11). This reuses the existing tier benefit, not a new mechanism.

Every touch is logged on one activity timeline. Emails, calls, visits, surveys, meetings and notes are logged as activities against the contact and, where relevant, the funnel stage. A contact's timeline blends these human-logged touches with the journey's own milestones (lead captured … deal won) into one navigable, bird's-eye history — distinct from the immutable audit trail and from support messaging.

One unified communications inbox feeds the funnel. Every inbound and outbound message we exchange with a contact — across the web contact form, email (sales@riversync.com), and the social channels LINE, Instagram, Facebook and LinkedIn, plus logged phone calls — is centralized in one threaded inbox, organized into the folders Inbox · Draft · Sent · Archived · Junk · Deleted. A conversation is one thread on one channel, anchored to the contact it came from and optionally to a funnel record (lead / opportunity / deal / quote); sending or receiving a message also writes an activity (SAL-8) so the blended timeline stays the single bird's-eye history. This is the sales communications layer — distinct from customer↔support messaging — and lets a sales user move straight from a message to the relationship and its activity.

Soft-delete by default. Audited business records are retired by a terminal status (closed · expired · decommissioned · cleared · lost) and retained for audit and history; hard delete is reserved for non-audited config and the audit trail's retention purge, and is blocked while a row is still referenced.

Every state change is an audited, event-bearing transition. Create, update and retire each emit a past-tense domain event the audit trail consumes; a terminal state may still reopen or renew through an explicit, recorded transition — never a silent edit of history.

Write authority follows ownership. Derived records (the partner link and its access grant) are written only by their owning service from events, never by API; offline field captures are insert-only from the Field app and immutable once a visit is signed off.

Reference and config catalogs are curated, not destructively deleted. Type catalogs, the maintenance-tier and product catalogs, plans and the permission catalog are admin-managed; a row still in use is re-pointed or deactivated rather than deleted, and cross-boundary cleanup is event-driven, never cascaded.