RTOpacks Client Spine¶

Status: Canonical. Governs all module specs, brief work, and architectural decisions. Governance level: Position 1 in the standing-rules.md governance hierarchy. Above WS-PRODUCT-01. Where they conflict, the spine doc names a more foundational layer; WS-PRODUCT-01 governs product surface; this doc governs the substrate the product sits on. Last updated: 2026-05-27 (dispositional articulation added to § 1 — sentinel posture, no-weaponised-lock-in, interface-as-revelation; access-control fold-in to § 3; three-tier access-control model in § 7 replacing the prior two-layer model; pending-identity-work composition note. Per Phase 1/3 of the canonical articulation arc accompanying ADRs 020-023). Authors: Tim, with Claude as drafting partner.

1. What RTOpacks is, honestly¶

RTOpacks closes the loop between strategic decision and compliant execution at machine speed, in the Australian regulated training market.

It integrates three things no competitor combines: a deep historical substrate of regulatory, funding, and labour market data; a content and assessment engine (UCCA) capable of producing regulator-grade training material to the letter of the law; and an architecture that generates compliance audit evidence as a byproduct of operations rather than as a separate prep event.

The market RTOpacks operates in is structured by government regulation of supply and demand in the labour market via financial inducement. Government decides what training matters, allocates funds to make it happen, and the supply side — Registered Training Organisations — competes to capture that funding. The smart operators in this market are not selling education in the abstract; they are running the government-money business with an educational hat on, exploiting their RTO license as a strategic asset and cycling their scope as the funding and demand landscape shifts. Most operators do not see this game clearly and run their RTO by ego, content inertia, or operational habit. RTOpacks gives every operator the analytical clarity and operational capability that smart operators previously achieved only through rare individual brilliance.

The license is the moat. The substrate is the map. UCCA is the engine. The audit trail is the wake. RTOpacks is the ship that runs the route at full steam.

Trajectory¶

The trajectory of RTOpacks is to absorb the remaining operational surfaces of being an RTO — student management, integrated billing, attendance and progress, native LMS delivery for regulated training — into the closed loop. Each absorbed surface gains the same architectural properties as the existing modules: data flows into the substrate, audit evidence is generated as byproduct, intelligence informs strategic decisions about it. The endpoint is the complete operational footprint of a compliant RTO running on one integrated substrate, replacing the current market reality of multiple disconnected vendors glued together with manual reconciliation.

RTOpacks is not competing on features. It is competing on architectural coherence in a market structured around fragmentation.

The "RTOpacks didn't start here" note¶

RTOpacks originated as a proof-of-concept for the UCCA content engine. It has matured into its own operating product addressing a distinct market need: the operational machinery a regulated training organisation requires beyond content production alone. RTOpacks and UCCA Inc share corporate ownership and the engine technology. They are not parent and child in a product hierarchy. If ucca.online ever materialises as a separate universal-capability-certification product, it is a sibling, not a parent. RTOpacks does not depend on UCCA's broader thesis to succeed; it serves its own market on its own merits.

Why architectural discipline matters specifically here¶

RTOpacks is operated by a team of three (Tim, Alex as engineering execution agent, Claude as architectural advisor). A three-person operation has a hard upper bound on how much substrate complexity it can hold in human memory. The architectural disciplines articulated across this doc and the companion architecture-decisions.md are not aesthetic preferences — they are operational necessities. The substrate has to broadcast its own structure because the operators cannot document the substrate fast enough to keep up with its growth.

Every named pattern, every canonical doc, every modular consolidation, every visualised map is a small extension of the substrate's ability to operate itself. Together they extend the team's ability to operate at the scale the substrate is heading toward.

The sentinel posture¶

The architectural disciplines articulated above produce a substrate with a specific disposition — the way RTOpacks holds itself in relation to the customer and the market. Naming this disposition matters because every downstream design decision, at every layer from substrate schema to interface behaviour, is tested against it.

RTOpacks is not a product the customer activates. It is substrate that exists in its own right — attentive to the regulated training domain, growing continuously through ingestion, generating intelligence and evidence as byproducts of its operation. The substrate existed before any particular customer arrived and continues to exist whether they are present or absent. A customer signing up does not create their substrate; they enter substrate that already knows about them (a Type 1 RTO arrives to a client file auto-populated from regulator data; the substrate recognised them before they recognised the substrate). A customer leaving does not collapse their substrate; their state persists, their work is preserved, their seat is held warm.

This is the sentinel posture: present, attentive, durable, indifferent to the moment-to-moment presence or absence of any particular customer. The substrate continues, knowing more tomorrow than it knew today, with or without any particular customer present at any particular moment.

Three principles compose into the sentinel posture and each is load-bearing in its own right.

Substrate as sentinel, not as product. The closed loop runs continuously. The ingestion pipelines grow the substrate during every customer's presence, every customer's absence, all customers' absence. The intelligence and evidence the substrate produces are byproducts of the substrate operating, not features the customer activates. The customer's relationship to RTOpacks is one of entry, participation, and possible departure — not one of creation, dependence, or capture. The substrate is the thing; the customer is a participant in it.

No weaponised lock-in. RTOpacks does not punish the customer for leaving, lapsing, or considering alternatives. Export-portable output is first-class (ADR-010). Subscription lapse leaves the administrator role intact and the door soft, not locked — the customer can return, find their state preserved, and resume without re-onboarding friction. The substrate retains audit trail across customer absence; their work is theirs whether or not they are currently paying. RTOpacks bets that demonstrated trust produces more reliable re-subscription than applied pressure, and designs for that bet structurally rather than instrumenting it through retention features bolted onto an otherwise hostile architecture.

Interface as revelation, not instruction. The customer arrives at a system that discloses its own use rather than tutorialising the customer into compliance with the product's expectations. The visual language — restraint, negative space, the deliberate use of canvas as interaction primitive rather than wizard-and-form scaffolding — is the visible surface of the sentinel posture. A system shouting features performs for the customer; a sentinel system simply exists, competent and attentive, and the customer who recognises that finds the system credible. Mastery does not need to advertise itself; it shows.

These three principles are tested at every layer where a design decision is made. The lens question is: does this decision express the sentinel posture, or does it violate it? A subscription model that hard-locks the customer on lapse violates it. A feature wall that gates basic competence behind sales-team interaction violates it. A surface that explains its own structure rather than performing competence at the customer expresses it. An audit trail that persists across the customer's absence expresses it. The principles are not aesthetic preferences; they are the disposition the substrate's commercial and structural decisions are obliged to express.

Why this disposition matters commercially¶

The Australian regulated training market is structured around fragmentation — multiple disconnected vendors, manual reconciliation between them, lock-in patterns as standard commercial practice, software that performs competence to customers who have been around long enough to recognise the difference. The operators who would find RTOpacks credible are precisely the ones who have lived through enough of that fragmentation to recognise the sentinel posture as something rare. They will not be convinced by feature lists or sales theatre. They will be convinced by a system that behaves like substrate, looks like mastery, and respects their ability to evaluate it on its own terms.

The disposition is therefore not just an architectural property but a commercial positioning. It is the property that competitors cannot copy by adding features, because the disposition emerges from years of design instincts applied consistently across every layer of the substrate. Disposition is the moat that the substrate moat (Section 4) is wrapped in.

2. The closed loop¶

RTOpacks operates as a five-phase closed loop. The phases are continuous, not episodic — every operational cycle runs through them, generating evidence and feeding intelligence back into the next cycle.

Phase 1 — Sense¶

The intelligence layer surfaces where the money is, what the market wants, where the gaps are, how the client's current scope is performing, and where opportunities sit just outside the client's present configuration. Built on the ingested data substrate (Section 4), the Sense phase produces views no individual RTO can assemble for themselves and no competitor structurally holds the data to produce.

Phase 2 — Decide¶

Human strategic decision-making, informed by Sense outputs. The decision-maker is typically the RTO's owner, CEO, or strategic operations lead — the person responsible for what business the RTO is in, not just how it operates day-to-day. Decide is oriented by license-as-moat logic and audit-cost-asymmetry economics (Section 6). RTOpacks does not automate this phase; it informs it.

Phase 3 — Execute¶

UCCA-driven content production, assessment generation, and compliant training material — all to the letter of the law. Workflows tracked, staff and skills aligned, processes and procedures invoked, continuous improvement recorded. The Execute phase is where most of the operational compute happens.

Phase 4 — Deliver and Assess¶

Students engage with the produced content, complete assessments, and generate completion evidence. Delivery happens either via RTOpacks-native LMS (currently entering this surface via InstaLearn for non-regulated credentials, expanding into regulated delivery as the platform matures) or via export to client-owned LMSes for clients who prefer that path. The export option remains a permanent first-class capability — RTOpacks serves the client, not captures them.

Phase 5 — Evidence¶

Audit trail generated as byproduct of operations across all phases. Date-stamped, cryptographically locked records of decisions, content production, delivery, assessment, and outcomes. Continuous audit-ready state, not periodic audit prep event. Record module surfaces this evidence for the client and for ASQA when audit is called.

The loop is the product¶

The closed loop is the central architectural commitment of RTOpacks. It is the thing competitors cannot match without rebuilding from a substrate they do not have. Other vendors automate fragments of the loop; only RTOpacks closes it. The substrate moat (Section 4) and the architectural coherence (no legacy product to evolve, no vendor sprawl) are what make machine-speed closure possible.

3. The Client¶

A client in RTOpacks is the central entity around which everything else organises. The canonical term is "client." Other terms previously used in code or text — customer, org, account — are retired. If a narrower concept emerges later that needs its own term, it is created deliberately rather than by repurposing legacy terminology.

Three customer types¶

RTOpacks recognises three customer types, distinguished by their relationship to regulatory authority and the data-provenance posture of their client file.

Type 1 — Registered RTO. Listed in TGA, with a complete public regulatory record. The client file is auto-populated at signup from RTOpacks' TGA mirror (Section 4). The client may correct or annotate the file; corrections flow into the compliance-mirror surface that surfaces drift between the client's self-reported state and the regulator's record.

Type 2 — Pre-registration RTO. Intends to register with ASQA but is not yet listed in TGA. Self-reports their information into TGA-shaped schema. At the moment of registration, the data graduates from "self-reported" to "regulator-verified" via a confirmation step, with provenance markers updated on each field.

Type 3 — Non-RTO content creator. Independent course developers, corporate in-house trainers, freelancers. Not regulated; not in TGA. Different product surface (limited modules, possibly watermarked output, different commercial terms). Worth flagging that Type 3 includes adversarial-curiosity users — competitors signing up to scope the tooling. Type 3 surface should be designed accordingly: useful for legitimate Type 3 users, structurally non-leaky of Type 1/2 substrate value.

Why "client" is the right term¶

A client in RTOpacks is not analogous to a "customer" in a typical SaaS. In most industries, the customer record is a thin layer — name, billing, preferences — and the customer's real business records live in their own systems. In RTOpacks, the client file holds the regulatory record itself, which IS the business in a regulated training market. Without the regulatory record, the business does not exist legally. The client file is the foundational legal artefact of the customer's existence as a business.

This is why "client" — with its regulatory-professional connotation, used in law firms, accountancy practices, and consulting firms — is more accurate than "customer." RTOpacks holds clients the way a tax accountant holds clients: as the bearer of a structured, ongoing, foundational record of the client's regulated existence.

Internal organisational complexity within a client¶

A single client (one RTO) may have one user (a sole-trader RTO) or many users across multiple sites, multiple states, and multiple roles (a large TAFE). The access-control structure within a client is articulated in ADR-020: a client administrator role (T4) holds authority over user invitation, role assignment, and plan control; client users (T4A) do operational work within the client substrate with permissions granted by the administrator. In a one-person RTO, the same human wears both roles — the architecture does not change, only the role-binding distribution does.

The principle: a user is attached to a client; users do not exist outside a client. A single human may be attached to multiple clients (a consultant working across several RTOs, for example) but the attachment is per-client, not global. Cross-client access between client substrates is structurally impossible at the user layer; the only path across client boundaries is via the operator support pattern in ADR-022.

4. The ingested data substrate¶

RTOpacks is built on an ingested data substrate that aggregates multiple Australian government data surfaces relevant to the regulated training market:

training.gov.au (TGA) — the supply-side regulator view. Authoritative on who is an RTO, what they are approved to deliver, regulatory history, scope, locations, qualifications, units of competency. Audience: RTOs, regulators, auditors. The apex source.
yourcareer.gov.au — the demand-side outcomes view. Editorial framing of courses, costs, career pathways, and outcomes. Audience: students and career-decision-makers. Gives RTOpacks visibility into how the regulator presents training to the consumer.
ABS labour market data — the macro-economic reality. Employment data, wages, occupational projections, regional labour signals. Sources include OSL (Occupations and Skill Levels) and IVI (Internet Vacancy Index) feeds.
Government funding and tender data — supply-side commercial signals. AusTender contracts, funded program announcements, ATM (Approach to Market) data.
Other sources captured opportunistically — ingested under the hoover-mentality principle described below.

Each source is held pristine, refreshed via sync, and never modified by RTOpacks. The product surfaces — modules, the Market view, the client file — are derived presentations that join across sources to produce views no individual source provides. The substrate is the moat; the presentations are the product.

Why the substrate exists — the four moats¶

The substrate exists for four reasons, in increasing order of strategic weight.

Operational. Upstream APIs have latency, rate limits, and query patterns RTOpacks needs to query against differently. Local substrate enables fast, reliable, unconstrained queries. This is the most visible benefit and the least strategically important.

Continuity. Capturing data while access is open. RTOpacks built the ingestion pipeline during a window when upstream APIs permitted unrestricted access. A future restriction — which is plausible, particularly as open-government data infrastructure matures and authorities recognise machine-speed scraping risks — will find RTOpacks already holding the data. The competitive position is locked in.

Historical. Full longitudinal record from day 1 of substrate operation. Every regulatory event, scope change, registration transition, funding announcement, labour market shift — captured as it happens. Competitors who did not capture the data in this window cannot retroactively obtain it. The historical archive is uncopyable and compounds in value daily.

Analytical. The full historical corpus, joined across sources, enables analysis no one else has done. Market structure analysis, regulatory trajectory modelling, scope-change prediction, comparative RTO analysis, supply-demand-funding triangulation. These are derivative products built on the substrate that competitors structurally cannot offer.

The TGA mirror — apex source¶

The TGA mirror is RTOpacks' local copy of the public TGA corpus. It includes the full regulatory record of every Australian RTO: legal entity details, registration history, approved scope, locations, qualifications, units of competency, regulatory events.

TGA's underlying architecture. TGA outsources its reporting layer to Microsoft PowerBI. To support this, TGA exposes a structured data API via Swagger (https://training.gov.au/swagger/index.html — an endpoint TGA has not formally published but which is operationally live because PowerBI depends on it). RTOpacks accesses this API directly, bypassing PowerBI's consumer-side export limits. PowerBI is one consumer of the API; RTOpacks is another consumer of the same contract.

The Swagger surface is structural, not accidental. TGA cannot restrict it without coordinating with their reporting vendor migration. RTOpacks' access to the substrate is more durable than a typical "scraped from a public site" position.

Swagger vs reports — the asymmetry. The Swagger schema represents what TGA's API makes available. The published reports at https://training.gov.au/reports represent what TGA chose to surface for routine reporting. These are not the same surface. The Swagger almost certainly exposes more than the published reports consume. RTOpacks ingested with hoover-mentality completeness rather than report-shape selectivity, which likely means RTOpacks holds a more complete picture of the exposed corpus than TGA themselves currently surface in published reports.

Honest limit. The mirror reflects what TGA publishes via the Swagger surface, not what TGA holds internally. There may be data TGA uses for its own operations that is never exposed externally. RTOpacks cannot mirror what TGA does not publish. The moat is "matches what TGA publishes," not "matches what TGA knows."

The compliance-mirror surface as product feature¶

When a Type 1 client signs up, the relevant TGA mirror data is copied into their client file. The client file holds its own working copy that the client may correct, annotate, or extend. The TGA mirror remains untouched.

Drift between the client's self-reported state and the TGA-sourced state is a first-class product surface. RTOpacks surfaces drift to the client as "you have updated these fields; the regulator's record still shows the previous values. Here is what you need to do, and where you need to go, to bring the regulator into sync." Drifted fields are visually flagged (yellow-highlight pattern) until the regulator accepts the change and the substrate's next sync reconciles the records.

No damage done if the client chooses not to act. RTOpacks holds the compliance flag for them. This converts a typical RTO blindspot (most RTOs rarely look at their own TGA record) into a continuous compliance check. The client sees themselves more clearly than TGA does, more often than they would ever check themselves.

The three-layer data architecture¶

RTOpacks operates a three-layer data architecture:

Layer 1 — Ingested raw. All upstream data sources held pristine and immutable from RTOpacks' perspective. TGA, yourcareer, ABS labour data, government funding and tender data, and any future ingested source. Refreshed via sync, never modified.

Layer 2 — Derived and computed. Joins, aggregations, transformations, model outputs, presentation-shaped views. Disposable in principle — recomputable from Layer 1 at any time. Authority comes from the derivation logic, which lives in version-controlled code.

Layer 3 — Client and operational state. The state RTOpacks creates and holds on behalf of clients and itself: client files, corrections, iterations, audit trails, custom annotations, generated outputs. The only layer where RTOpacks' own opinions live.

The pristine-raw principle applies to Layer 1 absolutely. The hoover-mentality principle applies to Layer 1 ingestion. The recompute-as-needed principle applies to Layer 2. The client-file architecture lives in Layer 3.

This separation is what makes the substrate moat operationally sustainable. Layer 1 is the asset that compounds in value over time and cannot be reconstructed by competitors. Layers 2 and 3 are the rebuildable surfaces that present that asset as products.

Current implementation note. This three-layer architecture is the principle the substrate is moving toward. Layer 1 has been protected, mostly by deliberate sync discipline. Layer 2 and Layer 3 are partially mixed in the current ops-db substrate. Ongoing architectural work — including the database-shape decisions downstream of OPS-DB-CONTENT-AUDIT-01 — is progressively aligning the implementation to the principle.

Working principles for the substrate¶

Hoover-mentality ingestion. RTOpacks ingests what upstream exposes, not only what current features consume. The substrate's future analytical and competitive value is asymmetric: marginal storage cost is low; marginal value of holding historically-captured data that competitors cannot retroactively obtain is high. Discipline around what to mirror is calibrated to access-window availability, not to current-feature need. This is the inverse of conventional engineering discipline ("only ingest what you need"); for substrate-as-moat businesses, the conventional posture is wrong.

Recompute-as-needed. Derived tables (Layer 2) are not precious. If derived outputs are wrong, the derivation logic is corrected and the derived layer is rebuilt from Layer 1. New analytical questions do not require new ingestion; they are computed from substrate already held. Storage costs are paid up-front at ingestion; compute costs are paid as derivations are needed.

Pristine-source. RTOpacks does not modify ingested data for any reason — not for cleanup, not for normalisation, not for correction, not for convenience. The faithfulness of the ingested layer to its upstream source at the moment of ingestion is the foundation of every downstream analysis; mutating it once destroys the foundation permanently. Modifications, normalisations, joins, and corrections happen in Layer 2 or Layer 3 — never on the raw.

The Sync Watchtower as integrity layer¶

The sync infrastructure (IRSL pattern, sync observability, watch carry-forwards, run-status logging) is the operational integrity layer for the substrate moat. Without observable, reliable, honest sync, the substrate degrades silently — ingestion gaps appear, freshness lies, historical capture has holes. The Sync Watchtower work that has been ongoing across recent sessions is foundational to substrate integrity, not separate operational machinery.

Future-restriction posture¶

If upstream sources restrict or close their APIs, RTOpacks shifts from "full sync" to "diff against what we already hold." Because the substrate is comprehensive at the moment of restriction, the operational delta is small — RTOpacks only needs whatever the source exposes going forward, applied as updates to the historical baseline. This is significantly more tractable than re-sourcing from scratch and is a deliberate architectural hedge.

Pending substrate audit work¶

The substrate's full inventory has never been catalogued canonically. Forward-referenced briefs that will close this gap:

INGESTED-SUBSTRATE-INVENTORY-01 — complete audit of every external data source RTOpacks has ingested: where each lands, how each is refreshed, completeness against the upstream surface, current state. The canonical answer to "what data substrate does RTOpacks actually hold?"
TGA-MIRROR-CORPUS-AUDIT-01 — specifically for the TGA mirror: inventory against the Swagger spec, comparison against the published reports as a semantic benchmark, historical fidelity assessment.
TGA-UPSTREAM-INTELLIGENCE-CAPTURE-01 — capture the Swagger spec canonically in repo, set up periodic re-fetch and diff watch; capture and monitor the published reports page for editorial changes. Both are competitive intelligence streams.
TGA-SWAGGER-VS-REPORTS-DELTA-AUDIT-01 — characterise the gap between what Swagger exposes and what published reports surface. The delta is moat-worthy data competitors operating in report-mode would not think to access.

5. The client file¶

The client file is the structured record of a single client. It is the central entity in Layer 3 and the focal point around which most product surfaces orient.

What the client file contains¶

The client file has two essential layers internally:

Upstream regulatory layer. For Type 1 clients, this is sourced from the TGA mirror at signup and refreshed periodically. For Type 2 clients, this is self-reported into TGA-shaped fields, with provenance markers indicating "self-reported." For Type 3 clients, there is no upstream regulatory layer; the client file is operational-state only.

Operational state layer. RTOpacks-created and RTOpacks-held content: client corrections to regulatory data (the drift surface), generated training and assessment material, version histories, staff and skill records, process and procedure documentation, audit evidence trail, correspondence, billing relationship, sessions and student outcomes once delivery is wired.

Each field in the client file carries provenance: regulator-verified, self-reported, derived, or RTOpacks-created. Provenance is not a presentation detail — it is a load-bearing schema property that determines how the field is treated by every consuming module.

The anchorage principle¶

The client file is the apex entity. A large amount of operational state hangs off it — Studio sessions, generated content outputs, staff work products, drafts, exports, version histories, audit decisions, delivery records, assessment outcomes, correspondence threads.

Every attachment to the client file is deliberate, named, and broadcasts its intent clearly. Solid, thoughtful anchorage points that any future module or surface knows how to use. Not silk threads. Not "we'll figure out where this goes later." Not accreted ad-hoc relationships.

The principle: if a new piece of operational state needs to attach to the client file, the attachment is designed deliberately before the attachment is built. The four substrate questions apply: what does it know, where does it live, who sees it, how does it fail. If those four answers do not exist before the attachment is built, the attachment is not built. This is what prevents the next year of work from accreting silk-thread architecture the way the previous year did.

The detailed shape of the attachment points — which tables reference the client file by what keys, what indexing strategy supports the access patterns, what permissioning model gates each attachment — is downstream of this doc and lives in module specs and architectural decisions. The principle in the spine doc is that attachments are deliberate and named, not accidental and inferred.

6. The two streams and the six modules¶

RTOpacks delivers two streams of capability that compose into one product. Either alone has limited commercial value; together they form the closed loop.

The strategic intelligence stream¶

Surfaces where the money is, what the market wants, where the gaps are, where the client's present configuration is performing or underperforming, where opportunities sit just outside the present configuration. Tells the operator where to go.

The compliant execution stream¶

Produces training, assessment, and audit evidence to the letter of the law. Lets the operator actually go there once the destination is chosen. Includes the workforce alignment, policy and process management, content production, delivery, and evidence generation that turn a strategic decision into an operating reality.

Why both are needed¶

Knowing where the money is, without the capability to produce compliantly, is knowledge with no commercial expression. Producing compliantly, without knowing where the money is, is either inertia (continuing to deliver what you have always delivered) or guesswork (building what you think will sell). Neither succeeds in this market because the market is regulated and subsidised — government decides what training matters and pays for it, and the supply side competes for that money. Building for "demand" in the abstract does not work; you must build for the specific places government has directed money to flow.

Small operators tend to pick one stream or the other. Smart operators run both. RTOpacks gives every operator the integration that smart operators previously achieved only through rare individual brilliance.

The duck-and-shark example¶

There is an RTO in Adelaide that on the public TGA register appears as a small operation — four qualifications on scope, generic, unremarkable. Anyone scanning the public register would categorise it as "small regional RTO" and move on.

Pull the historical scope of this RTO across fifteen years and a different picture emerges. Three hundred qualifications have been on scope over that window. The history maps to funding programs that opened and closed, CRICOS approvals for international students, industry demand surges in particular sectors. The operator adds to scope when an opportunity opens, removes when it closes, and reshapes continuously.

This is not a small RTO. It is an operation running the government-money business with an educational hat on, exploiting their RTO license strategically, cycling scope as the funding and demand landscape shifts. They are in a whole-of-market sense larger than many TAFEs, but they appear small because the public view shows only today's snapshot. The duck on the pond is sitting on a shark.

The smart-operator insight: the cost of holding qualifications on scope is non-trivial. Audit cost is roughly fixed for the first four qualifications and increases per additional. Holding qualifications requires either active delivery or demonstrable readiness to deliver at audit. This makes scope a strategic resource to be allocated, not a trophy to be accumulated. Smart operators understand this; ego-driven operators do not.

The strategic intelligence stream surfaces this dynamic for every client. "Your current scope is costing you $X in audit overhead and producing $Y in enrolments. Here are the qualifications producing the worst ratio. Here are the qualifications outside your current scope where the money has moved." This is not possible without the substrate. It is uniquely possible because of it.

The six current modules, mapped to the five-phase loop¶

Sense: Radar (RTO intelligence, footprint analysis, regulatory record visibility), Market view (qualification market analysis, demand-supply triangulation, scope optimisation).
Decide: strategic surfacing within the client file. Not a separate module — Decide is the human moment between Sense outputs and Execute initiation.
Execute: Studio (course design and content production), People (workforce compliance, trainer register, skills alignment), Documents (policy library, process and procedure documentation).
Deliver and Assess: InstaLearn (current entry point for non-regulated credentials, growing into regulated LMS over time). UCCA / Studio output formats include SCORM, print, and other exportable formats as first-class options for clients who prefer their own delivery infrastructure; native delivery via InstaLearn is the additional path, not the only path.
Evidence: Record (audit artefacts, the cryptographic ledger of decisions and operations across all phases).

Future modules on the trajectory¶

The closed loop is incomplete without student management (enrolment, attendance, progress, billing integration). This is a planned future module that extends the same closed-loop architecture. Its design conversation happens when its time comes; the spine doc acknowledges the trajectory without committing to specific sequencing.

Other future modules may emerge as the market reveals additional surfaces. Each new module attaches to the client file via deliberate anchorage (Section 5), consumes the substrate (Section 4), and integrates into the closed loop (Section 2).

The Market app — a note on placement¶

The Market app referenced in earlier audit work is a substrate-driven presentation surface — an early prototype of the strategic intelligence stream. Its specific product placement (whether it remains its own module, gets absorbed into Radar, or evolves into a new top-level surface) is a downstream product decision. The spine doc names it as the exemplar of substrate-driven presentation; its productisation is pending.

7. Identity and access¶

The access-control model¶

RTOpacks operates a three-tier access-control model, articulated in full at ADR-020. Summarised here for orientation:

T3 — Operator tier. The three-person team operating the substrate (Tim, Alex, Claude). Holds super-user authority across all client substrates for substrate operation, infrastructure administration, customer support, and incident response. T3 is the highest tier; there is no platform tier above it (per ADR-008). T3 does not have a commercial relationship to the client substrates it operates — operators are not paying customers of their own platform.

T4 — Client administrator tier. One or more users per client file holding administrative authority over that client's substrate. Functions: user invitation and management, role assignment, plan and billing control, view of all client substrate state. T4 is established via the signup-and-admin-authority flow (§8 and ADR-012); the T4 administrator role is structural (it does not consume a seat against the client's plan).

T4A — Client user tier. Users attached to a client file who do operational work within it. Functions: module use, per-user state, per-user audit trail. T4A users are invited by T4 administrators; their permissions are a subset of what the T4 administrator grants. Plan entitlements consume against T4A seats per ADR-021.

The T4 administrator role and the T4A user identity are separable. A T4 administrator is a role, not a user identity. The same human typically holds both — the structural authority position (T4) and a countable user identity that does operational work (T4A). In a one-person RTO, the same human wears both hats; the architecture does not change.

Users do not exist outside clients. A single human may be attached to multiple clients (a consultant working across several RTOs) but the attachment is per-client. Cross-client access between client substrates is structurally impossible at the user layer. The only path across client boundaries is via the operator support pattern (ADR-022). There is no commercial platform tier above clients (per ADR-008); UCCA Inc and UCCA Pty Ltd are corporate entities, not architectural tiers.

The user-and-credential separation¶

A user is the thing that has roles, owns sessions, takes actions, attaches to client files. A credential is the thing that proves the user is who they claim to be.

These are different concepts. The schema separates them. A user can have multiple credentials over time; a credential authenticates one user.

Credential management is outsourced. RTOpacks does not own credentials — does not store passwords, does not run MFA enrolment flows, does not manage session token rotation, does not implement password-reset logic. An external identity provider does. RTOpacks receives a verified identity assertion and acts on it.

Provider preference: Cloudflare-native first. Per the CLOUDFLARE-FIRST RULE, identity is asked of Cloudflare first. Cloudflare's identity story (Access, Zero Trust, evolving identity primitives) is evaluated against RTOpacks' three-customer-type requirements before any external provider is entertained. External providers, when entertained, are gap-specific rather than wholesale replacements — multiple targeted providers each filling a specific gap Cloudflare cannot fill, not a single IDP replacement. Each gap-filling provider gets its own ADR.

Federation as future credential type. Enterprise customers (TAFEs, larger RTOs with existing IdPs) may eventually require federated authentication via their own OIDC provider. Federation is treated as a future credential type, not a separate user system. The architectural separation of user from credential makes federation a configuration concern at the provider level, not a schema migration. Federation engineering happens when an enterprise contract justifies it; it is not a launch feature.

Pending identity work¶

CREDENTIAL-PROVIDER-DECISION-01 — audit Cloudflare's identity primitives against the three-customer-type requirements; identify gaps if any; evaluate external providers per gap (not as wholesale replacements); close with specific recommendations per gap.
IDENTITY-MODEL-RATIONALISATION-01 — resolve the four identity conventions currently in the database (email-keyed, UUID-keyed, prefix-keyed, randomblob-keyed) into one canonical user/identity model. Hard prerequisite for any identity-related database migration.
ADMIN-AUTH-MODEL-RECONCILIATION-01 — reconcile the current state of admin authentication (CF Access in practice, passkey scaffolding never authenticated anyone). Likely subsumed by CREDENTIAL-PROVIDER-DECISION-01.

The pending identity work now has the access-control model in ADR-020 as the target shape to rationalise toward; IDENTITY-MODEL-RATIONALISATION-01 in particular resolves the four current identity conventions into T4 administrator role-attachment and T4A user identity per the canonical articulation.

Signup is open to anyone with two paired verifications: an email matched against TGA-published data, and SMS confirmation on a real phone number. Both must succeed.

This gate solves three problems at once: authenticity (matching against TGA-published data proves real RTO association), individual ownership (the SMS proves a real human at the keyboard), and the trigger for client-file population (successful verification mints the client file from the TGA mirror).

On the matching strategy. The TGA mirror does not hold a single authoritative "RTO email domain." It holds rto_web_addresses (the RTO's published website domain) and rto_contacts (emails per contact role: CEO, public officer, and others). Neither field, in isolation, is "the email domain that authoritatively belongs to this RTO." Many small RTOs use personal-provider emails (Gmail, Hotmail, Bigpond). Large RTOs operate multiple domains. Trading-name domains differ from legal-entity domains. Educational institutions often hold .edu.au domains that may or may not match their TGA-listed website.

A literal "email domain equals TGA-listed website domain" check would exclude legitimate signups and admit some illegitimate ones. The signup-implementing brief will specify a richer matching strategy — anchored against actual substrate data on how RTOs present their domains and contacts in TGA — that combines website-domain matching, contact-email matching, RTO-code-plus-contact-phone matching, and other paths as appropriate.

The principle in this section is that signup verification anchors against TGA-published data. The specific matching logic is downstream design and will be informed by substrate evidence rather than imagined edge cases.

On the SMS verification. SMS sending and receiving is mediated by RTOpacks' SMS module — a substrate-shared internal wrapper around Cellcast (RTOpacks' chosen SMS provider per ADR-014). The signup gate's SMS leg uses this module, as will every other RTOpacks consumer of SMS (client-side messaging, 2FA flows if applicable, future use cases). The module wraps Cellcast's full published API surface per the external-service integration pattern (ADR-015), so the wrapper covers endpoints RTOpacks does not currently consume against future use.

For Type 1 clients, the auto-populated client file is the strategic centrepiece of onboarding. RTOpacks demonstrates competence by showing the prospective customer that everything about their RTO is already known. Most competitors onboard with forms; RTOpacks onboards with a demonstration of what it already knows. This is the show-don't-tell move — it converts the substrate moat into immediate customer-perceived value.

For Type 2 clients (pre-registration RTOs), signup proceeds via a non-TGA-listed email. The client self-reports into TGA-shaped fields. The data graduates to regulator-verified status at the moment of TGA registration via a confirmation step.

For Type 3 clients, signup proceeds via any email. Product surface is limited; commercial terms are different; competitive-intelligence considerations apply.

Account creation and administrative authority are decoupled. Whoever signs up first from an RTO domain creates the client file. That first signup gets a default role — typically "member" or "pending verification" — and full access to read-only views of the auto-populated client file (the regulator-sourced data is public anyway, so no privacy issue).

Administrative authority is established asynchronously via CEO notification. RTOpacks sends an email to the CEO on file in TGA (or to whoever the regulatory contact is) with a clear decision interface: confirm this user's access, set up your own admin account, or report the signup as unauthorised. The CEO does not have to log in and assign roles manually; they get a single decisive email with structured options.

Until the CEO acts, the first signup operates in pending-verification mode — can explore the product, see the auto-populated client file, get a sense of value, but cannot modify protected operational state, invite other users, or take actions that depend on administrative authority. If the CEO never acts, there is a soft escalation path after a defined timeout.

When subsequent users from the same RTO domain sign up later, the flow is identical: they create a user record attached to the existing client file, get the same pending state, and the current primary admin receives the same three-button decision flow. One flow to design, build, test, and maintain — not separate flows for first user versus Nth user.

The principle this encodes¶

Account creation is open to anyone with a verified RTO-domain email. Administrative authority is established asynchronously via CEO notification. The two are decoupled. This avoids gating the new user's experience on the CEO's responsiveness, treats the CEO email as a verification channel rather than a permission-grantor, and keeps "the client file exists" structurally separate from "this user has admin authority over it."

9. Substrate architecture — modularity, flows, and cartography¶

The architectural disciplines articulated in architecture-decisions.md (ADRs 015 through 018) together describe how RTOpacks' substrate is organised, how flows pass through it, and how the substrate makes itself legible to its operators. This section names the principles at the spine-doc level; the ADRs hold the concrete commitments.

Modular consolidation over ad-hoc attachment¶

The same shape of work appears more than once in the codebase, the second instance is the trigger for consolidating into a shared module rather than copying the pattern again. This applies to external service integration (Cellcast SMS as a shared module, future providers behind their own wrappers), to internal patterns (the IRSL pattern for sync logging, the user-credential separation for identity, the three-layer data architecture), and to operational machinery generally.

The failure mode this prevents: ad-hoc attachment of code at the point of immediate use, scattered across the codebase in subtly different shapes, with debugging routing through inconsistent paths and refactors becoming substrate-wide audits.

The discipline (per ADR-016) names two instances as the threshold for consolidation. Not every pattern needs to be modularised — only the ones that will recur. First instance is permissible as feature work; second instance is the warning sign; consolidation happens before the third instance is built.

The in-and-out bus pattern¶

Every flow of data into and out of RTOpacks passes through a known, named, observable point. Inbound webhooks, outbound API calls, internal worker-to-worker messages, scheduled task firings — each routes through a centralised structure (a "bus" in the architectural sense) rather than being scattered across whichever worker happens to handle that one case.

The bus pattern (per ADR-017) produces three properties that ad-hoc routing cannot:

Findability. When something breaks, the broken flow is locatable because every flow has a known path through the substrate.
Observability. Every flow can be instrumented at the bus level, giving consistent telemetry across the whole substrate without per-worker instrumentation discipline.
Replaceability. When a provider changes, a worker is rewritten, or a flow gets re-routed, the bus pattern means the change happens at the bus level rather than via cascading audits of every consumer.

The bus isn't necessarily a literal message bus (though it may be for some flows). It's an architectural pattern that requires every flow to have a named, traceable path through known infrastructure.

Substrate self-broadcasting via architectural cartography¶

The substrate documents itself to its operators because the operators cannot document the substrate fast enough to keep up with its growth. The mechanism is architectural cartography — a canonical visual map of the system, hierarchical and zoomable, with every component carrying a canonical name in everyday vocabulary.

When Tim says "the client-studio-storage-module needs X," the name is unambiguous because the named component exists at a known location on a known map. When Alex needs to understand what depends on a piece of substrate before changing it, he looks at the map. When future Claude opens into a new session, the map orients far faster than prose ever could.

The cartography commitment (per ADR-018) includes:

Tool choice: Mermaid as the primary diagram format. Renders natively in mkdocs (so the map appears on docs.rtopacks.com.au alongside the prose docs), lives in version control as text, diffs cleanly in git, and is readable and writable by Claude and Alex without special tooling. If Mermaid hits expressivity limits, alternatives get evaluated; Mermaid is the default.
Hierarchy: Multiple levels of map, from 10,000-foot system view down to component-level detail. Higher levels show systems and major flows; lower levels show concrete bindings, endpoints, and dependencies. Each level is canonical at its own resolution.
Naming convention: Components carry names following the shape <scope-prefix>-<domain-or-module>-<function>-<artefact-type>-<environment>. Scope prefix resolves to rtopacks-* (platform-owned), rto-* (client-facing), or no prefix (utility infrastructure) per the determination test in ADR-018. Examples: rto-studio-storage-db-prod, rtopacks-tga-mirror-ingest-bus-prod, rtopacks-sms-cellcast-wrapper-prod, rtopacks-ops-db-prod. ADR-018 is the canonical authority on the convention shape, vocabulary, and determination test; substrate-specific facts (Cloudflare character constraints, the KV uppercase-underscore exception, per-resource-type rename feasibility) live in infrastructure/cloudflare-naming-canon.md.
Living document: The map is maintained alongside the substrate. When new components are added, named, or relocated, the map updates in the same commit as the substrate change. The map is not a one-time documentation effort; it is a substrate artefact in its own right.

Why these three principles compose¶

Modular consolidation produces units worth naming. The bus pattern produces flows worth mapping. The cartography makes both legible at a glance. Together they ensure that:

The substrate has a coherent vocabulary (modular units have names)
The substrate has traceable flows (bus pattern means every flow has a known path)
The substrate is legible without expert knowledge (the map shows what's there, named consistently, traceable through known paths)

A three-person operation can run a substrate of any reasonable complexity if the substrate broadcasts its own structure. The same operation cannot run substrate of even moderate complexity if the substrate hides its structure. These three principles together are what makes operating at scale viable with three people.

Current implementation note¶

These principles describe the substrate's direction, not its current state. The current substrate has substantial ad-hoc attachment (which OPS-DB-CONTENT-AUDIT-01 surfaced extensively), flows that don't pass through named buses, and no canonical map at all. Bringing the substrate into alignment with the principles is the work of the next several months, executed via downstream briefs that each move one piece closer to the target shape.

The first prelim cartography work is the immediate next step: Alex produces a 10,000-foot Mermaid diagram of the substrate as it exists today, with working names per the proposed taxonomy. That gives us a concrete starting artefact to refine and to anchor subsequent substrate work against.

10. What this doc is not¶

This doc is the foundational architectural articulation of what RTOpacks is, the strategic thesis it operates against, the substrate it is built on, and the principles that govern how it is built. It is not:

A database schema. Specific tables, columns, and relationships live in module specs and architectural decisions.
A module specification. The detailed shape of Studio, People, Record, Radar, Documents, InstaLearn, and future modules lives in their respective spec docs.
A feature roadmap. What gets built when is a product-planning decision; the spine doc names the trajectory and the principles, not the schedule.
A pricing or packaging document. How the two streams are commercially packaged is a downstream decision.
A list of architectural decisions. Specific commitments (credential provider choice, database split shape, SMS provider choice, cartography conventions, etc.) live in architecture-decisions.md.
A code style guide, security policy, or operational runbook. Those live in their respective docs.
The system map itself. The architectural cartography is its own artefact, maintained alongside the substrate; this doc names the principle that it exists and how it's governed.

The spine doc is the foundation that everything else anchors against. When a brief, module spec, or architectural decision is being drafted, it is checked against the spine doc for consistency. When the spine doc conflicts with an existing artefact, the spine doc wins by virtue of being more foundational.

If the spine doc is wrong about something, the spine doc gets updated deliberately — with named reasoning, dated changes, and explicit acknowledgement of what is being revised and why. The spine doc is canonical, not immutable; but its changes are deliberate, not casual.

Standing rules added by this doc¶

The spine doc is canonical. Every subsequent brief, module spec, or architectural decision anchors against it.
The four substrate questions apply to every new attachment to the client file. What does it know, where does it live, who sees it, how does it fail. The four answers must exist before the attachment is built.
Layer 1 (ingested raw) is never modified. Pristine-source applies absolutely to every ingested data source.
The user-and-credential separation is a schema-level commitment. A user is the thing that takes actions. A credential is the thing that authenticates a user. They are not the same concept.
There is no platform tier above clients. UCCA Inc and UCCA Pty Ltd are corporate entities, not architectural tiers.
Hoover-mentality applies to substrate ingestion. Discipline around what to mirror is calibrated to access-window availability, not current-feature need.
The closed loop is the central architectural commitment. New modules and surfaces are evaluated against whether they extend the closed loop coherently or fragment it.
Recurring patterns are consolidated, not duplicated. Second instance of a pattern is the trigger to modularise; third instance must consume the shared module.
Every flow has a known path. Inbound and outbound flows route through named bus structures, not ad-hoc per-worker integration points.
The substrate is mapped. Architectural cartography is canonical infrastructure, maintained alongside the substrate, with consistent naming conventions and Mermaid as the default rendering format.

End of spine doc. Companion documents: architecture-decisions.md (specific commitments log, 25 ADRs), WS-PRODUCT-01 (product overview), module specs, design foundation, standing rules, the system map at canonical map location (TBD per ADR-018 implementation).