diff --git a/content/labs/spec-drift/lab.mdx b/content/labs/spec-drift/lab.mdx index a85a3dc..76ef530 100644 --- a/content/labs/spec-drift/lab.mdx +++ b/content/labs/spec-drift/lab.mdx @@ -6,6 +6,7 @@ topic: "spec" preview: "gate" tags: ["spec-driven", "quality"] writing: "from-intent-to-proof" +themes: ["quality-test-strategy", "delivery-operations"] --- The manifest on the left is the source of truth. The gate on the right is not diff --git a/content/labs/test-pyramid/lab.mdx b/content/labs/test-pyramid/lab.mdx index 6f32097..1d703d9 100644 --- a/content/labs/test-pyramid/lab.mdx +++ b/content/labs/test-pyramid/lab.mdx @@ -5,6 +5,7 @@ date: "2026-09-18" topic: "quality" preview: "bars" tags: ["testing", "ai"] +themes: ["quality-test-strategy"] --- When code is expensive, the pyramid is wide at the bottom because unit tests diff --git a/content/labs/workflow-stepper/lab.mdx b/content/labs/workflow-stepper/lab.mdx index 29db906..5dcef5c 100644 --- a/content/labs/workflow-stepper/lab.mdx +++ b/content/labs/workflow-stepper/lab.mdx @@ -5,6 +5,7 @@ date: "2026-09-17" topic: "orchestration" preview: "process" tags: ["camunda", "orchestration", "order management"] +themes: ["workflow-orchestration"] --- A submitted quote doesn't become one big transaction. It is decomposed into diff --git a/content/work/goldpath.mdx b/content/work/goldpath.mdx new file mode 100644 index 0000000..7f4c5d1 --- /dev/null +++ b/content/work/goldpath.mdx @@ -0,0 +1,69 @@ +--- +title: "A golden path for enterprise .NET, not another framework" +summary: "Goldpath: composable packages, templates and checks that give .NET teams the plumbing every enterprise system needs, with one manifest as the source of truth." +sector: "Developer tools" +role: "Author" +themes: ["architecture-integration", "quality-test-strategy"] +kind: "open-source" +aiNative: true +period: "2026 — now" +date: "2026-07-12" +stack: [".NET 10", ".NET Aspire", "PostgreSQL", "Quartz", "Stryker", "OpenAPI", "AsyncAPI"] +outcomes: + - { value: "23", label: "packages", countTo: 23 } + - { value: "13", label: "architecture decisions", countTo: 13 } + - { value: "1100+", label: "tests", countTo: 1100 } +--- + +## Context + +Every enterprise .NET team builds the same things again: idempotency, locking, +an audit trail, background jobs, messaging, bulk processing. Each version has +its own bugs. And the spec, the contracts and the code drift apart the moment +the first deadline arrives. + +Goldpath is a paved road for that. It is not a framework: it configures +Microsoft's own building blocks instead of wrapping them, so a team can leave +the road at any point. + +[GitHub](https://github.com/qorpe/goldpath) + + + + + + + + +## The decisions + +- **The manifest is the single source of truth.** Contracts, checks and + generated docs all follow from it. +- **Configure Microsoft, never wrap it.** Less to learn, nothing to unlearn. +- **AI stays in the development layer.** It helps write and change code. The + runtime libraries contain no AI; that is an opt-in module. +- **Standards are executable.** A rule that isn't checked by a tool is a + suggestion. The docs are generated, so they can't go stale. +- **Three approvals no tool can skip.** The spec is approved by the business, + the merge request by a developer, the cut-over by operations. Everything an + agent produces arrives as a merge request. + +## One proof, in detail + +The question every payments architect asks first: what happens when a node dies +in the middle of a batch? A test in CI answers it on every pull request, with +two real executor processes and a real PostgreSQL. + + + +No payment goes out twice. The test proves it; nobody has to believe it. + +## How I built it + +I wrote it with AI, inside the same rules it gives to its users: a manifest +first, deterministic checks, tests that must fail before the change, and +mutation testing to show the tests actually catch mistakes. diff --git a/content/work/mockifyr.mdx b/content/work/mockifyr.mdx new file mode 100644 index 0000000..8be058f --- /dev/null +++ b/content/work/mockifyr.mdx @@ -0,0 +1,73 @@ +--- +title: "A mock server that is done only when it matches the reference" +summary: "Mockifyr, a self-hosted API mocking and integration sandbox in .NET. Every behaviour it copies is checked against a running WireMock before it counts as done." +sector: "Developer tools" +role: "Author" +themes: ["quality-test-strategy", "architecture-integration"] +kind: "open-source" +aiNative: true +period: "2026 — now" +date: "2026-07-01" +stack: [".NET 10", "ASP.NET Core", "Testcontainers", "PostgreSQL", "Redis", "Kafka", "Docker", "Helm"] +outcomes: + - { value: "63", label: "releases", countTo: 63 } + - { value: "1500+", label: "tests", countTo: 1500 } + - { value: "15", label: "architecture decisions", countTo: 15 } +--- + +## Context + +Enterprise systems depend on downstream systems you can't call from a test: +billing, inventory, a partner's API, an SMS gateway. You mock them, and then +you trust the mock. I wanted a mock server in .NET, with its own codebase, that +speaks the protocols these systems actually use and can be handed to a partner +as a sandbox. And I wanted a way to know it behaves correctly, not a feeling +that it does. + +[mockifyr.qorpe.com](https://mockifyr.qorpe.com) · +[GitHub](https://github.com/qorpe/mockifyr) + + + +## How "done" is decided + +A feature that copies WireMock's behaviour isn't done when it looks right. It +is done when the same requests produce the same responses in both. + + + +Where no reference exists, a real client drives the feature instead: a real +mail client for SMTP, the official Twilio SDK for SMS, a real gRPC client for +gRPC. + +## The decisions + +- **The core does no I/O.** Delay, fault and proxy are directives the core + returns; calls to the outside world happen at the edges. That is what makes + the differential check possible. +- **Tenants are in the model from day one.** One process serves many teams or + partners, each with its own stubs, keys and quotas. Adding this later would + have meant rewriting the engine. +- **Memory first, storage optional.** Requests are always served from memory. + PostgreSQL, Redis or LiteDB are written through when data has to survive a + restart or be shared between replicas. +- **Every decision is written down.** Fifteen decision records and a parity + document for each area of behaviour, including what is deliberately left out. + +## How I built it + +I wrote it with AI. The AI never judged its own work: the architecture rule is +that only the running reference decides whether a behaviour is correct. + +## Outcome + +Sixty-three releases, one container image for amd64 and arm64, a Helm chart +that runs on OpenShift, and more than 1,500 tests. diff --git a/content/writings/from-intent-to-proof.mdx b/content/writings/from-intent-to-proof.mdx index 526155a..6cc2fdb 100644 --- a/content/writings/from-intent-to-proof.mdx +++ b/content/writings/from-intent-to-proof.mdx @@ -6,6 +6,7 @@ lang: "en" tags: ["manifesto", "spec-driven", "quality", "ai"] featured: true draft: true +themes: ["delivery-operations", "quality-test-strategy"] --- > Draft. The structure is final; the words are not. diff --git a/content/writings/mockifyr-neden.mdx b/content/writings/mockifyr-neden.mdx deleted file mode 100644 index e3cff61..0000000 --- a/content/writings/mockifyr-neden.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "Mockifyr'ı neden yazdım" -description: "Bağımsız, .NET tabanlı bir API mock motoru kurmanın ardındaki düşünce." -date: "2026-07-05" -lang: "tr" -tags: ["mockifyr", ".net", "mühendislik"] ---- - -API'leri taklit etmek (mock'lamak) yeni bir fikir değil. Ama ihtiyacım olan şey -şuydu: **tamamen bağımsız**, saf bir çekirdek motor — taşımadan (transport) -soyutlanmış, dış bağımlılığı olmayan, ve doğruluğu tahminle değil **kanıtla** -ispatlanan bir sistem. - -## Temel ilke - -Çekirdek saf kalır: I/O yapmaz, bir HTTP handler'a asla dokunmaz. Delay, fault, -proxy birer **direktiftir** — dış çağrılar `IServeEventListener` üzerinden akar. - -```csharp -public sealed record StubMatch( - ResponseDefinition Response, - IReadOnlyList Directives); -``` - -## "Bitti" ne demek? - -Bir davranış, gerçek referansa karşı **diferansiyel** olarak doğrulanana kadar -bitmiş sayılmaz. "Çalışıyor gibi görünüyor" bir kanıt değildir. Oracle çalışır, -diff yeşile döner — işte o zaman bitmiştir. - -Bu blog, o yolculukta öğrendiklerimi Türkçe olarak buraya not ettiğim yer. -Mockifyr'ın kendisine [mockifyr.qorpe.com](https://mockifyr.qorpe.com) adresinden -ulaşabilirsin. diff --git a/content/writings/why-i-wrote-mockifyr.mdx b/content/writings/why-i-wrote-mockifyr.mdx new file mode 100644 index 0000000..38bbb3f --- /dev/null +++ b/content/writings/why-i-wrote-mockifyr.mdx @@ -0,0 +1,74 @@ +--- +title: "Why I wrote Mockifyr: done means a green diff" +description: "A mock server is only useful if it behaves like the thing it copies. So I stopped asking whether it looked right and started comparing it with the real one." +date: "2026-09-30" +lang: "en" +tags: ["testing", "mocking", ".net"] +series: "Test strategy that holds" +seriesOrder: 1 +featured: true +themes: ["quality-test-strategy"] +--- + +Every integration test that uses a mock makes a quiet assumption: the mock +behaves like the real thing. When it doesn't, the test passes and production +fails, and nobody finds out until a customer does. + +I wrote [Mockifyr](https://mockifyr.qorpe.com) because I needed a mock server +in .NET, with its own codebase, that I could hand to a team or a partner as a +sandbox. It copies the behaviour of WireMock, the most widely used mock server. +The hard part wasn't writing it. The hard part was knowing it was right. + +## Looking right is not a test + +The usual way to build something like this is to read the reference +documentation, write the feature, write a few tests for the cases you thought +of, and move on. Every step of that depends on your own understanding. If you +misread how the reference handles an empty array or a missing header, your code +and your tests will agree with each other, and both will be wrong. + +It gets worse when code is cheap to write. With AI, I could produce a feature +and its tests in minutes. Tests written by the same hand, human or not, from the +same understanding, prove very little. + +## Ask the real one + +So the rule became: the only thing that decides whether Mockifyr is correct is a +running WireMock. + + + +That changes what "done" means. It isn't "I believe it works" or "the tests I +wrote pass". It is "the reference and my code give the same answers to inputs +I didn't choose". + +## What the loop needs from the design + +You can only compare two systems if you can drive one of them precisely. That +shaped Mockifyr's core from the first commit: it does no I/O. Delays, faults and +proxying are instructions the core returns, not things it does. Calls to the +outside world happen at the edges. A pure core is easy to put side by side with +anything. + +## Where the loop stops + +A byte diff only catches what it can compare. Timing, socket-level faults, TLS +handshakes and concurrency don't show up in it, so they are tested separately. +Some features have no WireMock equivalent at all, such as SMTP, SMS or gRPC. +For those, a real client drives the feature instead: a real mail client, the +official Twilio SDK, a real gRPC client. When there is no oracle, the next best +thing is the software people actually use. + +## The general point + +This isn't about mock servers. Whenever you rebuild something that already +exists, whether it's a legacy system, a library or a service, you already have +the best test you'll ever get: the old one. Run both, compare the answers, and +let the difference tell you when you are done. + +With AI writing more of the code, this matters more, not less. The model can +write the feature. It shouldn't be the one who decides it works. diff --git a/src/app/work/[slug]/page.tsx b/src/app/work/[slug]/page.tsx index 8739fbd..d912d81 100644 --- a/src/app/work/[slug]/page.tsx +++ b/src/app/work/[slug]/page.tsx @@ -13,6 +13,8 @@ import { Toc } from "@/components/writings/toc"; import { renderMdx } from "@/lib/mdx"; import { extractHeadings } from "@/lib/writings"; import { getLabsBySlugs } from "@/lib/labs"; +import { getAllWritings } from "@/lib/writings"; +import { PostRow } from "@/components/writings/post-row"; import { getProgrammeParts, getWorkBySlug, getWorkSlugs } from "@/lib/work"; import { pageMetadata } from "@/lib/seo"; @@ -54,6 +56,9 @@ export default async function WorkStudyPage({ work.programme ? getWorkBySlug(work.programme) : null, ]); const themes = work.themes.map(getTheme).filter((x) => x !== undefined); + const writings = (await getAllWritings()).filter((w) => + (w.themes ?? []).some((t) => work.themes.includes(t)), + ); const headings = extractHeadings(work.content); return ( @@ -164,6 +169,17 @@ export default async function WorkStudyPage({ )} + {writings.length > 0 && ( +
+

{t("relatedWriting")}

+
+ {writings.map((post) => ( + + ))} +
+
+ )} + {labs.length > 0 && (

{t("tryIt")}

diff --git a/src/app/writings/[slug]/page.tsx b/src/app/writings/[slug]/page.tsx index 60a7b34..f03b81a 100644 --- a/src/app/writings/[slug]/page.tsx +++ b/src/app/writings/[slug]/page.tsx @@ -20,6 +20,8 @@ import { type WritingMeta, } from "@/lib/writings"; import { articleJsonLd, articleMetadata } from "@/lib/seo"; +import { getWorkInThemes } from "@/lib/work"; +import { WorkCard } from "@/components/work/work-card"; /** A table of contents earns its space from three sections up. */ const TOC_MIN_HEADINGS = 3; @@ -56,9 +58,10 @@ export default async function WritingPage({ day: "numeric", }).format(new Date(post.date)); - const [seriesPosts, adjacent] = await Promise.all([ + const [seriesPosts, adjacent, practice] = await Promise.all([ post.series ? getSeriesPosts(post.series) : Promise.resolve([]), getAdjacentWritings(slug), + getWorkInThemes(post.themes ?? []), ]); const headings = extractHeadings(post.content); const showToc = headings.length >= TOC_MIN_HEADINGS; @@ -164,6 +167,17 @@ export default async function WritingPage({ {content} + {practice.length > 0 && ( +
+

{t("inPractice")}

+
+ {practice.map((item) => ( + + ))} +
+
+ )} + diff --git a/src/i18n/messages/en.json b/src/i18n/messages/en.json index ca86399..dde1363 100644 --- a/src/i18n/messages/en.json +++ b/src/i18n/messages/en.json @@ -68,8 +68,8 @@ { "title": "Quality & test strategy", "desc": "Tests strong enough to decide what reaches production.", - "href": "/labs/test-pyramid", - "proof": "test pyramid" + "href": "/work/mockifyr", + "proof": "green diff" }, { "title": "Delivery & operations", @@ -110,7 +110,8 @@ "themes": "Practice areas", "partOf": "Part of", "parts": "The parts", - "featured": "Featured work" + "featured": "Featured work", + "relatedWriting": "Writing in this area" }, "labs": { "title": "Labs", @@ -139,7 +140,8 @@ "older": "Older", "copy": "Copy code", "copied": "Copied", - "writtenBy": "Written by" + "writtenBy": "Written by", + "inPractice": "In practice" }, "openSource": { "title": "Open source", diff --git a/src/lib/labs.ts b/src/lib/labs.ts index d949315..29e15de 100644 --- a/src/lib/labs.ts +++ b/src/lib/labs.ts @@ -6,6 +6,7 @@ import { newestFirst, readMdx, } from "./content"; +import type { ThemeSlug } from "@/config/themes"; export const LABS_DIR = path.join(CONTENT_DIR, "labs"); @@ -14,6 +15,7 @@ export const LABS_DIR = path.join(CONTENT_DIR, "labs"); * the folder is all it takes — `npm run gen` (run before dev and build) * registers the demo so the Labs page, the home page and * in any essay can find it. */ + export interface LabFrontmatter { title: string; /** One sentence: what you can try. */ @@ -26,6 +28,8 @@ export interface LabFrontmatter { preview?: "flow" | "bars" | "process" | "gate"; /** The essay that explains it, by slug. */ writing?: string; + /** Practice areas (see src/config/themes.ts). */ + themes?: ThemeSlug[]; draft?: boolean; } @@ -49,6 +53,7 @@ async function readAll(): Promise { const lab: Lab = { ...parsed.data, tags: parsed.data.tags ?? [], + themes: parsed.data.themes ?? [], draft: parsed.data.draft ?? false, slug, content: parsed.content, diff --git a/src/lib/work.test.ts b/src/lib/work.test.ts index 8bb3f18..b0e5c9a 100644 --- a/src/lib/work.test.ts +++ b/src/lib/work.test.ts @@ -3,6 +3,7 @@ import { getAllWork } from "./work"; import { getAllLabs } from "./labs"; import { THEME_SLUGS } from "@/config/themes"; import { WORK_KINDS } from "./work"; +import { getAllWritings } from "./writings"; describe("work", () => { it("every case study has the card fields and only known labs", async () => { @@ -44,4 +45,15 @@ describe("work", () => { } } }); + + it("uses only known themes on writing and labs", async () => { + const [writings, labs] = await Promise.all([ + getAllWritings(), + getAllLabs(), + ]); + for (const item of [...writings, ...labs]) { + for (const t of item.themes ?? []) + expect(THEME_SLUGS, item.slug).toContain(t); + } + }); }); diff --git a/src/lib/work.ts b/src/lib/work.ts index bc1eac9..fb0b716 100644 --- a/src/lib/work.ts +++ b/src/lib/work.ts @@ -105,6 +105,21 @@ export async function getProgrammeParts(slug: string): Promise { .sort((a, b) => a.date.localeCompare(b.date)); } +/** Case studies that share a practice area with `themes`: those whose main + * theme matches first, then featured ones, then the newest. */ +export async function getWorkInThemes( + themes: readonly string[], + limit = 2, +): Promise { + if (themes.length === 0) return []; + const score = (w: WorkMeta) => + (themes.includes(w.themes[0]) ? 2 : 0) + (w.featured ? 1 : 0); + return (await getAllWork()) + .filter((w) => w.themes.some((t) => themes.includes(t))) + .sort((a, b) => score(b) - score(a)) + .slice(0, limit); +} + export async function getWorkSlugs(): Promise { return (await getAllWork()).map((w) => w.slug); } diff --git a/src/lib/writings.ts b/src/lib/writings.ts index d3f70e0..cd035f0 100644 --- a/src/lib/writings.ts +++ b/src/lib/writings.ts @@ -4,6 +4,7 @@ import GithubSlugger from "github-slugger"; import matter from "gray-matter"; import readingTime from "reading-time"; import { tagSlug } from "./slug"; +import type { ThemeSlug } from "@/config/themes"; export { tagSlug }; @@ -26,6 +27,9 @@ export interface WritingFrontmatter { featured?: boolean; /** Date of the last meaningful revision (ISO), if revised after `date`. */ updated?: string; + /** Practice areas (see src/config/themes.ts); links the piece to case + * studies in the same area. */ + themes?: ThemeSlug[]; } export interface WritingMeta extends WritingFrontmatter { @@ -61,6 +65,7 @@ function parse(fileName: string, raw: string): Writing { seriesOrder: fm.seriesOrder, featured: fm.featured ?? false, updated: fm.updated, + themes: fm.themes ?? [], readingMinutes: Math.max(1, Math.round(readingTime(content).minutes)), content, };