Skip to content

Decide the shape of the repository: one workspace for mail, further modules and other clients #57

Closed

Description

@Madraka

The project lead set the direction on 2026-11-18: this repository becomes a monorepo. Mail is the first module of a suite; a calendar, file storage and bookings follow as modules developed as packages; a mobile app may come later. Today the repository is one package with one Worker and one single-page app, and the feature scope lists calendar, booking and files as phase C, "decided after phase B".

Nothing is moved yet. A change of layout touches every path, every check and several sticky names, so it starts with research and a decision record that the project lead accepts (GOVERNANCE.md).

The decision record must answer

  • The layout. Which directories are apps (the mail Worker and its web app, later a mobile app) and which are packages (what mail, a calendar and files would share: sign-in and access, the design components, messages and languages, the storage and logging helpers, the contracts of the API). What stays out of a shared package on purpose.
  • What a module is. How a module brings its routes, its rights in the route table, its Durable Object classes and migrations, its screens, its messages and its tests, and how the shell composes them. One Worker for all modules or one for each, and what that means for an installer and for the same-site rule of ADR-0003.
  • Sticky names survive the move. Durable Object class names, binding names, migration tags, D1 migration order and R2 keys of an instance that already runs must not change because a file moved.
  • The checks keep holding. copies.json (the seed's paths), the size and lint ratchets, the static checks that read paths, the Cloudflare ledger, the vendored skill hashes, the three test tiers, and the required status checks of the main ruleset: each either follows the move in the same change or is listed with what replaces it.
  • The tooling. pnpm workspaces alone or with a task runner; one lockfile; how versions stay pinned in one place; what CI runs for a change that touches one package.
  • Other clients. What a mobile app needs from the API that the web app gets for free today (a session a native app can hold, push), read together with ADR-0005, which already names its first candidate for a native client and the triggers to look again.
  • Names. Whether "Podbay" is the suite and mail one module of it, or Podbay stays the mail product inside a suite with another name; this meets the open name review (#4).
  • The order. When the move happens relative to the open work (the rules of ADR-0008, snooze and mute, version 0.1), so that no large pull request is open across it, and whether it is one move or several.
  • What it does not decide. Building a calendar, files or bookings is not pulled forward by this record (roadmap, section 6).

Done when

  • The research is written from current primary sources (pnpm workspaces, Workers with several entry points or service bindings, Durable Object migrations when a class moves), each fact in the ledger where it is a Cloudflare fact.
  • The record is proposed, and accepted or changed by the project lead.
  • The roadmap and the feature scope say what the accepted record changes.

Activity

  1. added
    decisionA decision record (ADR) comes before code
    needs leadOnly the project lead can close it
    area: repositoryThe repository itself: settings, governance, guidance
    on Nov 18, 2026
  2. Madraka commented on Nov 18, 2026

    @Madraka
    ContributorAuthor

    Data for the areas this record is about was collected on 2026-11-19, from current primary sources, and is in three issues: administration (#87), files (#85), calendar and booking (#86). None of them builds anything.

    A proposed order, for the project lead to accept or change

    This is the auditor's proposal from what was read; it decides nothing.

    1. Mail first, to the level its screens claim. The controls and their alignment (The app builds its form controls by hand beside Kumo's #82, The filter dialog and the automatic reply: controls of different sizes, and edges that do not line up #83) and the check that holds them (Nothing holds the app to its design components: a check, the skill and a look at the screen #84), then the browser tests that fail without a cause (Test flakiness seen once or twice and not explained #43), then what is open for version 0.1. A second module on screens that are not level would copy the fault.
    2. This record (Decide the shape of the repository: one workspace for mail, further modules and other clients #57). Before any module: where shared things live decides how each module is written.
    3. Administration (Administration: domains, mailboxes, activity and backups: what a decision needs to know #87). It is phase A of the feature scope already and serves mail directly. Its first piece, a Domains screen that reads DNS, needs no token and no new binding, so it is also the smallest proof of how a second area lives beside mail.
    4. Files (Files: what a decision needs to know #85). The store and the membership rules are already here, and mail gains from it at once (an attachment saved, a file attached). The hard part is serving a person's file without it ever running in the app's origin.
    5. Calendar (Calendar and booking: what a decision needs to know #86), invitations by mail first. A message that carries an invitation is shown and answered in mail before there is a calendar screen; the data is kept faithfully so that a sync protocol can follow.
    6. Booking (Calendar and booking: what a decision needs to know #86), last. It is a public page that makes the instance send mail to strangers: it needs a sending domain, a bot check and rate limits, and the calendar under it.
    7. Another client. After the modules have an API that a client other than the web app can hold a session on.

    What the data changes for this record

    • A Worker can resolve DNS itself, so a Domains screen does not reopen the decision that the Worker holds no account token.
    • Sync protocols are an open question on this platform. Whether the HTTP methods CalDAV and WebDAV need reach a deployed Worker is not verified, and the JMAP calendar specification is not an RFC yet. A module's first slice should not depend on either.
    • One alarm for each Durable Object means reminders, like outgoing mail, are a queue behind that alarm: a shared helper, not one per module.
    • Sending is a beta described as transactional, with a sending domain set up for each zone. Booking and invitations to people outside both lean on it.
  3. Madraka commented on Nov 18, 2026

    @Madraka
    ContributorAuthor

    Two things from the project lead on 2026-11-19 for this record.

    The focus now is the architecture and the shape of the whole, ahead of wording and translation. This record moves up accordingly: it is written next, before the work on the screens' controls.

    Languages: some thirty-five are expected later, not two. The record's part on what modules share should therefore answer, for messages and languages:

    • where a module's messages live and how the shell loads only the language in use, so that thirty-five catalogs do not travel with every page;
    • the form of a message that survives many languages (plurals, order of values, direction of writing), and whether the catalogs stay TypeScript objects keyed by the English text or get a format a translator's tool can read and write;
    • how a language is added, checked for completeness and marked as reviewed or not, without a person reading code;
    • how the Worker's own words (errors, mail it writes itself) get a person's language (The Worker's own words in every language #39).

    Nothing of this is built by the record; it is what the layout has to leave room for.

  4. Madraka commented on Nov 18, 2026

    @Madraka
    ContributorAuthor

    For the "other clients" part of this record. The project lead put the shape forward on 2026-11-19: the web stays on the stack it has; iOS, Android, macOS, Windows and Linux are separate clients, and every client talks to the same JSON API. That is what ADR-0005 already decides (decisions 2 and 4), with Exact as the first candidate for a native client.

    Exact says of itself that it changes daily, so it was read again today, two days after ADR-0005. Extracts through a summarising tool: each line is re-read at its source before it enters the record.

    Exact on 2026-11-19, against ADR-0005's triggers

    Trigger of ADR-0005 Today
    A tagged release, a stability statement, a packaged tool Not met. No release, tag or package; "pre-1.0 and changes daily", worked from a checkout. Nothing to pin (rule V1)
    A frame with an author-facing srcdoc and a sandbox, on the web and natively Not met, with one change: its guide for agents now describes reading an app's HTML file into a sandboxed srcdoc frame. The author-facing srcdoc and a veto on the guest's navigation are still withheld. Linux has no iframe; Android's has an open defect
    An editor for HTML Not met. Markdown only, and on Linux, Windows and Android it shows the source
    A React tier Not met. Interfaces are written in its own language; React components do not carry over

    Host by host, in its own words: the web, macOS and Linux "work"; iOS works on the simulator and on devices; Android and Windows are "early".

    What a mail client would lean on:

    • Sessions: native hosts have no cookie jar and are told to keep a bearer credential in a granted store. That store is the Keychain on Apple hosts and an unencrypted file on Linux; Android and Windows were not found.
    • Push: admitted for iOS and Android in the last ten days; credentials for Android's service stay with Expo. Not built for macOS and the web.
    • Background work, deep links, sharing, picking and downloading files exist in some form.
    • Accessibility: no screen-reader bridge on Linux. Languages: one file of strings for each locale; right-to-left lists are not supported; no plural rules were found.
    • Maintenance: about 86% of attributed commits are one person's; MIT; no roadmap is stated.

    The fallback picture today: the framework Expo itself documents targets Android, iOS and the web; macOS and Windows are partner projects of React Native with their own versions; Linux is community only.

    What this asks of the record

    The record does not choose a native technology. It makes the choice possible later, whichever it is:

    • A session a client other than the browser can hold. Today a session is a cookie under a same-site rule. A native host has no cookie jar. This meets the keys and grants of #24.
    • The API's contract as a package any client can take: the shapes of requests and answers, the error codes, the route table's rights, with nothing that only the web app knows.
    • Each module's API before its screens, so that a second client is never blocked on a screen's internals.
    • Push as something the instance sends, and who holds the credentials for it; the own-account rule decides what is acceptable.
    • The mail frame's rule stated for any client: a stranger's HTML is shown sanitised, without script, without navigation and without remote content. A client that cannot do that does not show HTML mail.
    • The trial ADR-0005 names, written as the first step of any native client: a hostile message shown safely on a phone, time-boxed, before anything else is built.
    • Which hosts are in scope first. By today's reading, iOS and macOS are the ones the candidate can be tried on.
  5. Madraka commented on Nov 18, 2026

    @Madraka
    ContributorAuthor

    Two references to the roadmap's sections in issues (this one's "roadmap, section 6", and the same words on #45) now mean section 7, "How the direction changes": #92 gives the shape of the repository a section of its own before it.

  6. Madraka commented on Nov 18, 2026

    @Madraka
    ContributorAuthor

    Done by #92 (merge b200fd7): ADR-0018, accepted by the project lead on 2026-11-19. Every question of this issue is answered there. The research is from current primary sources, with each Cloudflare fact in the ledger. The roadmap (section 5) and the feature scope say what the accepted record changes. The move itself is in the roadmap's four steps; none of it is done yet.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: repositoryThe repository itself: settings, governance, guidancedecisionA decision record (ADR) comes before codeneeds leadOnly the project lead can close it

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions