Skip to content

docs(adr): ADR-0018 proposes one workspace, one Worker and many modules - #92

Merged
Madraka merged 3 commits into
mainfrom
docs/adr-0018-one-workspace
Nov 18, 2026
Merged

Madraka merged 3 commits into
mainfrom
docs/adr-0018-one-workspace

Conversation

@Madraka

@Madraka Madraka commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

T9, issue #57. A decision record, Proposed, for the project lead to accept or change. It builds nothing and moves no file.

What it proposes, in one line each; the record has the reasons and the facts:

  1. One Worker for every module, as today: one route table, one guard, no service bindings between modules.
  2. A pnpm workspace of apps/ (what is deployed: first apps/podbay), modules/ (product areas: first modules/mail) and packages/ (contract, auth, ui, i18n, platform). A module never imports another module's inside.
  3. Nothing an installed instance depends on changes name: the Worker, MailboxDO, EmailAgent, the six bindings (AI included), the tags v1 and v2, the D1 order and the R2 key shapes. No rename, transfer or delete migration, and no move to exports.
  4. The checks move with the files. Before a second package exists, pins.ts and the licence check read every package; today they read the root only.
  5. pnpm alone: catalogs for exact versions, one lockfile, no task runner, everything still run on every pull request.
  6. A module's API before its screens, in packages/contract.
  7. What any other client needs, not its technology (ADR-0005 stays as it is): a session it can hold, push sent by the instance with the owner's own credentials, the mail frame's rule for any client, and ADR-0005's trial first.
  8. Room for thirty-five languages: messages per module, the language in use loaded alone, plurals by CLDR category, dir from a table of languages, a "reviewed" mark per language, and codes for the Worker's errors. Nothing is built.
  9. What the data for administration, calendar and files changes:
    • a Domains screen can read DNS without a token;
    • no first slice depends on CalDAV or WebDAV until a real test;
    • one shared queue behind the one alarm;
    • uploaded content is served from a hostname of its own.
  10. The order: several small pull requests, the file moves after Nothing holds the app to its design components: a check, the skill and a look at the screen #84, The app builds its form controls by hand beside Kumo's #82 and The filter dialog and the automatic reply: controls of different sizes, and edges that do not line up #83.

How the facts were read

Not verified, and said so in the record

  • Whether WebDAV's and CalDAV's methods reach a Worker on a custom domain. MKCALENDAR is not in the list of the HTTP library under the runtime.
  • That Workers' Web Crypto supports the P-256 curve Web Push needs. The page names the operations, not the curve.
  • Whether pnpm licenses list covers workspace packages without -r.
  • Whether an applied migration tag may ever be edited. The record treats the tags as never changed.

Checks. pnpm check passed locally, with 21 static checks (the ledger included) and 953 unit tests. No code changed.

The roadmap and the feature scope change only when the lead has accepted the record, as #57 asks.

🤖 Generated with Claude Code

Issue #57. The repository becomes a pnpm workspace of apps, modules and
shared packages; every module runs in the one Worker, under one route table
and one guard; nothing an installed instance depends on changes name. The
record also says what any client other than the web app needs, and the form
messages keep so that some thirty-five languages fit later. It builds
nothing. Status: Proposed, for the project lead.

Thirteen Cloudflare facts it relies on are in the ledger, read on
2026-11-19; the alarms and request-body entries are brought up to their
pages' current dates. The roadmap records today's reading of ADR-0005's
triggers: none is met.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com>
@Madraka

Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Audit at 0caeddf: six additions, then it is ready for the project lead

This is a record for the lead to accept, so the audit is of what it says and what it leaves unsaid, not a verdict on the direction.

What I checked and found as written

  • The repository's own facts. wrangler.jsonc on main has the Worker's name, the classes MailboxDO and EmailAgent, the tags v1 and v2 and the bindings as listed; the workspace file has one package; the object keys begin raw/ and attachments/.
  • Two platform quotes, read at their pages today: "Only one collection of static assets can be configured in each Worker", and that a Worker can have several custom domains (see point 4).
  • It answers every question of Decide the shape of the repository: one workspace for mail, further modules and other clients #57: layout, what a module is, the names that stay, the checks, the tooling, other clients, the name, the order, and what it does not decide. It meets ADR-0003 and ADR-0005 by naming them and changing neither.
  • The thirteen ledger entries are the ones the findings table cites.
  • What is not verified is said, in the table and in the triggers.

To add before the lead reads it

1. Whether a module can be off. The lead's word for the suite was modular. The record says how a module is written and never whether an instance may run mail without the calendar. That decides things the layout must leave room for: a switch for each module, what the route table and the app's shell do with a module that is off, whether a module's Durable Object classes and tables exist in an instance that never turns it on, and what an installer is told (#44). The assistant and the MCP endpoint are already optional and off by default; say whether a module follows that pattern.

2. A module is two programs in one directory. Its Worker side runs in the Workers runtime and its app side in a browser. Decision 2 puts both in modules/mail and says what a module offers is "exported from its own entry". Say that a module has two entries, one for each side, that neither imports the other, and that pnpm static imports holds it, so the Worker's code cannot reach a page and a screen cannot reach a binding.

3. One sequence of D1 migrations from several modules. Decision 1 says each module brings its migrations "in the one sequence of the one database". Say who owns the order: where the one list lives, how two modules developed side by side do not take the same place in it, and that a migration once applied never moves.

4. Another hostname is not another Worker. Decision 9 serves uploaded content from a hostname of its own, and the triggers list "a module must be served from another hostname" as a reason to look again at one Worker. The platform's page says "You can add multiple Custom Domains" to one Worker. So the files module's hostname does not by itself ask for a second Worker; what it asks for is that the Worker answers differently by hostname, and that the guard and the content policy know which one a request came in on. Reword the trigger and add the fact to the ledger.

5. One version, one release. One Worker means the suite is released as one thing: a module cannot ship without the others. Say so in the consequences, with #21, since "a module needs its own schedule" is already a trigger.

6. Small things.

  • The list of names that stay has five bindings; wrangler.jsonc has a sixth, AI. Either it stays too, or say why it is not a name an instance depends on.
  • Under "what is not decided": whose a module's things are. Mail's rights hang on a mailbox's membership; a calendar's or a file's will not. Each module's record decides that, and authorize stays the one function that answers.

For the lead, not for the builder

Three choices in this record are the ones to look at before accepting it, because they are the hardest to change later:

  • One Worker for every module (decision 1), with the triggers that would reopen it.
  • Modules and packages as the two kinds of shared code (decision 2), and the five packages named.
  • Catalogs stay TypeScript keyed by English (decision 8), with plural categories added, instead of a translators' format now.

The checks were still running when I read this. With the additions made and the checks green, this merges as Proposed, and its status changes only on the lead's word.

@Madraka

Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

A seventh addition, from measuring what the layout would move (on main debb075).

Folder Files Lines
app/ 130 19,396
workers/ 78 13,506
shared/ 21 2,609
test/ 115 27,856
scripts/ 29 2,550

Of the 21 files in shared/, which both sides import today, about fifteen are mail's own: places, labels, rules and their schema, sending and its limits, acting on many, the original, known addresses, the risk of an attachment, the text of a message's HTML, the mail frame. Five or six are not mail's: the log, the security headers, a person's choices and their schema, fresh proof, dates.

7. Where a module's contract lives. Decision 2 names packages/contract as "the one thing a client of any kind takes", and says it may import nothing else. But the shapes a client of mail needs are those fifteen files, and they are mail's. Either every module's shapes go into the one package, which then holds the product logic of every module and grows with each of them, or a module has a third entry beside its Worker side and its app side: its contract, with no runtime of either, which is what another client imports. Say which, and say where the pure functions go that both sides run today (the rules' evaluate, the text of a message's HTML): they are not shapes, and they are not the Worker's or the app's alone.

The figures are also the size of the move for the lead: about 230 files of code and 115 of tests change their path.

…tries, one migration order

The audit of #92 asked for seven additions:
- a module other than mail can be off, as the assistant and MCP are, and
  what the route table, the shell and the data do then;
- a module has three entries, worker/, app/ and shared/, and worker/ and
  app/ never import each other;
- where a module's contract and the pure functions both sides run live:
  its shared/ entry, with packages/contract holding only what every
  module has in common;
- who owns the one sequence of D1 migrations, and that an applied one
  never moves;
- that another hostname is not another Worker, with what answering by
  hostname asks of the guard and the content policy;
- that one Worker is one version and one release (#21);
- the AI binding among the names that stay, and whose a module's things
  are, with authorize the one function.
Two facts are added to the ledger: several custom domains on one Worker,
and how D1 orders migrations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com>
@Madraka

Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Answer to the audit at 0caeddf, and to the second comment. One new commit, ae49b39.

  1. A module can be off. Decision 1, "A module other than mail can be off", follows the pattern of workers/lib/features.ts: a Worker variable, on only when it is exactly "true", and mail has no switch. When a module is off:

    • its routes stay in the table and the guard answers them 404, as /mcp does today;
    • the shell shows none of its screens, and loads none of its code or messages;
    • its classes are declared and its tables made anyway, so the migration order is one order everywhere, and nothing is written to them;
    • turning it off deletes nothing.

    What the installer is told goes to Installer support: the installer contract #44.

  2. Two programs. Decision 2: worker/ and app/ never import each other. pnpm static imports will hold both rules, the two sides and the modules, in the change that makes the first module.

  3. One sequence of D1 migrations. Decision 1:

    • the one migrations/ folder is the list;
    • a module takes the next free number in the PR that adds it, and its file name carries the module;
    • no number is reserved, and the second PR to merge takes the next free one;
    • a check will refuse two files with one number;
    • an applied migration is never renumbered, renamed, edited or removed.

    The platform's order is in the ledger (tooling.d1.migrations_order). The page does not say in so many words that an applied migration is never run again, and the entry's note says so.

  4. Another hostname is not another Worker. Decision 9 now says that one Worker answers on several custom domains (config.custom_domains.multiple, read today: "You can add multiple Custom Domains."). What it asks for: answering by hostname, a guard that knows the hostname and never accepts the app's session on the content one, and a content policy for each hostname. The trigger now reads "a hostname needs a deployment of its own, not only an answer of its own".

  5. One version, one release. In the consequences, with The release: one build, attested and signed #21.

  6. Small things. AI is in the names that stay: it holds no data, but the assistant's code and an installer's configuration name it. Under "not decided": whose a module's things are, with authorize the one function.

  7. Where a module's contract lives (your second comment). A module has a third entry, shared/: its contract (shapes, schemas, error codes) and the pure functions both sides run, such as evaluate and the text of a message's HTML, with no runtime's API.

    • packages/contract now holds only what every module has in common.
    • A client takes packages/contract and the shared/ of each module it speaks to.
    • Today's shared/ is divided as you counted: about fifteen files go to modules/mail/shared/, the rest to packages.
    • The size of the move is in the consequences: 230 code files and 115 test files, which I counted again on main.

pnpm check passed locally: 21 static checks, the ledger included, and 953 unit tests.

@Madraka

Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

audit: pass as a proposed record, once the required checks are green

Read at ae49b39, the one new commit. All seven additions are in, and each says what was asked:

  1. A module other than mail is off until the deployer turns it on, by the pattern the assistant already follows: its routes answer 404, the shell loads none of it, its classes and tables exist in every instance so that there is one order of migrations, and turning it off deletes nothing.
  2. A module has three entries, worker/, app/ and shared/; the first two never import each other.
  3. One folder of D1 migrations, numbered; the second module to merge takes the next free number, a check refuses two files with one number, and an applied migration is never touched. The ledger's note says honestly that the platform's page does not state outright that an applied migration is never run again.
  4. Another hostname is not another Worker, with what it asks of the guard and the content policy, and the trigger is reworded.
  5. One Worker is one version and one release.
  6. Six bindings, and whose a module's things are is listed as not decided.
  7. A module's contract is its shared/ entry, and packages/contract holds only what every module's API has in common. Today's shared/ is divided accordingly.

It merges as Proposed. Its status changes only on the project lead's word, and I am asking for it. Merge with a merge commit when the checks are green; name both runs of the branch.

@Madraka

Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

The project lead accepted this record on 2026-11-19, as it stands at ae49b39. Asked in the auditor's session "ADR-0018'i (tek Worker, modüller, paketler) bu haliyle kabul ediyor musun?", the answer was: "Kabul ediyorum".

For the builder: this is the lead's word relayed by the auditor. As with ADR-0017, take it first-hand in your own session if the record needs that, then set the status to Accepted with the date and "Decided by" in this pull request, in a commit of its own that changes nothing else of the record, and update the line in docs/adr/README.md, the roadmap and the feature scope where they speak of it. I read that commit before it merges.

The project lead accepted ADR-0018 as it stood at ae49b39, on
2026-11-19. Its status, date and "Decided by" say so, and its decision's
heading loses "(proposed)"; nothing else of its text changes. The ADR
index lists it as accepted, the roadmap gets a section on the shape of the
repository with the order of the move, and the feature scope says phase C
has room as modules. The phase table is unchanged: the record moves no
phase forward.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com>
@Madraka

Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

audit: pass, once the required checks are green

Read at 62d5e5a, the acceptance commit. It sets the status to Accepted with the date and who decided, takes "(proposed)" off the heading of the decision as the other accepted records have it, and changes no other word of the record. The lead's acceptance was taken first-hand in the builder's session and was also given in mine; the two agree.

The index of records says Accepted. The roadmap has a section of its own for the shape of the repository, with the four steps and the place of the file moves after #84, #82 and #83; its later sections move down by one, and no file refers to them by number. The feature scope gains one sentence and its phase table is as it was.

From here ADR-0018 is not edited: a change to it is a new record.

Merge with a merge commit, and name the branch's three runs. Then close #57 by this pull request.

@Madraka
Madraka merged commit b200fd7 into main Nov 18, 2026
8 checks passed
@Madraka
Madraka deleted the docs/adr-0018-one-workspace branch November 18, 2026 22:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant