# IA · One account, organisations apart, subscriptions apart

> The Architect's direction, 6 November 2026: an architecture like Atlassian's. A central account registered and signed into at
> `id.tutelora.com`; each product on its own domain; organisations registered there with no product information; product
> information in a dedicated subscription subsystem that links to the organisation subsystem. This plan checks that against what
> Atlassian actually does, compares it with what Atrium has, and sets out what it will take to align.

**Status:** IA-1 to IA-11 decided by the Architect, 6 November 2026, and carried into M00, AF, `PROJECT.md` and the map (§10). TB-1 to TB-7 on billing
were decided as recommended the same day. Nothing is built. The module gate still applies: discussion, plan, mockups, review, then build.

---

## 0 · The one-paragraph version

What you describe is broadly what Atlassian does, and it's a sound shape. Their documentation adds two refinements worth copying:
signing up from a product creates the organisation as well, and what you call subscription is really three separate concerns: what's
sold, what's running, and who may use it. They also run organisations on a separate host from sign-in; you've decided to keep everything at
`id.tutelora.com`, so a person has one address for their account, organisation and billing. **In Atrium this costs little,
because almost nothing is built:** `tenant` already has no product columns, and the main changes are to plans, not code. `app_tenant`
goes, a product catalogue and entitlements come in, and the hostnames move to `tutelora.com`. **The real cost is in the products,
above all Campus,** which has to hand over sign-in and stop being the owner of its schools' identity. The direction also removes work:
if every product delegates sign-in, phone sign-in only has to exist in Atrium. **All of this is built in Atrium; the TuteCore repository
isn't changed** (the Architect, 6 November 2026). Billing is in from the start: Tabula adapts Desk's self-service billing (IA-6).

---

## 1 · The shape

```
   tutecampus.app      tutedesk.com      tuteloop.com      tutebooks.com     Each product keeps its domain,
         │                  │                 │                 │             its records and its detailed roles
         └──────────────────┴── sends people to sign in ────────┘
                            ▼                 and calls, from its server, ▼
   ┌───────────────────────────── Atrium: one app, one database ──────────────────────────────┐
   │  ACCOUNTS (Clavis)         ORGANISATIONS (Album)        SUBSCRIPTIONS (Tabula)            │
   │  id.tutelora.com           id.tutelora.com              catalogue: product, offering      │
   │  a person's one login.     registered and run here.     entitlement: org holds offering   │
   │  Needs no organisation     No product information       instance: where it's running      │
   │  and no product            Knows nothing of plans       billing, linked by the org's ID   │
   └──────────────────────────────────────────────────────────────────────────────────────────┘
        + Nuntius, Tutelink, Tessera, Tutela, Aerarium, Lector on api.tutelora.com; short links on tutel.ink
```

---

## 2 · What Atlassian actually does

Read on 6 November 2026, from Atlassian's own pages unless marked. Its internal schema isn't public, so this describes behaviour and
documented concepts, not its tables.

| Concept | What's documented | Source |
|---|---|---|
| **The account** | "Your online Atlassian identity that exists independently of the Atlassian apps you use." "Anyone can create an Atlassian account." E-mail is required and unique; no phone-only account was found | [account](https://support.atlassian.com/atlassian-account/docs/what-is-an-atlassian-account/), [domains](https://support.atlassian.com/user-management/docs/verify-a-domain-to-manage-accounts/), [e-mails](https://support.atlassian.com/migration/docs/user-management-differences-in-cloud-and-server/) |
| **Signing in from a product** | Seen directly: `bitbucket.org` and `trello.com` answer with a 302 to `id.atlassian.com/login?application=…&continue=…`, and Trello returns through its own callback. An OIDC discovery document is published at `auth.atlassian.com`, a separate host | [discovery](https://auth.atlassian.com/.well-known/openid-configuration) |
| **The organisation** | "Bring together your company's users and apps." Run at `admin.atlassian.com`, **not** at `id`. Created automatically on first sign-up for an app, **or** alone: "Occasionally, you may need to create an organization without any apps" | [what it is](https://support.atlassian.com/organization-administration/docs/what-is-an-atlassian-organization/), [getting started](https://support.atlassian.com/organization-administration/docs/get-started-with-an-atlassian-organization/) |
| **Under the organisation** | Centralized: Organization → App. Original: Organization → Site → App | [what it is](https://support.atlassian.com/organization-administration/docs/what-is-an-atlassian-organization/) |
| **What's sold** | Commerce: Product → Offering → Pricing plan → Order → Entitlement, "an instantiated offering". A transaction account holds the bill-to party and payment methods | [primitives](https://developer.atlassian.com/platform/commerce/platform-concepts/primitives/) |
| **Billing is apart from the organisation** | A billing account groups billing activity; "Most organizations only need one". Consolidating organisations "is not a billing change" | [billing accounts](https://support.atlassian.com/subscriptions-and-billing/docs/understand-billing-accounts/), [consolidation](https://support.atlassian.com/atlassian-cloud/kb/atlassian-organization-consolidation-guide/) |
| **What's running** | Provisioning is separate from the order and joined by `provisionRequestId`. The Tenant Context Service holds each tenant's databases, licences and features, "populated directly from our provisioning systems"; without it the request is rejected | [install](https://developer.atlassian.com/cloud/admin/cookbook-install-apps-products/), [architecture](https://www.atlassian.com/trust/reliability/cloud-architecture-and-operational-practices) |
| **Who may use it** | Removing someone is scoped to the organisation and "doesn't … permanently delete their Atlassian account"; they stop being billed. Organisations control accounts only by verifying a domain and claiming them | [remove](https://support.atlassian.com/user-management/docs/remove-or-suspend-a-user/), [domains](https://support.atlassian.com/user-management/docs/verify-a-domain-to-manage-accounts/) |
| **Outsiders** | Portal-only customers are a separate kind of account that "can only log in to the help centers they've been added in" | [customers](https://support.atlassian.com/user-management/docs/manage-jira-service-management-customer-accounts/) |

### Three lessons Atlassian paid for

- **Organisations came late.** Some Bitbucket and Trello customers still have none. From 16 March 2026 eligible paid Bitbucket
  workspaces got one created for them, and "it is not possible to unlink" it
  ([Bitbucket](https://support.atlassian.com/bitbucket-cloud/kb/linking-your-bitbucket-cloud-workspace-to-an-atlassian-organization/)).
- **Accounts can't be merged.** [ID-240](https://jira.atlassian.com/browse/ID-240) has been open since June 2015, with 2,861 votes and
  7,323 support references. Atlassian's last statement on it (2021) says full consolidation is unlikely.
- **Identifiers and contacts.** In April 2022 an API that "accepts both site and app identifiers" deleted 883 sites, recovery was slowed
  by immutable IDs embedded across systems, and contact data went with the sites
  ([review](https://www.atlassian.com/engineering/post-incident-review-april-2022-outage)).

Moving existing users was also slow and contested: "users elected to migrate … upon their next login", which made it "long-running",
and moving control from admins to users drew "very vocal" feedback
([identity platform](https://www.atlassian.com/blog/atlassian-engineering/migrating-the-atlassian-identity-platform-to-aws)).

---

## 3 · Where Atlassian differs from your description

Your description holds. These four points are where its detail differs, and each becomes a decision in §8.

1. **Organisations aren't at `id`.** There, `id` is the person's: account, profile, security. Organisations live at `admin`. **You've decided
   to keep everything at `id.tutelora.com`** (IA-2), which is simpler for people and makes that one host a larger target. §6 says how
   that's handled.
2. **There are two ways in, not one.** An organisation can be created alone, but most are created by first signing up for an app. The
   record can still hold no product information either way (IA-3).
3. **"Subscription" is three concerns:** what's sold (catalogue, entitlement), what's running (the instance), and who may use it (access).
   Billing is a fourth, kept apart again (IA-6).
4. **Everyone must have an e-mail,** and outsiders get a lesser account. We can't copy that: phone-only parents are live in Campus (IA-5).

---

## 4 · Compared with what Atrium has

"Today" means TuteCore 2.1.1 in this repository, plus the current drafts of M00 and AF. Size: **S** one slice · **M** a few slices in one
repository · **L** its own plan and several slices · **XL** a programme across repositories. These compare effort; I can't give dates
until the discussions and mockup reviews set the pace.

| Layer | Atlassian | Atrium today | Gap | Size |
|---|---|---|---|---|
| Sign-in host | `id.atlassian.com` | Planned at `accounts.tutelora.app` | Move to `id.tutelora.com`. It's free in DNS, and the brand guide already says the company lives on `tutelora.com` | S |
| Account with no organisation | Normal | **No.** Sign-up requires `workspace_name`, and an account's way into anything is a membership | Registering an account alone | M |
| Account identifiers | E-mail only | E-mail only, and `Membership::lets()` requires the membership to hold that exact address | Phone and username as identifiers; replace `lets()`. Campus has this live | L |
| Central sign-in for other domains | Redirect, OIDC | None. No app is a provider | OIDC provider, proved first | L |
| Organisation record | Users and apps, plans elsewhere | **Close already:** `tenant` has name, short and legal name, slug, country, logo, colour, locale, time zone, currency, status. No product columns | Add address, registration, kind. No product columns ever | S |
| Registering an organisation | Alone, or with first app | Service only (`CreateWorkspace`), or sign-up, off as shipped | Self-registration at `id`, both routes | M |
| Running an organisation | `admin.atlassian.com` | Workspace settings inside the app | Its pages at `id.tutelora.com` (IA-2) | M |
| Product catalogue | Product, Offering | None. AF's `app` mixes "the product" with "the software holding a key" | `product`, `offering`; split `server` out of `app` | M |
| Entitlement | Entitlement | None. AF's `app_tenant` is the nearest idea and mixes it with the instance | `entitlement`; `app_tenant` goes | M |
| Instance | Tenant Context Service | None. Each product's tenant knows nothing of Atrium | `instance`: product, organisation, the product's own tenant ID, its host | S |
| Access | App access, groups | Broad roles planned | Products decide who may use them; Atrium keeps owner, admin and billing for the organisation itself (CL-16) | S |
| Billing | Transaction account, invoices | None; Desk's is the nearest | Adapt Desk's into Tabula, behind one switch (IA-6) | L |
| Products delegating sign-in | All, after long migrations | None. Each has its own | See §9 | XL |

### Prior art for the subscription subsystem

It's worth reusing, not rewriting. **Desk's M18b** is the closest: a subscription per paid period, derived state, `Billing::includes` and
`limit`, 1,428 lines plus a gateway. But it's never run on a server, its `plans` have no product column, it's tied to Desk's `Rls`
and `Tenant`, and its limits are Desk's own (team, agents, apps, storage). **Campus's `plan_package`** is a price catalogue with SMS and
e-mail allowances, but a tenant only has one nullable pointer to it, with no history or state. And **the public site says the
apps are "agreed per institution", with "nothing charged without a written agreement"**
(`tuteportal/tutelora.com/app/views/page/pricing.php`). That wording has to change before self-service billing is switched on (TB-2).

---

## 5 · The target shape

**Accounts (Clavis, `accounts`), on `id.tutelora.com`.** A person's one login. Sign-in identifiers (e-mail, phone, username) become child
rows; `user.email` is no longer the only way in, and `lets()` is replaced. An account needs no organisation and no product. Its public ID
is what every product stores, and it never changes. Phone codes, one number one account, and the matcher come from Campus.

**Organisations (Album, `organisation`), registered and run at `id.tutelora.com`.** `tenant`, plus address, registration and kind.
`membership` says this person is in this organisation, and grants nothing in any product; three roles (owner, admin, billing) run the organisation itself at `id` (CL-16). **No column here names a product or a plan.** Removing
someone happens here, once. Adding someone is one action here with two doors (§7). Contacts live here, not in any instance.

**Subscriptions (Tabula, `subscription`).**
- `product`: what can be subscribed to.
- `offering`: Free, Standard and so on, per product. Limits and features as rows.
- `entitlement`: this organisation holds this offering, with its state and agreed terms. Recorded on the day it's granted, for a year by default (the Architect, 6 November 2026), with that default a setting. Links to the organisation by ID alone.
- `instance`: this entitlement is running as this tenant in this product, on this host. Replaces `app_tenant`.
- ~~`product_access`~~: dropped by CL-16, never built. A product decides who may use it; if seats are ever charged, products report them.
- Custom domains: Atrium keeps the one list, owned by the organisation, one address to one instance; the product serves the traffic (CL-18).
- Billing accounts, plans and periods, payments and invoices, adapted from Desk's, as their own structure, with billing admins apart from
  organisation admins. Built dark behind one switch.

**Servers (the foundation).** AF's `app` splits. What's sold is a `product`; the software holding a key is a `server`. A server has its key,
module scopes and allowed addresses. A request is checked at key, scope and address, and then that the named organisation has a live
`instance` of this server's product. An outside system like GWCL's has a server too.

**Words.** On the console an organisation is a **client** (the Architect, 6 November 2026); in code, and for people at `id`, it stays an organisation.

**Identifiers.** Typed and never reused: `org_…`, `acc_…`, `ent_…`, `ins_…`, so an API can't take one for another (the 2022 lesson).

**Hosts.** `id.tutelora.com` (accounts, sign-in, organisations, subscriptions and billing), `api.tutelora.com` (module APIs, widget,
staff `/console`), `tutel.ink` (redirect only), `*.tutelora.dev` for staging. Since the marketing site shares
`tutelora.com`, the session cookie on `id` must be host-only and `__Host-` prefixed so nothing on a sibling host can set it.

---

## 6 · What not to copy

| Atlassian | Here | Because |
|---|---|---|
| E-mail required | Phone-only and organisation-created accounts | Parents and pupils. Campus's phone sign-in is live |
| A separate portal-only account type | One account type, plus "created by an organisation, reaches only it until claimed" | Portal-only accounts lead to [duplicates](https://support.atlassian.com/jira/kb/duplicate-account-issues-in-jira-service-management-cloud/) and a [one-way migration](https://support.atlassian.com/user-management/docs/migrate-a-portal-only-customer-to-atlassian-account/), and the spec promises one login for life |
| No real merge | Merge and split from the first day | Shared phones make duplicates likelier here. TuteCore and Campus already have these tools |
| Products without an organisation | Every instance has one, always | Atlassian is still retrofitting this |
| An edge, a Tenant Context Service, separate services | One monolith and one `instance` table | The spec's own rule, and Atlassian's scale isn't ours |
| Quotes, order objects, invoice groups | Plans, periods, payments and invoices, as Desk has them | Far smaller, and enough for one company selling in one currency |
| Moving users opt-in at next login | Move Campus's accounts in one planned step, school by school | Campus had 6 active and 201 inactive accounts on 5 November, so a long opt-in isn't needed. Admins' loss of control is still worth planning for |
| Organisations at `admin`, apart from sign-in | Everything at `id.tutelora.com` (the Architect's decision, IA-2) | One address is simpler for people. The cost is that organisation and billing pages share a browser origin with sign-in, which the rules below answer |

### Keeping `id` safe with everything on it

A fault in any page on a host can reach that host's sessions, and these sessions open every product. So these are rules for `id`, not options:

- **No third-party scripts,** with one named exception: Turnstile on the sign-in and sign-up pages (CL-6, chosen by the Architect, 7 November 2026). A strict Content Security Policy: no analytics, chat or support widgets on `id`. Tutela's widget belongs to the
  products, not here.
- **Uploads aren't served from `id`.** Organisation logos and other files come from another host, because an uploaded file opened on this origin
  could reach the session. SVGs especially.
- **Payment leaves `id`.** When billing arrives, people go to the payment provider's hosted page. No provider script runs here.
- **Step-up for what matters.** Changing people, the organisation, billing or security asks for a fresh check. TuteCore's step-up does this.
- **Staff stay elsewhere.** The staff console stays at `api.tutelora.com/console`, so god mode never shares the public sign-in origin.
- **Keep the door open.** Organisation and billing routes sit in their own route group, so they could move to another host later without a
  redesign, though their addresses would change.

---

## 7 · How the spec's scenarios run

1. **A school joins from a product.** Ama clicks "Start free" on `tutecampus.app` and goes to `id.tutelora.com` with Campus named in the
   request. She creates her account and registers Jaeda: the record has no product on it. Subscriptions then grants Campus Free, Campus
   makes its tenant, the instance is recorded, and she lands back in Campus.
2. **Starting at `id`.** The same, with no product: an account, an organisation if she wants one, and nothing else.
3. **Adding a product.** At `id.tutelora.com`, "Add TuteBooks" creates an entitlement and an instance. The school's details are
   already there, and she picks who gets access.
4. **Teachers join.** An admin adds a teacher by e-mail or phone, at `id` or inside Campus. The teacher is invited, creates an account at
   `id` or signs in with the one they have, and lands on the school's Campus address. An account alone gives no access to a school.
5. **A teacher at two schools.** One account, two memberships; he picks a school after signing in.
6. **One person, different roles.** Memberships in each organisation; detailed roles stay in the products.
7. **Someone leaves.** Removed once at `id`. Their memberships and access end, each product hears by signed webhook and ends its local
   session, and the account stays.
8. **Someone only handles billing.** A billing role, not an organisation admin role. They sign in and work at `id`, seeing subscriptions,
   renewals and invoices but not people or settings, and need no access to the product (IA-11).
9. **Paying.** "Jaeda has Campus on Free and Books on Pro", on one billing account. The billing admin chooses a plan at `id`, pays on Paystack's page
   by card, which renews itself, or mobile money, paid ahead with reminders, and comes back. Unpaid, the product falls back to Free.
10. **A parent or pupil.** The school invites them or creates the account, or they arrive through its own domain. The account reaches only that
    school until the holder proves their phone or e-mail (below).

### The hosts a person sees

Decided: IA-1, IA-2 and IA-11.

| Doing what | Host |
|---|---|
| Starting from a product ("Start free") | The product's domain, such as `tutecampus.app` |
| Creating an account, signing in, registering an organisation | `id.tutelora.com` |
| Daily work | The school's Campus address, such as `jaeda.tutecampus.app`, or its own domain |
| Running the organisation: people, products | `id.tutelora.com`, or inside the product for adding people |
| Renewals, invoices, billing issues | `id.tutelora.com` |
| Opening a short link | `tutel.ink` |
| Product servers calling Atrium; no person sees this | `api.tutelora.com` |

**Corporate e-mail and phone** work as sign-in identifiers, with two catches. The account is still the person's, so someone who leaves
loses that address, which is why an account should be able to hold a second identifier. And a phone must receive SMS, so a landline can't
get codes, and under "one number, one account" a shared office number can only belong to one person.

### Adding people from two places

**Decided by the Architect, 6 November 2026:** a school's admins can add people both at `id.tutelora.com` and inside the product. What that
requires, for discussion with Clavis:

- **One action, two doors.** Atrium owns the membership. A product never writes one itself; its screen calls Atrium through the API, then saves
  its own detailed role, such as class teacher of JHS 2.
- **The product decides who may add, from its own roles** (CL-9, decided 7 November 2026). Its key adds a person to an organisation holding that product, naming the admin who acted. Atrium doesn't judge the admin, which is safe because a membership grants nothing in any product (CL-16).
- **If Atrium is down,** the product's screen says so and the admin tries later, as the spec plans for new sign-ins. A retry can't add someone
  twice, because the call carries an idempotency key.
- **In the Atrium client library,** so every product gets the same flow.

### Parents and pupils: reaching `id` quietly

**Decided by the Architect, 6 November 2026 (IA-5):** one account type for everyone. Parents and pupils arrive by invitation or through the
organisation's own web address (`portal.sais.com`), and reach `id` quietly in the background. It's the web address, not an e-mail domain: having
an `@sais.edu.gh` address gives nobody an automatic link to that school, unlike Atlassian's verified domains.

What quiet can mean in practice:

- **No registration step.** Nobody is asked to "create a Tutelora account". The invitation carries what the school already knows, and the account
  is made behind the scenes when the person proves their phone or e-mail.
- **Already signed in:** the school's site sends the browser to `id` and straight back. They see a blink, or nothing.
- **Not signed in:** they prove who they are once, with a code. That page is on `id`, wearing the school's name and logo rather than ours, so it
  reads as the school's.
- **A full redirect, not a hidden frame.** Browsers increasingly block the third-party cookies a hidden frame would rely on.
- **Each school's address is on Atrium's list** (CL-18, decided 7 November 2026). Atrium only returns people to addresses on it, and keeps it itself: the organisation's custom domains, proved once.
- **A product's page never takes a credential.** Otherwise the sign-in protection in §6 means nothing, and any compromised product could collect them.
- **Who holds what until proved.** An account the school set up reaches only that school until its holder proves the phone or e-mail. An invitation
  proves it at first use.
- **If the address bar must never show `id`,** Atrium's page could be served on a sub-domain of the school's own (`signin.portal.sais.com`). That means
  a certificate per school, so it's a later plan, not the first version.

---

## 8 · Decisions

| # | Decision | Recommended | Alternative |
|---|---|---|---|
| **IA-1** | Hosts | **Decided by the Architect, 6 November 2026:** `id.` and `api.` both on `tutelora.com`, replacing the spec's `tutelora.app` | · |
| **IA-2** | Where organisations live | **Decided by the Architect, 6 November 2026:** registered and run at `id.tutelora.com`, with no separate `admin` host | · |
| **IA-3** | Ways in | **Decided by the Architect, 6 November 2026:** both, alone at `id` and from a product's "Start free". The record has no product on it either way | · |
| **IA-4** | An account with no organisation | **Decided by the Architect, 6 November 2026:** allowed, as at Atlassian. Open sign-up by phone costs money per text, so Campus's cost brake comes across, adapted for people with no organisation yet | · |
| **IA-5** | Parents and pupils | **Decided by the Architect, 6 November 2026:** one account type. They arrive by invitation or through the organisation's own web address, such as `portal.sais.com`, and reach `id` quietly in the background (§7) | · |
| **IA-6** | The first subscription subsystem | **Decided by the Architect, 6 November 2026:** self-service billing from the start, adapting Desk's, alongside catalogue, entitlement, instance and access. I had recommended leaving payment out at first | · |
| **IA-7** | Where phone sign-in lives | **Settled by the Architect's rule, 6 November 2026:** in Atrium only, as a recorded exception. Products reach it through the Atrium client library, which the spec already lists as shared code. A system that keeps its own login just doesn't use it | · |
| **IA-8** | A school's name, logo and contacts after the move | **Decided by the Architect, 6 November 2026:** owned by Atrium; Campus keeps read-only copies, updated by webhook, so its 182 `tenant->name` reads don't change | · |
| **IA-9** | When the two new subsystems are built | **Decided by the Architect, 6 November 2026:** the organisation record and subscription core join the foundation; self-registration and the organisation pages come with Clavis. The rest of M00's order stands | · |
| **IA-10** | Names | **Decided by the Architect, 6 November 2026:** Clavis becomes accounts only. **Album** for organisations (the Roman public register) and **Tabula** for subscriptions (the tablet a contract was recorded on). Their IDs in code are `organisation` and `subscription`, singular under the house rule; the spec's existing plural IDs stay as they are for now | · |
| **IA-11** | Where billing is handled | **Decided by the Architect, 6 November 2026:** at `id.tutelora.com`, with a billing role apart from organisation admin | · |

**Also decided:** a school's admins can add people both at `id` and inside the product (§7).

### What billing now requires

**Tabula isn't all of Aerarium.** The spec's cash desk covers money a product collects from *its* customers: school fees, chapter dues. Billing here is
**Tutelora charging its own customers,** which is a different job with a different merchant. Desk's Paystack code is this second kind, so it moves to
Tabula. That leaves Campus as the only product collecting from its customers today, so the spec's trigger stands: Aerarium proper waits until Loop takes dues
online. The one place that talks to Paystack is still built once: gateway and webhook handling go in the `payments` module as its first slice, with
Tabula as its first caller.

**It can't land before Clavis.** Someone has to be signed in at `id` to pay. So the catalogue and entitlements stay in the foundation (IA-9), and
billing follows Clavis in the order.

**What comes from Desk (M18b):** plans with monthly and yearly prices, one row per paid period, card renewals by our own scheduler with a saved
authorization, mobile money paid ahead with reminders, invoices and receipts kept as issued, VAT settings, a grace period and founding price, and one
switch. It has never run on a server, so it comes across with its tests and gets proved here. Its plans have no product column and it reads through Desk's
`Rls` and `Tenant`, so those are rewritten.

**Decided by the Architect, 6 November 2026: TB-1 to TB-7, as recommended below.**

| # | Decision | Recommended | Alternative |
|---|---|---|---|
| **TB-1** | What a price is based on (no document settles this) | A list price per offering, monthly and yearly, with an agreed price possible for one organisation, so self-service and "agreed per institution" both hold | Priced by institution size, in bands, as the public site says |
| **TB-2** | Switching it on | Built now behind one switch, as Desk's is. On when prices are set and the public site's "nothing is charged without a written agreement" has changed | On from the first release |
| **TB-3** | When a period goes unpaid | Falls back to the product's Free offering: it keeps working within Free's limits and nothing is deleted (Desk's rule) | Locks after a grace period |
| **TB-4** | Schools already on agreed terms | They keep their terms until the agreement ends, with Desk's grace period and founding price available | All move at switch-on |
| **TB-5** | Merchant, currency and tax | Tutelora Limited, through Paystack, in cedis. **Corrected 6 November 2026 after reading the law:** VAT from the first charge, not "none until registered" as Desk has it, because services have no threshold. 20% effective, on separate lines, with invoices through the GRA's E-VAT, and a school able to withhold (`reji/docs/reference/tax-ghana.md`). It assumes Tutelora has its own live Paystack account, which I can't see | · |
| **TB-6** | SMS credits | Stay in Nuntius with its wallets, and use the same checkout later. The public site sells them separately | In Tabula from the start |
| **TB-7** | How many bills per organisation | One billing account per organisation to start, as the spec's "one bill". Its structure stays separate, so a second can be added | Several from the start, as Atlassian allows |

**Ghana's tax law adds to Desk's code.** Read on 6 November 2026, with sources, in `reji/docs/reference/tax-ghana.md`. A subscription sold to a school is taxable at an effective
20%, and because the school's own supplies are exempt, it's generally a real cost to the school. Three things are new work: tax invoices cleared through the GRA's E-VAT by API, a payment marked net of
withholding (7.5% withholding tax, or 7% withholding VAT) with its certificate, and rates held as dated data.

**Before billing is switched on,** these are still needed, and none of them blocks building it:

- The prices themselves, and each product's Free offering and its limits (TB-1, TB-3).
- The public site's "nothing is charged without a written agreement" changed (TB-2).
- Tutelora's VAT registration and its E-VAT set-up with the GRA, and its own live Paystack account (TB-5).
- Which schools are on agreed terms, and until when (TB-4).

---

## 9 · What it will take

Each step is still gated: discussed, planned, mocked up and reviewed before it's built. **Steps 1 to 7 are Atrium's. The TuteCore repository isn't
changed at any step.** Steps 8 and 9 are other repositories' work, each with its own plan and discussion when the time comes.

| Step | Where | What | Size |
|---|---|---|---|
| **1. Decide** | · | Done, 6 November 2026: IA-1 to IA-11, then one sweep of M00, AF, `PROJECT.md` and the map (§10). Done too: TB-1 to TB-7. Still open: AF and BO decisions | S |
| **2. Prove OIDC** | Throwaway | Provider on Laravel 13, this schema, return addresses per server and tenant, a phone-only sign-in, two domains. Go or no-go. Do this early, because it can change Clavis's shape | S |
| **3. Foundation, revised** | Atrium | AF as it stands, with `server` for `app`; the organisation record; catalogue, offering, entitlement, instance; the console's dashboard, organisations and usage | L |
| **4. Nuntius send path** | Atrium | Unchanged. Sign-in codes need it | M |
| **5. Clavis** | Atrium | Accounts without organisations; identifiers and `lets()`; Campus's codes, cost brake, matcher and merge; OIDC; the pages at `id` for accounts, registering and running organisations, products and the billing role, under §6's rules; organisation-created accounts | L |
| **6. Billing** | Atrium | Tabula's plans, payment and invoices adapted from Desk; the gateway as the `payments` module's first slice; the billing role and pages at `id`; E-VAT clearance and withholding; behind one switch | L |
| **7. Client library** | Atrium, as a Composer package | The server report behind the dashboard, OIDC client, local `user` keyed to the account ID, the add-a-person call, removal webhook, tests. The spec lists an "Atrium client library" as shared code | M |
| **8. Campus moves** | Campus, Atrium | Below | XL |
| **9. The others** | Desk, Books, Loop | Desk: e-mail only and undeployed, so it can launch on central sign-in and Tabula, with no migration and without switching on its own billing. Books: no tenants yet, starts fresh. Loop: phone and password with its own `persons`, so a real move | M each |

### What Campus's move involves

Counts are from reading the code on 6 November, and are token and line counts, not call-site analysis.

- **Goes to Atrium or is retired once proven:** `Services/Auth` 2,839 lines, `Controllers/Auth` 1,698, about 1,500 more, auth pages 2,960,
  and `Feature/Auth` tests 3,161. `Services/Identity` and `Services/Accounts` (about 2,200) are the joins.
- **Stays:** the tenant row as the local key (129 foreign keys, 4,297 `tenant_id` tokens), `users` as a foreign key target (about 169) with the
  account ID on it, role rows, per-school `people`, host resolution and the school-specific columns.
- **`users` loses** password, remember token, two-factor columns, password-change columns and sign-in phone columns.
- **To solve:**
  - Passkeys are bound to Campus's domain, so they can't follow; people re-enrol at `id`.
  - Password policy is per school today, and one person can be at two schools.
  - Step-up asks for a local password.
  - Campus's Google and Microsoft sign-in moves.
  - A commercial rate sits inside `education_system_profile`.
  - School profile changes have their own approval and lock.
  - The per-app Service identity needs an answer under delegation.
- **How:** behind a switch, one school first, with Campus's own sign-in kept until it's proved (policy P4). Campus's one-use `SchoolHandoffs`
  token is close prior art for the return from sign-in.

**Exceptions to record in `PROJECT.md`, with the handbook left as it is (AF-1):** 0.1 (a service products depend on), 1.2 (the organisation named in a
request), 12.6 (app keys, sign-in by delegation), 13.3 (foundation changes made here, not in TuteCore), and 2.3 when Campus moves.

---

## 10 · What this changed in existing documents

The plans, the project record and the map were changed on 6 November 2026. The spec itself wasn't edited, because its diagrams show the old design too;
`reji/docs/spec-amendments.md` records what overrides it.

| Document | Said | Now says |
|---|---|---|
| Spec | Sign-in at `accounts.tutelora.app`, `api.tutelora.app` | `id.tutelora.com`, `api.tutelora.com` |
| Spec | Organisations registered "with the list of Tutelora products it has switched on" | No product information; a subscription subsystem |
| Spec, M00 | Accounts and organisations are one module | Two modules plus Subscriptions |
| AF | `app`, `app_tenant`, staff console over apps | `product`, `server`, `entitlement`, `instance` |
| Spec, Step 0 | Decides for each gap "whether to extend TuteCore or add it in Atrium" | Add it in Atrium, always |
| Spec, AF, IA | Branding-neutral, a brand registry, per-consumer looks | Out of scope (the Architect, 6 November 2026) |
| M00 | Seven modules | Adds Album and Tabula (IA-9, IA-10) |
| M00 | Payments only when a second product needs them | Tutelora's own billing in Tabula from the start; fees and dues stay with Aerarium (IA-6) |
| Map, `PROJECT.md` | `accounts.tutelora.app`, the current modules | The new hosts and subsystems |

---

## 11 · Risks and what isn't known

**Risks.**
- **One point of failure.** If `id` is down, new sign-ins stop across every product. Sessions already open continue, as the spec plans.
- **One target.** A breach of `id` reaches every product, and with organisations and billing on the same host (IA-2), a fault in those pages can
  reach sign-in sessions. §6's rules answer that, and it needs a security assessment before its first deployment.
- **Sign-in costs money.** SMS codes aren't free; who pays per product needs settling, and Campus's cost brake comes across.
- **Shared phones.** Families sharing a number collide with "one number, one account", which Campus has parked for learners. This is the
  design question most likely to hurt.
- **Children's data.** One central account per pupil across products changes who holds what about minors. **I haven't researched Ghana's data
  protection law on this; it needs proper advice before Clavis is approved.**
- **Campus is live.** Every step there must be reversible.
- **Billing before a pricing model.** The shape can be built with prices as data, but TB-1 decides the shape, so it comes first. Desk's code has never taken a
  real payment, so the first live charges deserve close watching.

**Not established.**
- From Atlassian: how sessions work across domains, token contents, whether one billing account spans several organisations, and its schema.
- From us: the pricing model; whether Tutelora is VAT-registered and has a live Paystack account; its E-VAT batch; the pilot date; school count; whether `tutelora.app`, `tutelora.dev` and `tutel.ink` are held (each returned
  SERVFAIL on 6 November, which proves nothing either way; the spec says `tutel.ink` is acquired).
- OIDC on this stack: step 2 exists to answer that.
