Archiboard

Plan chest

Every drawing on the board

36 drawings, one hand, one pen. Each links back to the sheet it belongs to. They are drawn to be read left to right, and each has a note in the margin that points at the part worth arguing about.

Three modules inside one process with the allowed dependency directions one deployable, one process, one database host billing public: IBilling internal: the rest catalogue public: ICatalogue internal: the rest notifications public: INotifier internal: the rest sideways: will not compile shared kernel arrows point down and inward; the kernel references nothing
Fig. 1. The only legal dependency directions in a modular monolith. The host may call a module's public facade, a module may call the kernel, and nothing may call sideways into a sibling's internals.
B-01 · The modular monolith is a legitimate destination
A context map with four contexts and one bought system tenant admin subscription = a contract catalogue subscription = a plan billing subscription = a charge notifications subscription = an opt-in U D U D U D published language: catalogue.v1 anti-corruption layer legacy accounting bought, not built one word, four correct meanings
Fig. 1. A context map for a small multi-tenant web application. U is upstream, D is downstream; the arrow points the way influence travels. Only the hatched system, which we did not write, sits behind an anti-corruption layer.
B-02 · Bounded contexts before microservices: drawing the seams
The dual write and the gap between the two writes POST /invoices invoice handler invoices 1 service bus topic 2 step 1 committed, step 2 threw, and nothing will retry it
Fig. 1. The dual write. Two systems, two writes, no transaction across them. The hatched band is the window in which the process can die with the invoice saved and nobody told.
B-03 · The transactional outbox with EF Core and Azure Service Bus
Sequence from the command to the outbox row to the bus handler sql database relay service bus insert invoice + outbox row one commit, or none select where SentAt is null a batch of 100 send, MessageId = row id set SentAt crash here and the row is sent again the broker never appears inside the database transaction
Fig. 2. The relay carries the row to the bus after the commit. The hatched gap is the reason delivery is at-least-once: the send has happened, the row has not yet been marked.
B-03 · The transactional outbox with EF Core and Azure Service Bus
The write path and the read path over one shared database write path POST /invoices/{id}/lines endpoint method Invoice aggregate DbContext, tracked read path GET /invoices?page=2 InvoiceListReader one SELECT flat record, untracked one database no ORM on this side same tables, same transaction log, two models
Fig. 1. The cheapest useful form of CQRS. The two paths share a database and share nothing else; the read side never loads an entity and the write side never returns a screen shape.
B-04 · CQRS without the ceremony
The same message arriving twice and the inbox insert that decides payments topic PaymentReceived MessageId 7f3a, delivery 1 PaymentReceived MessageId 7f3a, delivery 2 consumer INSERT into Inbox row inserted payment applied, commit error 2627 roll back, settle, move on the constraint decides, not an if
Fig. 1. Both deliveries reach the consumer and both attempt the insert. The primary key on (consumer, message id) is the only thing that distinguishes them, and it does so inside the same transaction as the payment.
B-05 · Idempotent consumers and the duplicate message you will receive
Two API versions routed through adapters to one domain model GET /api/v1/invoices/{id} GET /api/v2/invoices/{id} adapters: the only code that knows a version exists InvoiceV1 contract InvoiceV2 contract Invoice, the domain model one shape, no version in it billing db v1 still emits a field the domain dropped in 2024
Fig. 1. Two versions, two adapters, one domain model. The hatched adapter is the frozen one: it fabricates a field the domain no longer has, and that fabrication is the entire cost of keeping v1 alive.
B-06 · Versioning a public API for a thousand tenants
Three hosting options as a ladder of control against operational effort operational effort control where a team of five should land App Service PaaS, code or container pays: plan hours Container Apps KEDA, scale to zero pays: vCPU seconds AKS the cluster is yours pays: nodes, always on this rung did not exist until 2022; before it you climbed or you stayed
Fig. 1. The hosting ladder as I draw it today. The hatched area is the gap that stood open from 2018 to 2022; a small team either stayed at the bottom or climbed too high.
C-01 · App Service, Container Apps or AKS: hosting a .NET web application then and now
A global router in front of three stamps, each holding its own tenants Front Door one origin group per stamp tenant to stamp map stamp eu1, westeurope api + workers service bus tenant dbs tenants: 240 of 250 stamp eu2, westeurope api + workers service bus tenant dbs tenants: 61 of 250 stamp ch1, switzerlandnorth api + workers service bus tenant dbs tenants: 3 of 250 the only state shared by all stamps hatched: data never leaves the region
Fig. 1. One Front Door profile routes each tenant's subdomain to the origin group of its stamp. The stamps share nothing but the map that says who lives where.
C-02 · Deployment stamps: cloning the whole cell
A trace crossing API, queue and worker with the tenant id riding along API sets baggage once render queue Worker restores baggage tenant.id=4f2c in headers, then in message properties one trace as Application Insights shows it POST /renders tenant.id=4f2c sb.send sb.process tenant.id=4f2c render pdf sql insert without the id on the message, every span right of the queue would show tenant.id as empty
Fig. 1. The tenant id is set once in the API, travels as baggage, is written onto the message by hand, and is restored in the worker before its first span starts. The processor turns it into a tag on all five spans.
C-03 · OpenTelemetry in .NET: traces that carry the tenant id
Flag evaluation with the tenant context as input inputs tenant context id=4f2c plan=pro ring=canary flag definition Documents.NewEngine TimeWindow: after 1 Mar Targeting: 25% ring:canary Tenant: [4f2c, 9a11] IsEnabledAsync filters combined: Any hash(tenant, flag) is sticky refreshed every 30 s on: new engine off: old engine entitlements (plan) not a flag: lives in the tenant record and never expires
Fig. 1. The evaluator sees the tenant context and the flag definition and nothing else. Entitlements sit beside it, consulted by the code that needs them, and are not something a flag decides.
C-04 · Feature flags with Azure App Configuration: ship dark, reveal per tenant
Cost allocation tree from the subscription down to individual tenants subscription: 18,400 / month shared platform: 2,100 stamp eu1: 9,700 stamp eu2: 6,600 fixed floor: 4,200 variable: 5,500 divided by design capacity 250 split by measured drivers tenant A: 96 tenant B: 41 tenant C: 312 the hatched floor is divided by what the stamp was built for, not by the tenants on it today
Fig. 1. Three buckets, three rules. Shared cost is split equally, the floor is split by design capacity, and the variable lines follow measured drivers down to each tenant.
C-05 · The cost sheet: what a tenant actually costs you
The ladder of environments with the same Bicep module deployed at each rung modules/stamp.bicep one module, four parameter files dev dev.bicepparam B1, one stamp, min 0 test test.bicepparam P0v3, one stamp what-if, approval acceptance acc.bicepparam P1v3, one stamp, prod SKUs what-if, approval production prod.bicepparam P1v3 x3, two stamps done by hand, dated: DNS, Entra apps, secrets the same module at every rung; only the parameter file changes
Fig. 1. Four rungs, one module. The parameter file is the only thing that changes between them, and the two upper gates are where a human reads the what-if before anything runs.
C-06 · Bicep and the environments ladder
Two front doors and what sits behind each Door A: self-hosted Identity your login page mails, lockout, MFA SignInManager + UserManager AspNetUsers Door B: external identity provider OIDC challenge Entra External ID hosted login + MFA id_token + claims directory your app: cookie + ClaimsPrincipal code you patch and get audited for
Fig. 1. The two front doors. Behind Door A every box is yours to run; behind Door B you get an ID token and an invoice.
I-01 · ASP.NET Core Identity or Azure AD B2C: choosing the front door
The OpenID Connect redirect dance with the tenant resolved before the challenge your product (one deployment, many tenants) browser acme.myapp.be tenant resolver scheme = oidc-acme acme authority idp.acme.example callback /signin-oidc iss + tid checks cookie for acme host 302 to /authorize code + state Set-Cookie tenant known here, before any challenge
Fig. 1. The redirect dance for tenant acme. The host names the tenant before the challenge, so the policy scheme can forward to oidc-acme, and the callback lands on the same host so the same options validate the token.
I-02 · OpenID Connect for a multi-tenant web application: one issuer, many tenants
One authorization decision with the tenant membership lookup request + cookie policy Invoice.Edit TenantRoleRequirement handler per-request membership check tenant context: acme membership lookup user 42, acme cache: user + tenant get memberships miss Succeed or Fail keyed by user AND tenant, never by user alone
Fig. 1. One authorization decision. The handler asks for the user's roles in the current tenant, never the user's roles in general, and the cache key carries both halves.
I-03 · Authorization policies, requirements and handlers: roles that belong to a tenant
The two machine paths into the API path A: API key customer script API key handler X-Api-Key key hashes id + hash principal: tenant + scopes path B: client credentials customer service token endpoint client_credentials access token JWT bearer handler Bearer jwt signing keys principal: client + scopes rate limiter, partitioned by key or client API endpoints only the hash lives here
Fig. 1. Two machine paths, one principal. The key path looks up a hash in your table; the token path validates a signature against the issuer's keys. Everything after the principal is shared.
I-04 · API keys, client credentials and machine access
The admin consent flow between the customer tenant, Entra ID and your application customer's Entra tenant Entra ID your product Connect Microsoft 365 GET /adminconsent client_id, scope, state consent screen admin approves signs in service principal created redirect_uri callback admin_consent=True&tenant= sign in, read tid id_token with tid /authorize id_token tenant links acme -> tid tenant= is unauthenticated; trust only the tid claim
Fig. 1. The admin consent dance. The tenant value that comes back on the redirect is a hint; the tid claim in a validated id_token is the fact, and it only means something once it is in your link table.
I-05 · Entra ID multi-tenant applications and the admin consent dance
The anatomy of one ADR page ADR-004 Keep all tenants in shared tables accepted 2017-09-14 Context 12 tenants · 40 signed · 1 database at S3 Decision Consequences easier: one schema, one migration pipeline harder: restore one tenant to last Tuesday to police: a missed filter leaks rows What would make me revisit this supersedes: none · superseded by: none docs/decisions/0004-shared-row-tenancy.md numbered once, never renumbered numbers, not adjectives the tripwire: one line, and the only part that fired on its own in 2022
Fig. 1. One ADR page as a drawn sheet. Four sections and a status; the last line is the one that gets read when the numbers in the context stop being true.
K-01 · Architecture decision records: a page per decision
A publishing platform with everything connected to everything The publishing platform, as drawn in 2016 front end web app identity cms API service bus worker sql search index fifteen lines, no verbs
Fig. 1. Every component that existed, every connection that existed. Accurate, and useless: no line says what travels along it or why.
K-02 · How I draw a system before I build it
The same system drawn for one question Q: what happens when an editor publishes a document? editor publishes cms api document store writes the document service bus publishes DocumentPublished worker delivers reads the document search index indexes it fails, retries after 30 s alert pipeline real, but not this question (the alerts have their own sheet)
Fig. 2. Same system, one question. Six boxes, six arrows, each with a verb, and the failure path drawn while the pen was still out.
K-02 · How I draw a system before I build it
The four layers of Microsoft documentation and the question each answers opinion Well-Architected Framework five pillars, workload guides Azure Architecture Center patterns, reference architectures behaviour Product documentation one tree per service and library Samples repository github.com/dotnet/samples what does good look like read when deciding how do the pieces fit together read when combining services what does it actually do read when building does it compile read when the page stops making sense limits, date, considerations read these before the overview
Fig. 1. Four layers, four questions. The top two carry opinion and date slowly; the bottom two carry behaviour and are the only ones to trust about what a service does today.
K-03 · Reading Microsoft docs like an architect
Two requests drawn as arrows crossing the tenant boundary tenant boundary tenant A (company 1) API, tenant = A rows of A reads tenant B (company 2) API, tenant = B rows of B report reads rows of B one login which tenant is the token for? the arrow the ticket did not mention
Fig. 1. The report and the shared login, drawn as what they are. Both cross the hatched strip, and the hatched strip is the only thing that keeps company 1's rows out of company 2's screens.
K-04 · Saying no to the feature that breaks the tenancy model
The two alternatives that keep the boundary organisation: the report reads only here read model one crossing, outward, as the tenant, audited tenant A publish job rows of A reads totals publishes tenant B publish job rows of B reads totals publishes the shared accountant one identity membership A membership B has, with a role each token, tenant = A one at a time API resolves tenant sends switching tenant means a new token
Fig. 2. The alternatives. Left: each tenant publishes agreed totals outward into a read model the organisation owns. Right: one person, several memberships, one tenant per token.
K-04 · Saying no to the feature that breaks the tenancy model
Timeline 2010 to 2026, .NET releases above the line and lessons below What Microsoft shipped vermilion = the rewrite the hinge: the code did not survive it, the decisions did .NET 4.0 MVC 2 .NET 4.5 Web API EF 6.1 OWIN .NET Core 1.0 Core 2.1 LTS .NET 5 one .NET .NET 7 filters .NET 9 Aspire .NET 10 (2025) 2010 2012 2014 2016 2018 2020 2022 2024 2026 pen before keyboard wiki was the wrong place one issuer, many tenants rewrote it, kept the ADRs tenant in the middleware fell over at 340 tenants one builder, api + worker 400 lines of Polly deleted still saying no (K-04) What I learned one release every two years is enough to show the shape
Fig. 1. One line from 2010 to 2026, sampled every two years. Above it, what arrived on schedule; below it, what I learned late and at my own expense. The vermilion box is 2016, the only year in which the two rows had to agree with each other.
K-05 · Fourteen years of .NET web applications: what changed, what did not
The five strategies of the standard resilience handler wrapped around one outbound call your api 1. rate limiter, 1000 concurrent 2. total timeout, 12 s 3. retry, 2 attempts, jitter 4. circuit breaker, 10% / 30 s 5. attempt timeout, 3 s exactly one HTTP send search service open here and nothing below runs without jitter every instance retries in the same millisecond
Fig. 1. The pipeline reads outward. The innermost timeout bounds one attempt, the retry decides how many attempts, and the outer timeout bounds the wait for the caller regardless of what happens inside.
R-01 · Retries, timeouts and the circuit breaker: Polly then, Microsoft.Extensions.Resilience now
Two cache layers with a tenant-prefixed key in front of a shared database instance 1 api L1 IMemoryCache this process only, 30 s instance 2 api L1 IMemoryCache this process only, 30 s the two L1 caches never agree L2 Azure Managed Redis shared by every instance, 10 min miss in both tenant db the key, in both layers t:0042:pricelist:7:v3
Fig. 1. Both layers are addressed by the same string. The hatched prefix is the only thing that stops instance 2 handing tenant 0042 data to tenant 0051.
R-02 · Caching layers for a web application: in-process, Redis, and HybridCache
Per-tenant token buckets in front of one shared database tenant 0042 tenant 0051 tenant 0077 one partition per tenant plan: pro 200 tokens, 100 per 10 s plan: free, empty 20 tokens, 10 per 10 s plan: free 20 tokens, 10 per 10 s 429, Retry-After: 8 shared one elastic pool the limit exists to protect this, not the API
Fig. 1. Each tenant gets its own bucket, sized by plan. Tenant 0051 has drained theirs and is being told to come back in eight seconds, while the other two carry on untouched.
R-03 · Rate limiting the noisy neighbour
Two instances racing for a blob lease before running a scheduled job instance 1 InvoiceRunService timer, 02:00 UTC instance 2 InvoiceRunService timer, 02:00 UTC acquire, 201 Created 409 conflict blob lease leases/invoice-run invoices runs exactly once no lease, does nothing the holder renews every 20 s; if it dies the lease expires in 45 s
Fig. 1. Both instances wake at 02:00 and both try to acquire the same blob lease. One gets 201 and does the work, the other gets 409 and goes back to sleep.
R-04 · Background work: hosted services, queues and the job you must not run twice
A load profile shaped like the real tenant base, next to the metrics watched during the run the load shape, per tenant 3 big 40 small 60% of the traffic one run what you watch during it p95 latency, per tenant pool DTU or vCore percent queue depth and message age 429 and 503 rate, per tenant flat load across 500 identical tenants tests a product you do not have
Fig. 1. The generator on the left, the dashboard on the right. Every metric on the right is read per tenant, because an overall p95 that looks fine can hide one customer at nine seconds.
R-05 · Load testing a tenant-shaped system
Three tenancy models side by side database per tenant app tenant A tenant B one backup, one restore per tenant; the pool shares the compute schema per tenant app tenant_a.Invoices tenant_b.Invoices one restore restores everyone shared rows with a tenant id app tenant invoice A 1042 B 1043 A 1044 the only fence is this column
Fig. 1. Three ways to slice a tenant. From left to right you trade isolation for density; the hatched column on the right is the only thing keeping tenant A out of tenant B's invoices.
T-01 · Three ways to slice a tenant
The request path through the tenant-aware pipeline resolver runs first: the OIDC authority depends on the tenant request tenant resolver authentication authorization endpoint response ITenantContext (scoped) sets, once which authority? DbContext tenant id for the query filter background job, no HttpContext message carries tenant id new scope, set ITenantContext handler
Fig. 1. The tenant is resolved once at the edge and then travels as a scoped service. A background job has no edge, so it creates its own scope and sets the same service before calling the same handler.
T-02 · Tenant resolution in the middleware
Where the global query filter is applied and the three holes around it LINQ query query pipeline tenant filter added here SQL shared db around the fence IgnoreQueryFilters() SqlQuery, ExecuteSql entity without a filter second fence: RLS keyed on SESSION_CONTEXT
Fig. 1. The filter lives in the query pipeline, so anything that skips the pipeline skips the filter. The dashed line on the right is the second fence: row-level security in the database, which does not care how the SQL was produced.
T-03 · EF Core global query filters as a tenant fence, and where they leak
A tenant catalog routing an application to shards in two elastic pools app 1. which shard? catalog tenant shard pool 4711 shard-02 A 0042 shard-07 B cache this; it is a single point of failure 2. connect elastic pool A (standard) shard-01 shard-02 shard-03 per-db max caps a neighbour elastic pool B (premium) shard-07 shard-08 one tenant per shard here move a noisy tenant
Fig. 1. The application asks the catalog once, then connects straight to the shard. Pools are budgets around groups of shards; moving a database between pools changes its budget, moving a tenant between shards changes its address.
T-04 · Sharding Azure SQL with elastic pools and a catalog
Layers of per-tenant configuration resolution and where the result is cached resolving Invoices:MaxLines for tenant 4711 1. tenant override catalog row for 4711: MaxLines 2000 not set? fall through 2. plan entitlements plan Pro, shipped with the code: MaxLines 500 not set? fall through 3. product defaults appsettings.json: MaxLines 100 what the tenant paid for, not a feature flag HybridCache key tenant:4711:settings:v17 resolved once IOptionsSnapshot<InvoiceOptions> per request entitlement changed bump Version: v17 becomes v18
Fig. 1. A setting resolves override, then plan, then default, once per version of the tenant's settings. The version is part of the cache key, so a change shows up without anyone having to evict anything.
T-05 · Per-tenant configuration and entitlements
The onboarding saga with its compensating steps and the point of no return orchestrator (Durable Functions or state row) register in catalog provision database identity tenant DNS and domain seed data online and welcome mail on failure mark failed drop database delete identity unbind domain nothing: db is gone retry until sent left of the line: undo. right of it: retry until done
Fig. 1. Every step left of the dashed line has a compensation that runs in reverse order when a later step fails. The last step has none; once the tenant is Online and the mail is out, the only correct move is forward.
T-06 · Onboarding a tenant is a saga