Duolith docs

0170. The server work is built in full, and proven on one example: a social app and its website

  • Status: Accepted (Mik, 18 Nov 2026)
  • Date: 2026-11-18
  • Decided by: Mik, 18 Nov 2026: "Build out everything but don't do it on workstable, I want a generic social media app and website as the example, things with payments and targeting and such to make it all easy". The design of the example and the order of work are the integrator's.
  • Planning item: docs/plan/server-roadmap.md

Context

Decisions 0163 to 0169 describe a server companion, domains, a request pipeline, transports and live updates, workflows, cost and infrastructure, and placing parts on their own servers. Earlier records said each would be proven by moving a domain of IDX-Studios/work-stable-api.

Asked for a sceptical review on 18 Nov 2026, the integrator recommended building much less: one slice on Bun and Postgres, proven on WorkStable, with the rest waiting until an app needed it. The reasons are recorded here because they do not go away:

  1. The scope is what several funded teams build (a server framework, a workflow engine, a load and cost tool, an infrastructure generator).
  2. Nothing is measured yet. Seven records, no server code.
  3. Five targets, five stores and two languages multiply every piece of work and every test.
  4. Security code we write ourselves has been tested by nobody else.
  5. Some parts have no app asking for them today.

Mik chose the full build, in line with his rule for this project ("only the best complete repo is the goal", 14 Nov 2026), and chose a generic example over WorkStable. This record takes that as settled and answers the risks with how the work is done, not with less of it.

Decision

1. Everything in decisions 0163 to 0169 is built

Nothing is cut and no target or store is dropped. The order is in docs/plan/server-roadmap.md. Version 1 stays client-only (13 Nov 2026) with its two server-free stages, and when the server packages start relative to version 1 is Mik's call.

2. One example proves all of it: Plaza

examples/social is a small social network called Plaza, with its public website, its web app and its iOS and Android apps, all from the same page files. It is generic on purpose: accounts, posts, follows, payments and promoted posts are what most products need some of, so an app author can copy the part they need.

It is one example, not eight, because the records' claims are about parts working together: a command that changes a model, refreshes a kept page, pushes to a live subscriber and starts a workflow that charges a card.

The domains (examples/social/domains/*.domain.yaml):

DomainWhat it holdsWhat it proves
accountsAccount, Profile, Session. Sign up, sign in, edit a profile, block someoneThe caller step, sessions, revocation, allow: rules (self, admin), personal and secret fields
postsPost, Comment, Reaction. Write a post, the feed, one postValidation, derived keys, the read cache, changes:, page of, live reactions and comments, kept public pages, answers cached at the edge, operation budgets
followsFollow. Follow, unfollow, who follows whomA workflow that fans a new post out to followers (each:), with fairness between accounts
mediaUpload. Receive a photo, check it, resize it, store itA workflow with an undo, needs: [storage], body limits, outbound calls
paymentsPlan, Subscription, Tip, Payout. Support a creator monthly, tip a post, pay a creator outOnce-keys, the outbox, a signed webhook, a workflow with a refund as its undo, needs: [paymentProvider], secrets
promotionsCampaign, Audience, Budget. Pay to show a post to a chosen audienceTargeting, a very high rate of small writes (impressions), rate limits, a budget spent by a workflow, and the part that load tests say should move to its own server
notificationsNotification. In the app, by push, and a daily digestLive models, event subscribers, a scheduled workflow
moderationReport, Review. Report a post; a person decidesA workflow that waits for a person (waits for:, up to seven days), admin rules, the audit trail, a command in another domain with an undo

The pages:

RouteHow its HTML is made (decisions 0162, 0163)
/, /pricing, /about, /helpWritten at build. No server involved
/@[handle], /post/[id]Kept: made on first request, refreshed when a command changes what they show. Public, so search engines and link previews read them
/home, /notifications, /settings, /promote, /adminPer request, or app routes. Never in a shared cache

Payments, made easy and done properly:

  • paymentProvider is one service with two implementations behind one interface. A fake ships with the example: it is deterministic, and the tests, the mock server and the crash test use it. Stripe in test mode is the second. No key is ever in the repository.
  • On iOS and Android, a digital subscription bought inside the app must go through the store. So the native apps use the store purchases of version 1 (work package 11.3) and the web uses the provider. Both end in the same command, payments.grant, so the rest of the system does not know which one it was.
  • Money is the money type throughout, a charge is a workflow that either completes or refunds, and every provider call carries a once-key.

Targeting, without becoming surveillance:

  • An audience is built only from what a person chose to say: topics they follow, their language, a coarse region, and "followers of this account".
  • An account has a personalised promotions choice, off by default where the law requires it. On iOS the tracking prompt of version 1 (work package 11.37) is honoured.
  • A campaign's owner sees counts, never people. An audience smaller than a set size is refused with a named failure (audienceTooSmall).
  • No sensitive category exists in the shapes, so none can be targeted. These are build-checked facts about the domain files, in the strict spirit Mik asked for.

3. How the example answers the review's risks

RiskWhat the work does about it
The scope is very largeWork packages are ordered so that Plaza runs end to end early and then gains a part with each package. A package is done only when its part of Plaza works and is tested
Nothing is measuredEvery package adds its benchmark, and no figure goes into the docs before it is measured on Plaza. Load tests use Plaza's own traffic profile (decision 0168)
The matrix of targets and storesThe conformance suite is written first, from the spec. Every package runs it on every target and store it claims. A target that fails is not listed as supported
Security code tested by nobody elseKnown test vectors for every token and signature check, the security conformance suite on every build, and an outside review before Plaza is put on the public internet with real payments. Until then, test keys only
Parts with no userPlaza is the user. Its impressions are the reason to move a part to its own server, and one acceptance test is that duolith advise recommends exactly that from Plaza's load run

4. What happens to WorkStable

It stays the source of the lessons in decisions 0164 to 0167, and a later adopter if Mik wants that. It is not the proving ground. The Elysia adapter of decision 0164 is still built, and is tested against a small Elysia app kept in the repository's test fixtures.

Alternatives considered

OptionWhy not
One narrow slice proven on WorkStable (the integrator's recommendation)Mik chose the complete build and a generic example. A private product is also a poor public example: nobody else can read it or run it
Several small examples, one per recordEach would pass alone, and the claims are about parts working together
A to-do list or a blog as the exampleHas no payments, no targeting, no high-volume writes and nothing worth a workflow, so most of the records would go unproven
Copy a real social productThe example must be generic and ours. Plaza takes common ideas (posts, follows, a feed) and no product's name, look or content

Consequences

  • examples/social becomes the largest example. It is built up by the work packages in the roadmap, each owning its own domains and pages so that parallel work does not collide.
  • The guide gains a path, "Build a social app", that follows Plaza part by part.
  • Statements in decisions 0164, 0165 and 0167 that a stage is proven by moving a WorkStable domain are replaced by this record: the proof is Plaza.
  • Needed from Mik later: a Stripe test account, a place to deploy Plaza (a subdomain of duolith.dev), and store sandbox products for the native apps.

Mik's answers (18 Nov 2026)

  • "Build out everything", on a generic social app with payments and targeting, not on WorkStable.
  • "Start everything now": the server packages begin beside version 1.
  • Accepted on 18 Nov 2026, together with decision 0171, which answers the risks this record lists.