This is the most common failure mode in AI-assisted development, and it is not really a bug. It is the natural consequence of how these tools are built and how we prompt them. Worth understanding, because once you know why it happens you can prompt around it fairly reliably.

Over-building costs you in three separate currencies, and it is worth separating them up front, because the fixes differ:

1. Code you have to maintain — the extra abstractions, files and options that outlive the task.
2. Tokens — the context, time and money burned producing and re-reading work nobody asked for.
3. Code you have lost — the lines an agent quietly removed on its way to the change you did want, which is the one that bites hardest because it is invisible in the output and only shows up in the diff.

The prompts in this post are written to be copied and adapted. Most of them are short.

Why AI tools over-build

A few forces push in the same direction.

They are trained on published code. The material these models learned from is skewed towards libraries, frameworks, tutorials and well-regarded open source — code written to be reused by strangers, extended in unknown directions, and demonstrated in blog posts. That code is correctly full of interfaces, options and extension points. Your internal service handling one known case is not that code, but it looks superficially similar, so the same patterns come out.

Helpfulness reads as thoroughness. A model optimised to be useful will tend to cover the cases you did not mention. You asked for a CSV parser; it handles quoted fields, BOM markers, custom delimiters and a streaming mode, because each of those is plausibly helpful. Each addition is defensible on its own. The sum is a small library you now own.

They cannot feel the cost. A human developer who adds an abstraction pays for it later — in review, in debugging, in the next person’s onboarding. The model has no stake in the file six months from now. There is no friction pushing back against another layer.

The prompt is usually underspecified. “Add caching to this” does not say where the boundary is. The model fills the gap with assumptions, and its default assumption is generality: make it configurable, make it swappable, make it work for cases you did not mention.

Context is partial. The tool often cannot see that you already have a retry helper in utils/http.py, or that the project has a house convention for configuration. So it builds its own. Duplication is a form of bloat too, and it is the kind that tends to survive review, because the new code looks fine in isolation.

flowchart TD
    A["Vague request"] --> B["Model fills gaps with assumptions"]
    B --> C["Default assumption: make it general"]
    C --> D["Extra abstractions, options, files"]
    D --> E["Code that passes review in isolation"]
    E --> F["Maintenance cost paid later by humans"]
    A2["Scoped request with stated constraints"] --> B2["Few gaps to fill"]
    B2 --> G["Minimal change to existing structure"]

The key point of the diagram: over-engineering is not the model being wrong, it is the model resolving ambiguity in the direction of generality. Remove the ambiguity and most of it disappears.

The practical guide

1. State the scope in files, not in adjectives

“Keep it simple” is nearly useless as an instruction — simplicity is subjective and the model already believes its output is simple. A file budget is not subjective.

Add retry-on-timeout to the fetchInvoice call in services/billing.ts.
Change that one file only. No new files, no new classes.
If you think this needs more than one file, stop and tell me why
instead of writing it.

If the change genuinely needs a new file, the model will say so, and now you are having a useful conversation about scope instead of reviewing code you did not want.

2. Name the one case you are solving, and the ones you are not

Over-building thrives on unstated cases. Close them explicitly.

We only ever read UTF-8 CSVs written by our own exporter, always with
the same six columns. Do not handle other encodings, custom delimiters,
missing columns, or malformed rows beyond raising an error.

This single instruction prevents more bloat than any amount of “be concise”. A useful variant when you genuinely do not know the case list yet:

Before writing anything, list the edge cases you are planning to handle
and wait. I will tell you which ones are real.

3. Keep tasks small and incremental

This is the rule that makes all the others easier to follow, and the one most often broken, because handing over a big task feels like the whole point of having an assistant.

Two prompts beat one. First: make it work for the exact case, in the existing structure. Then, once you have seen the diff, decide whether it needs generalising. The model is good at both jobs; it is just bad at guessing which one you wanted.

Step 1 only: make this work for the single case I described, in the
existing structure, with the fewest lines you can. Do not generalise,
do not add options. Once I have reviewed it I will tell you whether
step 2 is needed.

The inversion matters. Generalising working code you have read is cheap. Reviewing a speculative framework to find the 10 lines that do the work is expensive — in review time and in tokens, since every follow-up re-reads the whole thing.

Size the increment so that you can still meaningfully review it. A good working limit is a change you would be happy to review as a pull request from a colleague: one behaviour, a diff you can hold in your head, a clear answer to “did this do what I asked?” Past that point, review quality collapses — you start skimming, and skimming is exactly how both bloat and silent deletions get merged.

Small increments also fail cheaply. If the model misunderstands the task, you find out after one reviewable change, not after eleven files that all assume the same wrong thing. And because each increment lands in a clean tree, every diff is attributable.

We are doing this in steps, not all at once. Step one is only:
add the endpoint and return a hard-coded response. Do not touch the
database layer, auth, or tests yet — I will ask for those separately.
Stop when step one works.

The exception, with a caveat. A larger task is reasonable when there is a genuine specification behind it: written requirements, defined acceptance criteria, named files or interfaces, and an explicit statement of what is out of scope. That is exactly what closes the ambiguity gap the model would otherwise fill with invention, and it is why teams with real task documents get better results from agentic tools than teams working from one-line tickets.

But a specification is not a substitute for checking. It changes what you check for, not whether you check. With a spec, the failure mode is rarely “the model did the wrong thing” — it is the model satisfying every stated criterion while adding structure nobody specified, or quietly dropping an existing behaviour the spec did not mention because the spec described the feature, not the code around it. Nothing in a document prevents that; only the diff shows it.

So even with a good spec, work through it in stages and review at each boundary:

Here is the specification. Work through it in stages and stop after
each one for review. Do not implement anything the spec does not
call for, and if the spec is ambiguous or silent on something, ask
rather than deciding for me. List anything you had to assume.

The last sentence is the valuable one. Assumptions the model announces are cheap to correct; assumptions it bakes into code are not.

4. Point at the code it should imitate

Most bloat is the model inventing structure because it does not know yours.

Follow the pattern in handlers/orders.py exactly. Use the existing
get_config() helper rather than adding configuration. If something in
that pattern does not fit, say so rather than inventing a new one.

This also fixes the duplication problem: told where to look, the model reuses instead of rebuilding.

5. Ban speculative generality by name

The specific phrases work better than a general plea for restraint, because they map to recognisable patterns:

• No new interfaces or abstract base classes unless there are two real implementations today.
• No configuration options for values that have exactly one value in this codebase.
• No new dependencies without asking first.
• No backwards-compatibility shims — nothing is calling this yet.

Put these in a project instructions file (CLAUDE.md, .cursorrules, or whatever your tool reads) so you are not retyping them. That is the single highest-leverage habit here: the rules apply to every prompt without costing you anything per prompt.

6. Be explicit about tests, both ways

Left alone, assistants either write no tests or write twenty, including tests for the abstractions they just invented. Say which you want:

Add exactly one test, for the timeout path, to the existing test file.
Do not restructure that file, do not add fixtures, and do not test
anything that already had coverage.

7. Review the diff for structure, not just correctness

When you read the output, the question is not only “does this work?” but “is anything here that I did not ask for, and is anything missing that used to be there?” New files, new abstractions, new configuration — and removed lines. Each is a place where the model made a scope decision on your behalf. This matters enough that it gets its own section below.

Deleting the extra work is fast when you spot it in review. It is very slow once it has been merged, imported elsewhere, and become load-bearing.

8. Reset the conversation when scope drifts

Long sessions accumulate context, and accumulated context tends to grow the perceived scope of the task — as well as the cost of every subsequent message, since the whole history is re-read each turn. If the fourth follow-up in a thread is producing more machinery than the first, start a fresh conversation with a tight restatement of the remaining work. It is cheaper than steering a drifting one, in both senses of cheaper.

9. Ask for the plan before the edits

For anything beyond a small change, make the first response a plan rather than code. A plan is a few hundred tokens and takes twenty seconds to read; the implementation it would have written is thousands of tokens and takes ten minutes to review.

Do not write any code yet. In under 15 lines, tell me:
which files you will change, roughly how many lines in each,
any new files or dependencies, and anything you are unsure about.
Then stop and wait.

This is the cheapest possible point to catch “I was going to add a strategy pattern here”. It also gives you a scope you can hold the model to afterwards: “That plan said two files. You changed five. Explain the other three.”

Watch the token burn

Over-engineering has a twin that gets much less attention: the tokens spent getting there. Every file the tool reads, every file it re-reads, every unchanged line it echoes back, every dead end it explores — all of it is context consumed, and on metered plans, money. On agentic tools it compounds, because the agent is reading and writing on its own initiative between your messages.

The pattern to watch for is a straightforward task that quietly costs several times what it should. A one-line config change that ends with forty files read. A small feature that runs the full test suite four times. A refactor where the assistant reads a 2,000-line file three separate times because it forgot it had already seen it.

Some of that burn is the tool’s doing, but most of it is caused by the same thing that causes bloat: an unbounded request. “Fix the failing test” invites a hunt. “Fix the failing test in test_billing.py::test_refund — the cause is in refund() in billing.py, do not read anything else unless you need to” does not.

Where the tokens actually go

• Broad search instead of targeted search. Reading whole files to absorb conventions, when a few grep matches would show them.
• Re-reading. Files read once, then read again later in the same session.
• Echoing unchanged content. Some editing styles reproduce an entire file to change one line. On a large file that is the whole file, every time.
• Over-wide verification. Running the complete test suite to confirm a change that touches one module.
• Exploratory sprawl. A search that keeps widening because nothing told it when to stop.
• Long sessions. Accumulated history is re-sent with every turn, so a drifting thread gets more expensive per message as it goes.

Prompts that cap the burn

Put this in your project instructions file so it applies to every task:

Minimise token use. Prefer targeted grep and narrow file reads over
reading whole files. Do not re-read a file you have already read in
this session. Do not read a large file end to end to learn conventions
when a few matches would show them. Run only the tests that cover the
change, not the whole suite. If usage looks unexpectedly high for the
size of the task, stop and tell me before continuing.

Give large tasks an explicit heads-up rule, so you find out about cost before it is spent rather than after:

Before starting anything that touches more than a few files, tell me in
one or two lines: roughly how many files, whether it needs new packages,
migrations or tests, and whether it should be split. Then start — this
is a heads-up, not a request for permission.

And scope individual investigations rather than opening them up:

The bug is somewhere in the checkout flow. Start with
services/checkout.py and the two functions it calls in cart.py.
Read only those. If the cause is not there, tell me what you would
look at next instead of going and looking.

When a session is already expensive, the right move is usually not to keep steering it. Summarise and restart:

Summarise in 10 lines: what we changed, what is left, and the
constraints I gave you. I am going to start a fresh session from that
summary.

One last habit, cheap and surprisingly effective: if the pace or the cost looks wrong, say so mid-task. “That seems like a lot of reading for a one-line change — what are you looking for?” A tool that has to justify its search usually narrows it.

Read the diff twice: before and after

The most damaging thing an AI agent does to a codebase is not adding code. It is removing code you did not ask it to remove.

This happens more than people expect, and the mechanism is mundane. When a model rewrites a function or a file, it reproduces it from its own understanding rather than surgically patching it. Anything it did not consider important — or did not have in context — can simply fail to reappear. What gets lost is predictable and, in each case, quiet:

• An early-return guard for a null case that only occurs in production.
• A try/except around a call that fails once a month.
• A comment explaining why a line that looks wrong is actually correct.
• A feature flag check, or a permissions check, sitting in the middle of a function being “cleaned up”.
• Logging or metrics calls, removed as noise.
• A workaround for a third-party bug, with no obvious reason for existing.

None of these break a test suite reliably. Several of them are precisely the code that exists because of a past incident. And because the model’s summary of its work says “refactored processPayment for clarity”, the deletion never appears in the conversation at all. It exists only in the diff.

The practice

Start every task from a clean tree. Commit or stash first. If the working tree already has changes in it, you cannot tell the agent’s edits from your own, and the diff — your only real record — becomes useless.

Read the diff, not the summary. The model’s description of its change is a description of what it intended. The diff is what happened. Review the diff before you run anything, and treat removed lines as first-class findings rather than noise around the addition.

Read removals specifically. Additions get scrutiny naturally because they are new and interesting. Deletions are easy to skim past, especially in a large diff. Look at them on purpose:

# Only the removed lines, across the whole change
git diff -U0 | grep '^-' | grep -v '^---'

Ask for the deletions to be declared. You can make the agent surface them itself, which turns an invisible change into a reviewable statement:

After making the change, list every line you deleted or replaced that
was not part of what I asked for, and why it went. If the answer is
"nothing", say that explicitly.

Forbid unrequested removal outright for narrow fixes:

This is a surgical fix. Do not delete or rewrite any existing line that
is not directly required by the change — including comments, logging,
error handling, and guard clauses. If something looks dead or wrong,
tell me about it, do not remove it.

Prefer patches over rewrites. The prompt-level version of this is simply saying so:

Edit the existing function in place with the smallest possible change.
Do not rewrite it from scratch and do not reformat the surrounding code.

Diff the before and after of the file itself when the change is large enough that a rewrite was likely:

git stash                      # or: git switch -c ai-change
git diff --stat HEAD           # scope of change, file by file
git diff HEAD -- path/to/file  # then read the ones that grew or shrank unexpectedly

A file that shrank during a task that was supposed to add something is the single most reliable signal that scope was silently traded away. It takes one line of output to spot and can save you an incident.

flowchart LR
    A["Clean tree"] --> B["Scoped prompt"]
    B --> C["Agent makes change"]
    C --> D["git diff --stat"]
    D --> E{"Anything shrink<br/>unexpectedly?"}
    E -->|"Yes"| F["Read removed lines<br/>ask why they went"]
    E -->|"No"| G["Review additions<br/>for scope creep"]
    F --> H["Restore what mattered"]
    G --> H

The point of that loop is that both halves of the review matter. Scope creep is what the agent added; silent deletion is what it took away. A review that only asks “is this code good?” catches the first and misses the second.

The cycle this fits into

None of this works as a set of isolated prompting tricks. It works when the prompting sits inside a loop that assumes the AI’s output needs checking, and gives you defined places to do the checking.

The diagram shows that loop as nine steps, each with a named owner, plus two feedback paths.

It starts with a specification, not a prompt. Step 1 is the task document: requirements and objectives, the work broken into tasks with acceptance criteria, references to the sources of truth (project bible, architecture, standards, policies), and an explicit statement of scope and constraints. That is the same content as a well-scoped prompt, just written down once and reusable — and it is where the ambiguity that causes over-building gets removed, before any code exists.

The build step is explicitly incremental. Step 2 is implementation with AI assistance, and its own guidance is to follow the coding standards and keep changes focused and incremental. The AI is a tool inside the step, not the owner of it; the developer still owns the step.

Three different checks follow, and they are not the same check. Step 3 is review for quality, logic, security and maintainability — by a peer, an AI, or both. Step 4 is testing against the acceptance criteria, including edge cases and error scenarios. Step 6 is verification against the sources of truth: does this align with the existing codebase, the project bible, and organisational policy — and, stated directly on the diagram, were any unintended deviations introduced by the AI? That last question is the one this post has been circling. It is a distinct check, and it belongs in the process rather than in someone’s good intentions.

The Git review step is about diffs, not just code. Step 9 asks the reviewer to compare diffs to see exactly what changed — noted on the diagram as especially important with AI-generated code — and to look for unexpected or unnecessary changes. Unexpected covers the silent deletion; unnecessary covers the over-engineering. Same review, both failure modes.

The two loops are the point. The top path sends anything incomplete or broken back through the cycle. The bottom path, from a rejected change review, returns all the way to step 1 — feedback, changed requirements or new requirements become a revised specification rather than another improvised prompt on top of a drifting session. That is the structural version of “reset the conversation when scope drifts”.

If the diagram cannot render for you, the summary is: specify, build small with AI help, review, test, fix, verify against your standards, document, commit, review the diff, then merge or loop back — with a human owning every step and the AI assisting inside them.

Worth being honest about the cost of this: it is more ceremony than “ask the assistant and merge what comes out”. The pay-off is that each step is small enough to actually perform. A nine-step cycle around a two-day change is bureaucracy. The same cycle around a one-behaviour increment is about twenty minutes, most of which you would have spent anyway.

Scenarios

A configuration value becomes a configuration system

Ask: “Make the request timeout configurable.”

What tends to come back: A Config class, environment-variable loading with type coercion, a defaults file, validation, and timeout wired through three layers of constructor injection.

What was needed: A module constant, or one environment variable read at the call site.

Prevention: Name the mechanism, not the goal. “Read the timeout from an environment variable at the call site in client.py, defaulting to 30 seconds. Do not add a configuration class or file.” Rule 1 and rule 5 do the work here.

One-off script becomes a CLI application

Ask: “Write a script to rename these files.”

What tends to come back: Argument parsing, --dry-run, --verbose, --recursive, logging configuration, a main() guard, progress output, and a docstring describing usage.

What was needed: Fifteen lines you run once and delete.

Prevention: State the lifespan. “This is a throwaway script I will run once on this directory and then delete. No arguments, no flags, no logging — hard-code the path.” Telling the model the code is disposable is remarkably effective, because it removes every justification for extensibility.

A bug fix becomes a refactor

Ask: “Fix the off-by-one in the pagination.”

What tends to come back: The fix, plus the surrounding function extracted into three smaller ones, renamed variables, added type hints, and a docstring — a 4-line fix inside a 60-line diff.

What was needed: The 4 lines. The tidying may even be good, but it is now impossible to review the fix in isolation, and if the page breaks tomorrow you cannot tell which part did it.

Prevention: Separate the jobs explicitly. “Change only the lines required to fix the off-by-one. Do not rename, reformat, or extract anything. If you see other issues, list them at the end instead of fixing them.” The “list them instead” clause is worth keeping — you get the model’s observations without the unrequested diff, and you can accept them as a separate change.

A CRUD endpoint arrives with a service layer

Ask: “Add an endpoint to fetch a user by ID.”

What tends to come back: A repository interface, a service class, a DTO, a mapper between the DTO and the model, a custom exception hierarchy, and the endpoint.

What was needed: A handler that queries and returns, matching the five endpoints already in the file.

Prevention: This is rule 4 almost exclusively. “Add it to routes/users.py following the exact pattern of the existing get_order endpoint. No new files.” When an existing pattern is named, the model copies rather than architects.

A parser grows a plugin system

Ask: “Parse this log format.”

What tends to come back: A format-detection layer, a registry of parser strategies, and an extension point for adding formats later — because logs come in many formats, and the model does not know that yours does not.

What was needed: One regex and a loop.

Prevention: Close the case list, as in rule 2. “There is exactly one log format and it will not change. Parse it directly — no strategy pattern, no format detection.”

A shared helper gets duplicated

Ask: “Add date formatting to this report.”

What tends to come back: A new formatDate function in the report module — while utils/dates.ts already exports one.

What was needed: An import.

Prevention: Make searching part of the instruction, and make the result visible:

Before writing any helper, grep utils/ for an existing one and tell me
what you found. If something close already exists, use it or extend it
rather than adding a second version.

This one is worth putting in your project rules permanently, since it applies to every task and the model cannot be expected to have your whole tree in context.

A “cleanup” quietly removes error handling

Ask: “Tidy up processPayment, it has got messy.”

What tends to come back: A shorter, more readable function — minus the try/except around the gateway call, minus the idempotency-key check, and minus a comment reading // do not remove: gateway double-charges on retry. Tests pass, because nothing tests a gateway that fails twice.

What was needed: The same function, tidier, with every guard intact.

Prevention: Two layers. First, constrain the edit:

Improve readability only. Do not remove or alter any error handling,
retry logic, idempotency check, comment, or log line. Behaviour must be
identical.

Second, verify rather than trust:

Show me a list of every line you removed, with the reason for each.

Then read the diff yourself anyway. This is the scenario that justifies the whole diff habit — the output looks better and is worse, and the only place the truth is recorded is in the removed lines.

A one-line change costs a hundred thousand tokens

Ask: “The date on the invoice PDF is in the wrong format.”

What tends to come back: The fix — after the agent has read the PDF renderer, the template system, three model files, the test suite, the configuration loader, and the changelog, run the full test suite twice, and explored a theory about timezones that turned out to be unrelated.

What was needed: One grep for the format string, and one edit.

Prevention: Point at the target and cap the search before it starts:

The invoice date format is wrong. Grep for the format string in
templates/ first. Change only where it is defined. Do not read the
renderer or the test suite unless the grep comes back empty, and run
only the invoice tests.

The general form is worth internalising: when you already know roughly where the problem lives, saying so is not spoon-feeding, it is the single biggest cost control you have.

A prompt block worth keeping

Most of the constraints above are not per-task decisions — they are how you want the tool to behave always. Written once into a project instructions file (CLAUDE.md, .cursorrules, a system prompt, whatever your tool reads), they cost nothing per prompt and apply to work you are not watching closely:

## Scope
- Do the task asked, and nothing adjacent. If you see other problems,
  list them at the end instead of fixing them.
- No new files unless I asked for one, or you tell me first and I agree.
- No new interfaces or abstract classes unless there are two real
  implementations today.
- No configuration options for values that have exactly one value in
  this codebase.
- No new dependencies without asking first.
- Reuse what exists: search before writing a helper, and follow the
  nearest existing pattern rather than inventing one.

## Edits
- Make the smallest change that works. Edit in place; do not rewrite
  files or functions wholesale.
- Never remove existing error handling, guards, comments, logging or
  tests that are not part of the change. Flag them instead.
- After each change, list anything you deleted that I did not ask you
  to delete.

## Cost
- Prefer targeted grep and narrow reads over reading whole files.
- Do not re-read files you have already read this session.
- Run only the tests covering the change.
- Before anything touching more than a few files, give me a one-line
  heads-up on size and whether it should be split.
- If cost looks high for the size of the task, stop and say so.

Trim it to taste. The value is not in these exact words but in the fact that they are written down somewhere the tool reads every time, instead of being remembered by you in some prompts and forgotten in others.

The pattern underneath

Every one of those preventions is the same move: replace an assumption the model would have to make with a fact you supply. Scope, lifespan, the case list, the pattern to follow, what already exists. The model is not trying to gold-plate your codebase. It is answering a question you asked less precisely than you thought, and generality is the safest-looking answer to an imprecise question.

That reframing is also the reason this is a tractable problem rather than a complaint about the tools. You cannot make a model want less code. You can remove the ambiguity that makes more code look like the right answer — and you only have to write most of those constraints down once.

The same move handles the other two currencies. Unbounded search burns tokens for exactly the reason unbounded scope burns files: nothing said where the edges were. And silent deletion happens because “improve this” gave the model licence to decide what mattered in code it could not see the history of. Say where the edges are, and say what must survive.

Four habits, then, and none of them take long:

• Keep the increment small enough that you will genuinely review it — and when a real specification lets you go bigger, still stop and check at each stage.
• Before sending a prompt, spend ten seconds asking what the model would have to guess — then say it.
• Before starting anything big, ask for the plan and the cost, not the code.
• After every change, read the diff — the removed lines first.

The project provides a Docker-based foundation for monitoring multiple SaaS applications across Linux virtual machines. It combines Prometheus for metrics, Grafana for visualisation, and Uptime Kuma for availability checks, with collectors running alongside each application.

Its purpose is to give a solo developer or a small platform team consistent operational visibility across an application portfolio.

The problem: fragmented visibility

Without a shared monitoring approach, each application tends to develop its own operational habits: a health endpoint here, container logs there, and a server dashboard somewhere else.

That makes basic questions harder to answer:

• Which applications are affected?
• Is the problem in the API, database, queue, container, or host?
• Did performance deteriorate gradually or change suddenly?
• Is a background workflow progressing even though the website still loads?
• Is the application unavailable, or has monitoring lost contact with it?

The stack addresses this by collecting comparable signals from each deployment and storing metrics centrally. Operators can investigate application behaviour alongside the infrastructure supporting it.

Two parts of one ecosystem

The architecture separates the central monitoring environment from the software that produces measurements.

flowchart TB
    subgraph Apps["SaaS application environments"]
        App["Application code and metrics library"]
        Infra["Host, containers, proxy, and data services"]
        Exporters["Infrastructure exporters"]
        Endpoint["Private application metrics endpoint"]
        Public["Public website or API"]

        App --> Endpoint
        Infra --> Exporters
    end

    subgraph Central["Central monitoring VM"]
        Prom["Prometheus"]
        Grafana["Grafana"]
        Kuma["Uptime Kuma"]

        Grafana -->|"Queries stored metrics"| Prom
    end

    Prom -->|"Scrapes over private network"| Endpoint
    Prom -->|"Scrapes over private network"| Exporters
    Kuma -->|"Checks public availability"| Public

The central environment collects, stores, and presents operational data. Application environments expose measurements through a common format.

This is monitoring for SaaS applications under the operator’s control: integrating their backend code and deployment infrastructure, rather than connecting to arbitrary third-party SaaS accounts.

The central environment

Three services form the core:

Grafana is the central metrics dashboard. Uptime Kuma provides a complementary availability view through its own interface. They belong to the same monitoring environment, but the repository does not implement a custom dashboard that merges every signal into one application.

What runs alongside each application

Each application VM runs collectors appropriate to its workload:

Database and cache exporters are optional Compose profiles. A deployment enables the components it actually needs.

Infrastructure collectors and application instrumentation serve different purposes. An exporter can describe a container’s memory usage, but application code must provide context such as how many jobs failed or how long an API operation took.

How status data is collected

The stack combines two perspectives.

Availability checks test whether a configured endpoint responds from the monitoring location. These help answer, “Can this service be reached?” They do not establish that every feature or every user’s network path is working.

Internal metrics describe activity and resource usage inside the deployment. These help explain slowdowns, failures, and capacity pressure.

The metrics pipeline uses a pull model: Prometheus requests measurements from each registered endpoint.

sequenceDiagram
    participant User as User or background task
    participant App as Application
    participant Library as Metrics library
    participant Prom as Prometheus
    participant Dash as Grafana

    User->>App: Perform an operation
    App->>Library: Record count, duration, or outcome
    Note over Library: Keep aggregated measurements locally
    Prom->>App: Request private /metrics endpoint
    App->>Library: Read current measurements
    Library-->>App: Prometheus-format metrics
    App-->>Prom: Return measurements
    Note over Prom: Store samples and evaluate rules
    Dash->>Prom: Query a time range
    Prom-->>Dash: Return time-series results

Although it is natural to describe applications as “sending monitoring data,” they generally return it when Prometheus scrapes them. They do not contact Grafana directly or transmit a separate monitoring event for every request.

Prometheus discovers endpoints through configuration files. Labels associate measurements with applications, hosts, environments, and components, making it possible to query related signals together.

How the libraries inside other projects work

The application integration guides describe using standard Prometheus client libraries, including prom-client for Node.js and prometheus_client for Python.

These libraries run inside the backend application. A small integration layer connects them to HTTP middleware, framework interceptors, workers, or scheduled collectors.

The basic building blocks are:

• Counters: totals that increase, such as completed requests or failed jobs.
• Gauges: current values that rise or fall, such as active requests or waiting jobs.
• Histograms: measurements grouped into buckets, such as request durations, from which latency percentiles can be estimated.

For an API request, instrumentation records the method, a normalised route, the response status, and the elapsed time. A worker can record completed and failed jobs. Queue integration can periodically read queue state and expose the results as gauges.

The library keeps these measurements in a registry and exposes them through a private /metrics endpoint. Prometheus then collects them using the same mechanism it uses for infrastructure exporters.

Labels should describe bounded categories, such as route templates and status codes. Customer identifiers, request bodies, and raw URLs are generally unsuitable metric labels: they can disclose sensitive information and create excessive numbers of time series.

A shared integration pattern

The repository contains application preparation guides and instrumentation examples. It does not contain a separately published, proprietary monitoring SDK.

The reusable element is currently the integration pattern: consistent endpoints, metric names, labels, and instrumentation conventions. Each application implements that contract using its own framework and a standard client library.

Consistency matters because central queries and alert rules depend on the metric names and labels that applications expose. Installing a library alone does not make an application compatible with every dashboard or alert.

What “real-time” means here

This is near-real-time monitoring rather than a continuous stream of individual events.

The current Prometheus configuration scrapes metrics every 15 seconds and evaluates alert rules every 15 seconds. Dashboard refresh settings, query windows, and alert waiting periods introduce additional delay.

Counters can preserve activity between scrapes: a burst of completed requests still contributes to the next collected total. A short-lived gauge spike, however, may occur entirely between samples and go unseen.

Alerts can also require a condition to persist before firing. That helps distinguish a sustained problem from a brief fluctuation.

A failed scrape needs interpretation, too. It means Prometheus could not collect measurements from an endpoint; it does not, by itself, prove that the public application is down. Availability checks provide another piece of evidence.

From measurements to useful diagnosis

The benefit comes from comparing signals.

Consider an illustrative case where a website remains reachable but background processing slows down:

1. Availability checks continue to pass.
2. Application metrics show an increasing number of waiting jobs.
3. Worker completion rates fall.
4. Database metrics show connection pressure.
5. Host and container metrics help establish whether resource exhaustion is also involved.

This narrows the investigation. It does not automatically prove a root cause, but it provides a much stronger starting point than a single green uptime indicator.

The repository includes alert rules covering application availability, latency, server errors, infrastructure pressure, data services, and RabbitMQ queues. Their usefulness depends on the corresponding measurements being available and correctly labelled.

Rule evaluation and notification delivery are separate concerns. The checked-in central stack does not include Alertmanager, so escalation routing and notification configuration remain additional operational work.

Infrastructure and deployment

The deployment model uses a dedicated monitoring VM and a companion Docker Compose stack on each application VM.

Metrics collection is designed to travel over a private overlay network, such as Tailscale or WireGuard. Exporters bind to private interfaces, and application integration guides call for private monitoring endpoints. Public websites remain accessible to users without exposing their internal telemetry.

The central services use persistent Docker volumes. Prometheus defaults to 30 days of metric retention, with that period configurable.

Configuration files define scrape targets, alert rules, and Grafana provisioning. This makes the monitoring setup reviewable and repeatable alongside other infrastructure configuration.

A dedicated monitoring VM also separates monitoring from any one application’s host. It can continue observing other deployments if an application VM fails. The current single-VM central design does not provide high availability for monitoring itself.

What the project provides today

The implemented foundation includes central service definitions, infrastructure exporter configurations, target discovery files, alert rules, Grafana provisioning, and application onboarding guidance.

Some capabilities still require deployment-specific work:

• Dashboards: the provisioning mechanism is present, but the dashboard directory currently describes recommended dashboards rather than shipping a completed dashboard collection.
• Application instrumentation: integration guides explain the required code changes; those changes live in the individual application projects.
• Availability checks: Uptime Kuma must be configured with the endpoints and checks relevant to each application.
• Advanced observability: central log aggregation, distributed tracing, richer alert routing, and SLO reporting are future extensions.

The current project is therefore a metrics and availability foundation, with a defined path toward broader observability.

Key advantages

Consistent visibility across applications. A common collection model reduces the need to learn a different monitoring approach for every product.

Better incident investigation. Application symptoms can be examined alongside queues, databases, containers, and hosts.

Visibility beyond uptime. Latency, error rates, queue growth, and resource pressure can reveal degradation while a service still responds.

Incremental adoption. Teams can start with host and container metrics, then add application instrumentation and dependency-specific collectors.

Control over telemetry. The core metrics pipeline and storage run in infrastructure controlled by the operator, with private collection paths.

A reusable foundation. Standard Prometheus metrics allow different application languages and frameworks to participate in the same monitoring environment.

The practical result is a shared way to understand a growing SaaS ecosystem: whether services respond, how they behave, and where to investigate when their behaviour changes.

Nothing here is exotic. It is the same thing that happens to any useful text that has no owner, no version, and no distribution mechanism. What makes it uncomfortable is that this text is now load-bearing: it shapes what gets flagged in a pull request, what an assistant refuses to answer, and which risks a workflow checks for. We have decades of practice managing that kind of dependency for code. We have almost none for instructions.

What an AI artifact actually is

An AI artifact is a reusable unit of operating knowledge that shapes AI-assisted work. In practice that means prompt templates, system instructions, workflow definitions, review guidelines, test patterns, knowledge articles, code templates, policy packs, and evaluation suites.

The important shift is not the vocabulary. It is treating these things as assets with an owner, a version, a compatibility statement, and a lifecycle — rather than as text that lives wherever it was last pasted.

OAI2 — the Open AI Artifact Interchange Initiative — is an open standard and registry for packaging, validating, sharing, and consuming those artifacts. (The name refers to AI artifact interchange; the project has no affiliation with OpenAI.)

The package and the registry

An OAI2 package is a directory with content plus an oai2.yaml manifest:

artifact/
├── oai2.yaml              # Manifest (required)
├── content/main.md        # Primary content (required)
├── variables.schema.json  # Variable definitions, JSON Schema 2020-12 (optional)
└── tests/cases.yaml       # Test cases (optional)

The manifest is where the file stops being a document and starts being a dependency. From the project’s TypeScript code-review sample:

oai2Version: "0.1"
kind: "PROMPT_TEMPLATE"

artifact:
  id: "org.acme.code-review.typescript"
  version: "1.2.0"
  title: "TypeScript Code Review Prompt"

ownership:
  maintainers: ["platform-governance@acme.example"]
  team: "platform-engineering"

visibility:
  mode: "public"

compatibility:
  providers: ["openai", "anthropic", "azure-openai"]
  agentTargets: ["cli", "ide", "web"]
  minTokenContext: 8000

validation:
  profiles: ["oai2-core", "secure-prompting-v1"]

Identity, ownership, visibility, compatibility, validation profiles — declared once, machine-readable, and travelling with the content. Variables move out of the prose and into a schema, so strictness becomes an enum with a default rather than a sentence someone has to remember to edit.

The registry is the other half. It handles publishing, validation, search with visibility enforcement, controlled sharing, retrieval, and subscriptions. Artifacts sit in one of three visibility modes: public, private, or private-shareable — the last being the interesting one, where an artifact is invisible by default but grantable to named partner organizations.

flowchart LR
    A["Author package"] --> B["Validate against profiles"]
    B --> C["Publication gate"]
    C --> D["Registry: versioned, searchable"]
    D --> E["Share grant to named org"]
    D --> F["Subscription: notify on new release"]

The key point of the flow: validation is a gate, not a formality. A package that only parses can be stored, but publication requires it to pass the deterministic rule set.

An illustrative walkthrough

The following scenario is illustrative — it uses the project’s own sample artifacts and demo seed data, not a real customer.

Acme’s platform team owns that TypeScript review prompt. They package it, run oai2 validate locally, and publish. The registry checks the manifest, verifies the declared entrypoint actually exists in the archive, scans for secret patterns, computes a SHA-256 over the package, and — if the checks pass — publishes it as an immutable 1.2.0.

Globex wants it. Because the artifact is public, they find it via search, oai2 inspect it to see maintainers and compliance level, and oai2 pull a specific version. They then subscribe with a compliance filter, so when Acme ships 1.3.0 a signed webhook arrives rather than a rumour.

Now change one detail: Acme’s safety constraints artifact is private-shareable. Globex cannot find it at all until Acme creates an org-to-org grant, optionally scoped to a semver range and an expiry date. Same registry, same package format, different disclosure decision — expressed as configuration rather than as a forwarded email.

Who this is for, and what it solves

• Engineering leads get an answer to “which version of the review standard is this team actually using?” that does not depend on someone’s memory.
• AI platform teams get one distribution path instead of per-team copies, and a subscription mechanism so downstream teams learn about changes.
• Artifact maintainers get named ownership, immutable versions, and deprecation with a declared successor — so improving an artifact is not a broadcast-and-hope exercise.
• Governance functions get visibility modes, validation profiles, risk-tier declarations, and an audit log of state-changing operations.

What this adds over Git or a shared doc

Git already gives you history, review, and diffs, and for a single team that is often enough. What it does not give you is a manifest contract: a machine-readable declaration of identity, compatibility, and ownership that other systems can act on. Nor does it give you cross-organization discovery with visibility enforcement, validation as a publication gate, selective sharing with expiry, or update subscriptions to a repository you have no access to.

Two honest limits. Interoperability is a design objective, not a promise: the compatibility block declares intended providers and targets — it does not mean an artifact behaves identically across tools or models. And validation checks specified rules only: passing oai2-core means the package is well-formed and free of the patterns the rules describe. It is not a claim of correctness, safety, or reproducible model behaviour. The project’s own design principles put it plainly — AI-assisted validation is an assistive layer, not a guarantee.

Where the project actually stands

Implemented today: organization registration and API keys; artifact catalog with lifecycle states; versioned package upload with hashing; fifteen oai2-core manifest checks with a publication gate; full-text search with visibility scoping and facets; org-to-org share grants with version ranges and expiry; subscriptions with HMAC-signed webhook delivery; an audit log; a web UI; and a CLI covering login, validate, publish, search, inspect, pull, and subscribe.

Specified but not yet built: standards profile management, publisher domain verification, artifact signing and provenance attestations, deeper dependency resolution, and the extended CLI surface (share, fork, drift detection, upstream pull). That matters for the compliance ladder — Declared and Validated are reachable now; Verified and Trusted depend on the profile and trust work still ahead. The licensing model is also still open.

When you do not need this

If one team owns three prompts and everyone who uses them sits in the same standup, a versioned file in the repo is the right answer. The cost of packaging is only worth paying when artifacts cross a boundary — between teams, between an authoring group and its consumers, or between organizations — and when someone downstream needs to know that what they have is current, owned, and checked.

If that boundary exists in your organization, the four sample artifacts in the project repository are the fastest way to judge whether the model fits: a prompt template, a system instruction, a policy pack, and a workflow definition, each complete with manifest, variable schema, and test cases. Read one manifest end to end. Either it describes a problem you recognise, or it does not.

The project can start simple: press a key, speak into a microphone, send the audio for transcription, pass the text to an AI model, then play the spoken response through a speaker. From there it can grow into a wake-word assistant, camera-aware helper, local automation controller, or even a small household AI terminal.

What the Project Is

The project is an AI-powered voice assistant running on a Raspberry Pi.

At a high level, it does this:

1. Captures speech from a USB microphone.
2. Converts speech to text.
3. Sends the text to an AI model.
4. Receives a response.
5. Converts the response to speech.
6. Plays the answer through a speaker.
7. Optionally captures images from a camera for visual questions.

The design is intentionally hybrid. The Raspberry Pi does the local hardware work, while the AI model runs in the cloud.

That gives the best balance of cost, performance, and simplicity.

Why Not Run Everything Locally?

A Raspberry Pi can do a lot, but it is not ideal for running a modern large language model locally. Small models may run, but they are usually slow, limited, or frustrating for natural conversation.

Speech recognition is also computationally expensive. Lightweight local models can work, but they may be slower or less accurate than cloud-based speech-to-text services.

The better early design is:

Raspberry Pi = local appliance
Cloud AI = intelligence layer

That means the Pi handles microphones, speakers, camera, wake word detection, and local actions. The cloud handles transcription, reasoning, and advanced language understanding.

This keeps the device responsive without needing expensive hardware.

Basic Architecture

flowchart TD
    A["User speaks"] --> B["USB microphone"]
    B --> C["Raspberry Pi audio capture"]
    C --> D["Speech-to-text service"]
    D --> E["AI chat model"]
    E --> F["Text response"]
    F --> G["Text-to-speech engine"]
    G --> H["Speaker output"]
    H --> I["User hears response"]

The important design decision is that not every stage has to use the same provider. For example, the project could use one service for speech-to-text, another for the AI model, and a local engine for text-to-speech.

That makes the system flexible and cost-conscious.

Recommended Version 1

The first version should avoid unnecessary complexity.

A practical first milestone is a push-to-talk assistant:

Press Enter → record speech → transcribe → ask AI → speak answer

This avoids wake-word detection, continuous listening, and streaming audio. Those can be added later once the basic loop works.

Version 1 Components

Important Hardware Lesson

A standard Raspberry Pi headphone jack does not accept microphone input. It is for audio output only.

That means a phone-style headset with an inline microphone will not appear as a capture device.

To capture speech, one of these is needed:

• USB microphone
• USB webcam with built-in microphone
• USB sound card with microphone input
• I2S microphone module
• Microphone HAT or array board

For a simple assistant, a USB webcam microphone or USB microphone is the easiest option.

Once the USB camera/microphone is plugged in, the Pi should show a capture device:

arecord -l

Example output:

**** List of CAPTURE Hardware Devices ****
card 3: gadget [USB Webcam gadget], device 0: USB Audio [USB Audio]
  Subdevices: 1/1
  Subdevice #0: subdevice #0

That tells us the microphone is available as:

plughw:3,0

A direct recording test can then be done with:

arecord -D plughw:3,0 -f S16_LE -r 16000 -c 1 -d 5 test.wav
aplay test.wav

If the recording plays back clearly, the microphone is working.

Proposed Tech Stack

flowchart LR
    subgraph Hardware["Hardware"]
        Mic["USB microphone"]
        Cam["USB / Pi camera"]
        Speaker["Speaker or headphones"]
    end

    subgraph Pi["Raspberry Pi"]
        Python["Python assistant app"]
        Audio["ALSA audio capture/playback"]
        Piper["Piper local TTS"]
        Skills["Local skills / commands"]
    end

    subgraph Cloud["Cloud AI Services"]
        STT["Speech-to-text"]
        LLM["AI chat model"]
        Vision["Vision model"]
    end

    Mic --> Audio
    Audio --> Python
    Python --> STT
    STT --> LLM
    LLM --> Python
    Python --> Piper
    Piper --> Speaker
    Cam --> Python
    Python --> Vision
    Vision --> LLM
    Python --> Skills

The Raspberry Pi becomes the physical interface. The AI services provide the intelligence. Local skills can be added later for actions that should not need cloud reasoning.

Software to Install on the Raspberry Pi

Assuming Raspberry Pi OS is already installed, updated, and accessible via SSH, the basic dependencies are:

sudo apt update
sudo apt upgrade -y

sudo apt install -y \
  git curl wget unzip jq \
  python3 python3-venv python3-pip \
  portaudio19-dev python3-pyaudio \
  libasound2-dev alsa-utils \
  ffmpeg sox \
  mpg123 \
  espeak-ng

For Python:

mkdir -p ~/pi-ai-assistant
cd ~/pi-ai-assistant

python3 -m venv --system-site-packages .venv
source .venv/bin/activate

pip install --upgrade pip wheel setuptools

pip install \
  openai \
  sounddevice \
  scipy \
  numpy \
  python-dotenv \
  webrtcvad \
  requests

For camera support on Raspberry Pi OS:

sudo apt install -y python3-picamera2

The --system-site-packages option is useful because some Raspberry Pi camera packages are installed through the OS package manager rather than through pip.

Local Text-to-Speech With Piper

For cost control, spoken output should ideally be local.

Piper is a good fit because it runs locally and can generate natural enough speech without sending every AI response to a cloud text-to-speech provider.

A typical folder layout might look like this:

~/pi-ai-assistant/
├── assistant.py
├── camera_test.py
├── .venv/
├── piper/
│   ├── piper/
│   │   └── piper
│   └── voices/
│       ├── en_GB-semaine-medium.onnx
│       └── en_GB-semaine-medium.onnx.json
└── snapshots/

The assistant can send text into Piper and play the resulting .wav file using aplay.

Core Voice Flow

The first working Python version only needs a few functions:

flowchart TD
    A["Start assistant"] --> B["Wait for user input"]
    B --> C["Record 6 seconds of audio"]
    C --> D["Save temporary WAV file"]
    D --> E["Send audio for transcription"]
    E --> F["Send text to AI model"]
    F --> G["Receive answer"]
    G --> H["Generate speech locally with Piper"]
    H --> I["Play audio response"]
    I --> B

This is deliberately simple. It avoids the harder problem of knowing exactly when the user has finished speaking.

Later, the fixed six-second recording can be replaced with voice activity detection.

Basic Assistant Script

A minimal assistant can be structured like this:

import os
import subprocess
import tempfile
from pathlib import Path

import sounddevice as sd
from scipy.io.wavfile import write
from openai import OpenAI

client = OpenAI()

BASE_DIR = Path.home() / "pi-ai-assistant"
PIPER_BIN = BASE_DIR / "piper" / "piper" / "piper"
PIPER_MODEL = BASE_DIR / "piper" / "voices" / "en_GB-semaine-medium.onnx"

SAMPLE_RATE = 16000
RECORD_SECONDS = 6
INPUT_DEVICE = None


def record_audio(path: str):
    print(f"Recording for {RECORD_SECONDS} seconds...")
    audio = sd.rec(
        int(RECORD_SECONDS * SAMPLE_RATE),
        samplerate=SAMPLE_RATE,
        channels=1,
        dtype="int16",
        device=INPUT_DEVICE,
    )
    sd.wait()
    write(path, SAMPLE_RATE, audio)
    print("Recording complete.")


def transcribe_audio(path: str) -> str:
    with open(path, "rb") as f:
        result = client.audio.transcriptions.create(
            model="gpt-4o-mini-transcribe",
            file=f,
        )
    return result.text.strip()


def ask_ai(user_text: str) -> str:
    response = client.responses.create(
        model="gpt-4.1-mini",
        input=[
            {
                "role": "system",
                "content": (
                    "You are a concise voice assistant running on a Raspberry Pi. "
                    "Answer clearly and briefly."
                ),
            },
            {
                "role": "user",
                "content": user_text,
            },
        ],
    )
    return response.output_text.strip()


def speak(text: str):
    if not PIPER_BIN.exists():
        print("Piper not found. Printing only.")
        print(text)
        return

    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
        output_path = tmp.name

    try:
        piper = subprocess.Popen(
            [
                str(PIPER_BIN),
                "--model",
                str(PIPER_MODEL),
                "--output_file",
                output_path,
            ],
            stdin=subprocess.PIPE,
            text=True,
        )
        piper.communicate(text)

        subprocess.run(["aplay", output_path], check=False)
    finally:
        try:
            os.remove(output_path)
        except FileNotFoundError:
            pass


def main():
    print("Pi AI Assistant ready.")
    print("Press Enter to speak. Type q then Enter to quit.")

    while True:
        command = input("\nPress Enter to record > ").strip().lower()
        if command in {"q", "quit", "exit"}:
            break

        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
            audio_path = tmp.name

        try:
            record_audio(audio_path)
            user_text = transcribe_audio(audio_path)

            if not user_text:
                print("No speech detected.")
                continue

            print(f"You: {user_text}")

            answer = ask_ai(user_text)
            print(f"Assistant: {answer}")

            speak(answer)

        except Exception as e:
            print(f"Error: {e}")
            speak("Sorry, something went wrong.")
        finally:
            try:
                os.remove(audio_path)
            except FileNotFoundError:
                pass


if __name__ == "__main__":
    main()

This is not the final product, but it gives the project a working spine.

Once this works, every improvement becomes incremental.

Handling Audio Devices

One practical issue is that Linux audio devices can appear under different card numbers after reboot.

For example, a USB webcam microphone may appear as:

card 3, device 0

So the test command would be:

arecord -D plughw:3,0 -f S16_LE -r 16000 -c 1 -d 5 test.wav

But after reboot, the same device might become card 1 or card 2.

For early testing, this is acceptable. Later, the assistant should use a more stable device name or configuration.

A useful debugging command in Python is:

python - <<'PY'
import sounddevice as sd
print(sd.query_devices())
PY

This lists devices as Python sees them, which helps when choosing the correct microphone input.

Adding the Camera

The camera should not be treated as always-on intelligence. That increases complexity, cost, and privacy risk.

A better design is on-demand vision.

For example:

User: "What do you see?"
Assistant:
  1. Captures a still image.
  2. Sends the image and question to a vision model.
  3. Speaks the answer.

The camera flow looks like this:

sequenceDiagram
    participant User
    participant Pi as Raspberry Pi
    participant Camera
    participant Vision as Vision Model
    participant AI as Chat Model

    User->>Pi: "What do you see?"
    Pi->>Camera: Capture snapshot
    Camera-->>Pi: snapshot.jpg
    Pi->>Vision: Send image with question
    Vision-->>Pi: Description / visual answer
    Pi->>AI: Combine context and response
    AI-->>Pi: Final answer
    Pi-->>User: Spoken response

A basic camera test script could save a snapshot:

from picamera2 import Picamera2
import time

camera = Picamera2()
config = camera.create_still_configuration()
camera.configure(config)
camera.start()

time.sleep(1)

camera.capture_file("snapshot.jpg")
camera.stop()

print("Saved snapshot.jpg")

For a USB camera, the implementation may use OpenCV instead of Picamera2.

What the Assistant Could Do

Once the basic voice loop works, the project can become much more useful.

Possible capabilities include:

General Conversation

The assistant can answer ordinary questions:

"What is the difference between RAM and storage?"
"Explain Docker like I'm new to it."
"Give me three ideas for dinner."

Coding Helper

Since the Pi is accessible over SSH and can sit on a desk, it can become a voice-driven development companion:

"Summarise this error."
"What does this command do?"
"Remind me of the Git command to undo the last commit."

Local Device Controller

Local commands can be routed without needing the AI model to invent shell commands.

Examples:

"What is the CPU temperature?"
"How much disk space is left?"
"Restart the service."
"Take a photo."
"Check if Docker is running."

These should be implemented as safe predefined functions, not arbitrary AI-generated terminal commands.

Home Assistant Integration

The Pi could call a Home Assistant API or MQTT broker:

"Turn on the office light."
"Set the room to evening mode."
"Is the garage door open?"

In this design, the AI interprets the request, but the actual action is executed by a controlled integration.

Visual Assistant

With a camera, it can answer visual questions:

"What is on my desk?"
"Can you read this label?"
"Does this cable look plugged in?"
"What does the screen say?"

This could be especially useful as a physical troubleshooting assistant.

Personal Desk Console

It could become a small local AI terminal:

"What am I working on today?"
"Summarise my project notes."
"Create a checklist for setting up this Pi."
"Give me the next three steps."

If connected to local files or a project folder, it could answer questions about specific work.

Skill Routing

A serious assistant should not send every request blindly to a general-purpose model.

Instead, it should classify intent and route requests.

flowchart TD
    A["User request"] --> B["Transcribe speech"]
    B --> C["Intent router"]

    C --> D["General AI chat"]
    C --> E["Local system command"]
    C --> F["Camera snapshot"]
    C --> G["Home automation"]
    C --> H["Timer / reminder"]
    C --> I["Project notes lookup"]

    D --> J["Spoken response"]
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J

This matters because it keeps the assistant safer, faster, and cheaper.

For example, asking “what time is it?” should not need a cloud AI call. Asking “what is the temperature of the Pi?” should run a local command. Asking “explain the difference between these two architecture choices” can go to the AI model.

Cost Control

The biggest cost risks are:

• Sending continuous audio to the cloud
• Using premium models for every request
• Using cloud text-to-speech for every response
• Sending camera frames continuously
• Allowing long conversations to grow without limits

The cost-effective design is:

Local wake word
Local silence detection
Cloud speech-to-text only after activation
Cheap/fast AI model by default
Local Piper text-to-speech
On-demand camera only

A premium model can still be used for harder questions, but it should not be the default for every interaction.

Development Roadmap

Phase 1: Prove the Audio Loop

Goal:

Record → transcribe → ask AI → speak answer

This confirms that the microphone, API key, Python environment, and speaker output all work.

Phase 2: Add Better Recording

Replace fixed six-second recording with silence detection.

This allows the user to speak naturally without needing to fit into a fixed time window.

Phase 3: Add Wake Word

Add a wake-word engine such as Porcupine or openWakeWord.

The assistant then behaves more like:

"Hey Pi" → listen → answer

This is the first point where it starts to feel Alexa-like.

Phase 4: Add Camera Awareness

Add commands such as:

"What do you see?"
"Take a photo."
"Read this."

This should be on-demand, not continuous.

Phase 5: Add Local Skills

Add controlled local actions:

Check CPU temperature
Check disk space
Restart a known service
Read a local note
Call a local HTTP endpoint
Control Home Assistant

Phase 6: Run as a Service

Once stable, run the assistant under systemd so it starts automatically on boot.

Example service shape:

[Unit]
Description=Raspberry Pi AI Voice Assistant
After=network-online.target sound.target
Wants=network-online.target

[Service]
Type=simple
User=dian
WorkingDirectory=/home/dian/pi-ai-assistant
Environment=OPENAI_API_KEY=your_api_key_here
ExecStart=/home/dian/pi-ai-assistant/.venv/bin/python /home/dian/pi-ai-assistant/assistant.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

The API key should eventually be handled more safely than hardcoding it directly in the service file, but this shape is enough to understand the moving parts.

Security Considerations

A voice assistant that can run commands must be treated carefully.

The assistant should not be allowed to execute arbitrary shell commands generated by an AI model.

Instead, use a whitelist:

ALLOWED_ACTIONS = {
    "cpu_temperature": get_cpu_temperature,
    "disk_space": get_disk_space,
    "take_photo": take_photo,
    "restart_known_service": restart_known_service,
}

The model can choose from known actions, but the code decides what those actions are allowed to do.

This distinction is important.

Bad design:

User asks → AI writes shell command → Pi executes it

Better design:

User asks → AI identifies intent → Pi runs predefined safe function

Privacy Considerations

The microphone should not constantly stream to the cloud.

A safer design is:

Local wake word detection
Then record
Then send only the captured request

The camera should also be explicit:

Only capture when the user asks a visual question

This keeps the assistant useful without turning it into a constant surveillance device.

Possible Final Form

The finished assistant could become a small desk-based AI companion:

flowchart TD
    A["Raspberry Pi AI Assistant"] --> B["Voice chat"]
    A --> C["Camera-based visual help"]
    A --> D["Local system tools"]
    A --> E["Home automation"]
    A --> F["Project assistant"]
    A --> G["Reminders and timers"]
    A --> H["Developer helper"]

    B --> B1["Ask questions"]
    B --> B2["Have short conversations"]

    C --> C1["Describe scene"]
    C --> C2["Read text"]
    C --> C3["Troubleshoot physical objects"]

    D --> D1["CPU temperature"]
    D --> D2["Disk space"]
    D --> D3["Service status"]

    E --> E1["Lights"]
    E --> E2["Sensors"]
    E --> E3["MQTT / Home Assistant"]

    F --> F1["Read local notes"]
    F --> F2["Summarise project state"]
    F --> F3["Suggest next steps"]

The useful part is not merely that it talks. The useful part is that it bridges the physical room, local devices, project context, and cloud intelligence.

What Should Be Built First

The correct first version is intentionally modest.

Build this first:

USB microphone
Python script
Cloud speech-to-text
Cloud AI response
Local Piper speech output
Manual press-to-talk loop

Only after that works reliably should the project add:

Wake word
Silence detection
Camera vision
Local action routing
systemd startup
Home Assistant integration

That progression avoids wasting time on complicated assistant behaviour before the basic hardware and software path is proven.

Conclusion

A Raspberry Pi AI assistant is very achievable if the project is built in layers. The Pi should not try to be the entire AI system. It should be the local appliance: microphone, speaker, camera, wake word, and safe local actions. The cloud AI service should handle the heavy language and speech intelligence.

The most efficient and cost-effective path is:

Start simple.
Use the cloud where the Pi is weak.
Run locally where cloud cost is unnecessary.
Add intelligence in controlled layers.

That gives a practical assistant now, with a clear route toward something much more capable later.

So I did the sensible thing first and went looking at what already exists. WordPress was the obvious candidate, and it is genuinely good at what it does — but it is a database, a PHP runtime, an admin interface, an update treadmill and a security surface, all standing between me and a text file. That is a fair trade for a site with editors, plugins and comment threads. For one person publishing occasional posts it is an installation to maintain in exchange for nothing I actually wanted.

That pointed me at the open-source static site generators instead, which are much closer to the right shape. I picked one, installed it, and then spent the next stretch of time doing everything except writing: reading theme documentation, working out which of three config files owned a setting, tracing why a layout override was ignored, and discovering that the small visual change I wanted lived somewhere inside a theme I had not written and did not want to learn.

None of that was the generator’s fault. It was solving a much bigger problem than mine. But at some point the frustration tipped over into curiosity: how much of this do I actually need?

The honest answer turned out to be very little. A couple of hours later I had a working engine, and about thirty minutes after starting it I had a real post rendered and published. This project was an absolute pleasure to work on — one of those rare ones where the scope stays exactly where you put it.

What it actually is

The whole engine is one Node script, three HTML templates and a stylesheet:

build.js       the entire build, ~25 kB, read top to bottom
templates/     layout.html, post.html, index.html, contact.html
src/styles.css the whole design
blog/          Markdown posts, one flat folder
public/        assets copied verbatim into dist/
dist/          generated output — safe to delete, never edited by hand

That comes to roughly 43 kB of source in total. Five npm dependencies do the heavy lifting: markdown-it for rendering, markdown-it-anchor for heading links, gray-matter for frontmatter, highlight.js for code, and fs-extra for file operations.

There is no database, no admin interface, and nothing to install on the server beyond Node and nginx. The build runs on my laptop or over SSH and produces plain static HTML files; nginx serves those files and does nothing else. Nothing executes when a visitor loads a page, so there is no login to protect, no schema to migrate, and no backup to take that a git clone does not already cover. The posts are the backup — they are Markdown files in a folder.

Writing a post means creating blog/<slug>.md:

---
title: A clear, specific title
date: 2026-09-10
tags:
  - static-sites
slug: optional-override    # defaults to the filename
draft: false               # drafts are excluded from the build
description: Optional      # otherwise the first paragraph is used
---

Markdown, raw HTML, and inline `style` attributes all work.

blog/my-post.md becomes dist/blog/my-post/index.html, served at /blog/my-post/. Only title and date are required. A missing title, an unparseable date, or a slug that collides with an existing post fails the build loudly — I would much rather see an error in the terminal than a broken page on the live site.

How the build works

The pipeline is deliberately linear. Nothing is incremental, nothing is cached, and the whole site rebuilds in milliseconds because there is almost nothing to do.

flowchart TD
    A["blog/*.md"] --> B["gray-matter: split frontmatter from body"]
    B --> C["Validate: title, date, unique slug"]
    C --> D["markdown-it: render body to HTML"]
    D --> E["Custom fence rule"]
    E --> F["mermaid fence → pre.mermaid, rendered in the browser"]
    E --> G["Other languages → highlight.js at build time"]
    F --> H["Post objects: slug, dates, tags, reading time, excerpt, prev/next"]
    G --> H
    I["templates/*.html"] --> J["{{name}} substitution"]
    H --> J
    J --> K["dist/"]
    L["public/ + docs/banners/"] --> K
    M["src/styles.css + code theme"] --> N["Concatenate, hash, styles.HASH.css"]
    N --> K
    K --> O["Post pages, homepage, archive, contact"]
    K --> P["rss.xml, sitemap.xml, robots.txt"]

The key point the diagram makes is that there is exactly one path from a Markdown file to a page, and one templating mechanism holding it together. Posts are loaded and validated, rendered to HTML, decorated with derived metadata, poured into templates via {{name}} substitution, and written to disk alongside the copied assets and the feed. There is no plugin system, no theme layer, no lifecycle hooks. When something looks wrong on the page, the code that produced it is in one file and I can find it by reading downwards.

The template engine is four lines:

function render(template, vars) {
  return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (match, key) => {
    const value = vars[key];
    return value === undefined || value === null ? '' : String(value);
  });
}

That is the entire abstraction. No conditionals, no loops, no partials. Anything that needs logic is a small JavaScript function that returns an HTML string, which is a perfectly good template language when you already know JavaScript.

What it supports

Markdown, with the typographer on. Standard CommonMark plus smart quotes, dashes, and automatic linkification of bare URLs. Headings at levels 2–4 get permalink anchors.

Raw HTML and inline CSS. html: true is set intentionally. When Markdown is not expressive enough — a two-column block, a bit of colour, a <details> disclosure — I drop into HTML in the middle of a post and carry on. This is a single-author site, so the usual reason to sanitise Markdown does not apply; the escape hatch is worth more than the restriction.

Embedded media. Anything in public/ is copied to the root of dist/, so public/images/diagram.webp is referenced as /images/diagram.webp. Video works the same way — a plain <video> tag with a file from public/, no plugin or shortcode involved.

An image viewer. After the page loads, every image in the post body is wrapped in a button that opens it in a native <dialog> lightbox. Using the browser’s own dialog element means Escape, focus trapping, and backdrop clicks all work without me implementing any of them. If an image has a data-full attribute pointing at a larger original, the lightbox opens that instead, so pages can ship a smaller display copy.

Mermaid diagrams. A fenced block tagged mermaid is emitted as <pre class="mermaid"> rather than highlighted as code, and Mermaid 11 renders it in the browser. The loader script is only injected into pages that actually contain a diagram — the build checks the rendered HTML for class="mermaid" and adds the module import only where it is needed. Every other fenced block is highlighted at build time, so ordinary posts ship no JavaScript for code at all.

Syntax highlighting with no client-side cost. highlight.js runs during the build and its GitHub theme is concatenated onto the stylesheet, which is then content-hashed into styles.<hash>.css so a design change invalidates caches by itself.

RSS, sitemap, robots. The feed carries the twenty most recent posts with full content, not truncated summaries. The sitemap lists every published URL with the post’s own date as lastmod.

Derived metadata I never have to type. Reading time from a word count, an excerpt taken from the first real paragraph when no description is given, previous/next navigation between adjacent posts, and tag lists.

A contact form with no backend. The form posts to Web3Forms, which relays submissions to email. A static site stays static.

Rotating banners. Each page picks a banner image at random, but tracks what it has shown in sessionStorage so every image appears once before any of them repeats. Intrinsic width and height are read directly out of the PNG, WebP, or SVG header at build time — about forty lines of byte-offset parsing instead of an image library — so the page reserves the right space and does not jump while the image loads.

Publishing

Local development is npm run dev: a watcher on blog/, templates/, src/, public/ and the banners folder, a debounced rebuild, and a small static server on port 3000. npm run drafts does the same but includes posts marked draft: true, so unfinished writing is visible to me and invisible to everyone else.

Releases are a tarball with a checksum. package.sh builds the archive, deploy.sh installs the engine on the server and installs dependencies there, and publish.sh rebuilds the live site from whatever is currently in the server’s blog/ directory. Deployment never overwrites posts or uploaded images, and both scripts take a lock directory so a deploy and a publish cannot interleave. Publishing a new post is: copy the Markdown up, run publish.sh. No pipeline, no build minutes, no vendor.

Was it worth it?

For a personal blog, easily. The trade is real and worth stating plainly: I gave up an ecosystem. There are no plugins, no themes, no community answers to search when something breaks, and no one else maintaining it. If this were a site with several authors, non-technical editors, comments, or requirements I could not predict, that would be the wrong trade — I would install WordPress or learn a mature generator’s theme system properly, and be glad the work had already been done.

But my requirements were fully known on day one, and they were small. The cost of learning someone else’s abstraction over a large problem turned out to be higher than the cost of writing my own small solution to a small one. And there is something genuinely pleasant about a project where reading the source is reading the documentation — where the answer to “why does the page look like that” is always about forty lines away.

The situation this is built for

A familiar version goes like this. Someone senior asks what the team is doing about AI. The answer is honest but unsatisfying: a few engineers use an assistant in their editor, someone prototyped a chatbot against internal documents, and there is a slide deck circulating about agents. Meanwhile the list of candidate tools grows every month, each with a persuasive demo and a different assumption about how you already work.

Readiness inside the team is uneven. One squad has strong test coverage and fast CI; another is maintaining a service where a change takes three days to verify. The data that would make a promising use case viable is scattered across systems with unclear ownership. Nobody is quite sure which constraints are real and which are habits.

The instinctive response is to pick tools. That is where the trouble starts, because a tool choice made in isolation quietly assumes several things are already true:

• That your delivery practices can absorb the change — that code review, testing, and release processes will still hold when more code arrives faster.
• That the platform underneath can support the use case — that the data is accessible, described, and trustworthy enough to be worth pointing a model at.
• That the team can supervise the output — that someone can tell a good result from a plausible-looking wrong one, and has the time to check.

When those assumptions do not hold, the tool is not the thing that fails. Delivery is. The pilot stalls, the enthusiasm drains, and the organisation concludes that “AI didn’t work for us” when what actually happened is that a reasonable idea was applied to an unready context.

What Compass is

Compass is a decision-support application for AI adoption in software delivery and platform architecture. Its central idea is straightforward: assess the context first, understand the trade-offs that context creates, and turn the findings into a practical adoption plan the team can actually run.

It is not an autonomous engineering team. It does not write your services, deploy your changes, or enforce policy on your behalf. It is also not a universal AI strategy product — it is deliberately scoped to how software teams build, ship, and operate systems.

The work is organised around two complementary perspectives:

• Software delivery. Which AI tools and workflows fit the way this team actually builds and ships software?
• Platform architecture. Where could AI add value inside this system, and which foundations need attention before that is sensible?

Teams often start with one and discover they need the other. A delivery assessment surfaces a promising use case that turns out to depend on data the platform cannot yet serve. An architecture assessment identifies a strong opportunity that the team has no realistic capacity to supervise. Holding both perspectives is the point.

How it works

You describe the project and the team: what you are building, who is on it, how you work now, which tools you already use, and the constraints you are operating under. Where a platform perspective is relevant, you describe the capabilities that matter for it.

From there you explore delivery needs, platform needs, or both, through guided assessments. Compass uses that context to produce findings you can review rather than verdicts you have to accept: AI readiness and project complexity insights, recommendations across the software development lifecycle, architecture capability and gap analysis, candidate AI opportunities with their prerequisites, and risk, oversight and governance considerations attached to each.

You then compare possible changes. Save an assessment, adjust the assumptions, and look at an alternative scenario side by side — a more cautious rollout against a more ambitious one, or the same ambition with a different sequence. From the comparison you agree priorities and a phased plan, and produce reports you can take into a leadership conversation.

Later, when the situation has moved, you revisit the assessment.

flowchart LR
    A["Project and team context"] --> B["Guided assessment"]
    B --> C["Software delivery perspective"]
    B --> D["Platform architecture perspective"]
    C --> E["Findings and recommendations"]
    D --> E
    E --> F["Compare options and priorities"]
    F --> G["Phased adoption plan"]
    G --> H["Reassess as circumstances change"]
    H --> B

The loop at the end of that diagram is a team activity, not continuous automated monitoring. Nothing is watching your repositories and silently updating a score. Reassessment happens when you decide something has changed enough to warrant it — a platform capability landed, a team grew, a pilot taught you something. Saved assessments, history, and trends exist so that when you come back, you are comparing against what you actually thought last time rather than against memory.

Shared workspaces and comments serve the same purpose. The output of an assessment is most useful as something a group argues with.

A worked example (hypothetical)

The following scenario is illustrative. It is not a customer case study, and it does not represent specific Compass outputs.

Imagine a team of nine maintaining an established logistics application. The codebase is a decade old in places, test coverage is patchy in exactly the modules that change most, and the release cadence is fortnightly. Two engineers use an AI assistant informally; nobody else does. A board member has asked why delivery is not faster.

Working through a delivery assessment, the team articulates something they already half-knew: their bottleneck is not typing code, it is the time between “change written” and “change trusted”. That reframes the shortlist. Generating more code faster into a codebase with weak verification is not obviously an improvement. Bounded assistance in areas with clear feedback — test scaffolding, refactoring under existing coverage, review support — looks more defensible as a first step.

An architecture perspective adds a second finding. The team is interested in an AI-assisted feature for exception handling in shipment data, and the case for it is genuinely good. But the assessment surfaces prerequisites: the relevant data is spread across two systems with inconsistent identifiers, and there is no established path for a human to review and correct a suggested resolution. That does not kill the idea. It sequences it.

The team then compares a more ambitious scenario — pursuing the customer-facing feature within the quarter — against the cautious one. Seeing the prerequisites and oversight requirements laid out next to the timeline makes the trade-off concrete rather than rhetorical. They choose the cautious sequence, with the ambitious use case explicitly parked and a review checkpoint set for when the data work completes.

The valuable output here is not a tool recommendation. It is a defensible answer to “why aren’t we doing the exciting thing yet”, and a date on which that answer gets re-examined.

Who it is for

• Engineering leaders deciding where adoption effort goes first across several teams with different readiness, and needing to explain that ordering to people above and below them.
• Technical founders balancing genuine ambition against a small team’s capacity, who need to know which single change is worth the disruption this quarter.
• Architects evaluating whether the platform can support a proposed AI capability, and what has to be true first.
• Delivery managers working out how a change lands in existing workflows — what it does to review load, testing, estimation, and the shape of a sprint.
• Consultants who need a repeatable way to structure a client assessment and communicate recommendations that hold up under challenge.

Why this shape of tool works

Context makes recommendations relevant. A recommendation that ignores your test coverage, your release process, and your team’s experience is a generic list. The same recommendation, produced against a described context, can be argued with on its merits.

Two perspectives expose different constraints. Delivery assessment finds workflow and capacity limits. Architecture assessment finds data, integration, and foundation limits. Teams that only look at one tend to be surprised by the other.

Explanations matter more than conclusions. Findings come with the reasoning that produced them, which is what lets a team disagree productively. A recommendation you cannot interrogate is not decision support; it is an instruction.

Comparison beats commitment. Examining two plausible futures side by side is cheaper than discovering the difference by living through one.

Governance outputs are planning aids. Risk considerations, human oversight guidance, and governance templates help a team think through supervision and accountability before adopting something. They are inputs to your own process — not evidence of compliance, and not automated enforcement.

Two design principles are worth stating plainly, because they are easy to get wrong.

The first: unknown is not the same as absent. If a team cannot answer a question about their data lineage, the honest reading is that they do not currently know — which is itself useful information, and often the first thing worth fixing. Treating every gap in knowledge as a confirmed deficiency produces a bleaker and less accurate picture than the team deserves.

The second: readiness is not one number. A team can be strong on engineering practice and weak on data foundations, or the reverse. Collapsing those into a single verdict destroys exactly the information that would tell you what to do next. Different dimensions deserve to stay separate.

Deferring is a real answer

The most useful output of an assessment is often “not this, not yet”.

flowchart TD
    A["Potential AI use case"] --> B["Consider value and context"]
    B --> C["Review foundations, risk and oversight"]
    C --> D["Suitable to explore now"]
    C --> E["Foundations need attention"]
    C --> F["Defer or retain the current approach"]
    D --> G["Bounded pilot with human review"]
    E --> H["Prioritise improvements"]
    H --> C
    G --> I["Evaluate and revisit"]
    F --> I

This diagram describes a decision-making philosophy, not Compass’s internal rules. Its point is that three outcomes are legitimate. A use case can be suitable to explore now, as a bounded pilot with human review. It can be blocked on foundations, in which case the improvement work is the AI work. Or it can be deferred, with the current approach retained — sometimes because the value is thin, sometimes because the oversight burden exceeds what the team can carry.

Naming a prerequisite is a result. It converts a vague sense that “we’re not ready” into a specific piece of work with a name and an owner. And an explicit deferral, recorded with its reasoning and a date to revisit, is far more durable than an idea that quietly stalls and reappears in six months with nobody able to say what happened last time.

The takeaway

Adopting AI well is less about finding the best tool than about knowing which decisions you are actually making, on what evidence, and in what order. Compass exists to make those decisions deliberate and explainable — to give a team a clear view of its own context, an honest account of its gaps, and a defensible next step rather than a backlog of enthusiasm.

If your team is somewhere between “we should be using AI” and knowing what to do on Monday, the useful move is to assess a real project — one with actual constraints, actual people, and an actual deadline — and see what the context tells you.

That model is useful on its own, but it also creates a natural path toward something broader: the same Markdown source can drive a live or periodically refreshed dashboard without introducing a second definition format.

The important architectural decision is that the Markdown document remains the source of truth. The dashboard, generated Markdown, and exported PDF are all different views of the same underlying definition.

The Original Forge Model

At its simplest, Forge consists of a document library, an editor, and a CLI.

A document stored in the tenant library contains normal Markdown alongside executable or retrievable blocks. The CLI retrieves that source, executes the dynamic sections, and generates an updated Markdown document.

The resulting document can remain local, be posted back into the Forge library, or be exported further, for example to PDF.

flowchart LR
    A["Forge SaaS Library"] --> B["Markdown Source"]
    B --> C["Forge CLI"]
    C --> D["Execute dynamic blocks"]
    D --> E["Generated Markdown"]
    E --> F["Local file"]
    E --> G["Post back to Forge"]
    E --> H["Export to PDF"]

The strength of this model is that execution happens where the CLI runs.

That means a Forge document can obtain information that a hosted SaaS platform would not normally be able to reach, including local files, private databases, Docker, internal services, operating-system information, or commands that require elevated privileges.

Markdown Remains the Source of Truth

The extension into dashboards should not introduce a second configuration system.

Instead of maintaining one definition for documentation and another for monitoring, Forge can use the same Markdown document to define both.

Conceptually:

flowchart TD
    A["Forge Markdown"] --> B["Execution Layer"]

    B --> C["Generated Document"]
    B --> D["Dashboard State"]

    C --> E["Markdown"]
    C --> F["PDF"]

    D --> G["Hosted Dashboard"]

The document defines:

• what information is required,
• how that information should be retrieved,
• how often a live value should be refreshed,
• where execution should take place,
• and how the result should be represented.

The dashboard is therefore not a separate application definition. It is a visual rendering of the same document.

From Document Blocks to Dashboard Widgets

An executable Forge block can be treated as both a document element and a dashboard widget.

For example, a document might contain blocks representing:

• production API health,
• server disk usage,
• Docker container state,
• Git branch or release information,
• SSL certificate expiry,
• database statistics,
• deployment status,
• open issues,
• or custom script output.

When the document is generated normally, these blocks become Markdown.

When the document is viewed as a dashboard, the same blocks become visual widgets.

flowchart LR
    A["Widget definition in Markdown"] --> B["Execute"]
    B --> C["Structured result"]

    C --> D["Markdown renderer"]
    C --> E["Dashboard renderer"]

    D --> F["Table / text / status"]
    E --> G["Card / gauge / chart / status"]

This separation between execution and presentation is what makes the extension practical.

A disk-space block, for example, should ideally return structured information rather than preformatted text:

{
  "totalBytes": 250000000000,
  "usedBytes": 184000000000,
  "freeBytes": 66000000000,
  "usedPercent": 73.6
}

The Markdown renderer might turn that into a table.

The dashboard renderer might display a progress bar or gauge.

The underlying result remains the same.

Every Document Can Have a Dashboard

Once widgets produce structured state, every Forge document can automatically have an associated dashboard.

The default dashboard layout can follow the order of the Markdown document.

For example:

## Production

:::
type: http-health
title: API
refresh: 30s
:::

:::
type: disk-space
title: Disk
path: /
refresh: 5m
:::

:::
type: docker-status
title: Containers
refresh: 1m
:::

Forge could automatically derive a dashboard similar to:

┌──────────────────┐  ┌──────────────────┐
│ API              │  │ Disk             │
│ Healthy          │  │ 73.6% used       │
└──────────────────┘  └──────────────────┘

┌──────────────────┐
│ Containers       │
│ 6 / 6 running    │
└──────────────────┘

The user can then visually rearrange those widgets.

That rearrangement does not need to alter the underlying Markdown. It can be stored separately as presentation metadata.

flowchart TD
    A["Markdown source"] --> B["Widget definitions"]
    B --> C["Default dashboard layout"]

    C --> D["User rearranges widgets"]
    D --> E["Dashboard layout metadata"]

    A --> F["Still remains canonical source"]

This keeps the responsibilities clean:

The CLI Becomes a Generator and a Watcher

The existing CLI can be extended rather than replaced.

Its first role remains document generation.

forge generate production.md

Its second role becomes continuous or scheduled execution.

forge agent production.md

In agent mode, the CLI periodically executes the widgets defined in the Markdown and sends only the resulting structured state back to the SaaS platform.

flowchart LR
    A["Forge Library"] --> B["Markdown source"]
    B --> C["Forge CLI / Agent"]

    C --> D["Run widgets locally"]
    D --> E["Structured widget state"]

    E --> F["Forge SaaS"]
    F --> G["Hosted dashboard"]

This is important because the hosted dashboard does not need direct access to the customer’s infrastructure.

The CLI executes where the data is actually available.

Why the Local Runner Matters

A hosted Forge service can directly query many external APIs, but it cannot automatically inspect a private server.

For example, a dashboard widget may want to display:

Production server disk usage

The Forge SaaS platform cannot normally run:

df -h /

on a user’s private Linux server.

The local Forge agent can.

flowchart LR
    A["Private Server"] --> B["Forge CLI / Agent"]
    B --> C["df / Docker / DB / local API"]
    C --> D["Structured result"]
    D --> E["Outbound HTTPS"]
    E --> F["Forge SaaS Dashboard"]

Only an outbound connection is required.

There is no need for Forge SaaS to open a connection into the private network.

That makes the model suitable for small companies and individual developers who want useful system visibility without deploying a larger monitoring stack.

Generate Once or Watch Continuously

The same Markdown source can therefore support two execution patterns.

Point-in-time generation

forge generate production.md

This executes the document once and produces a snapshot.

Continuous execution

forge agent production.md

This keeps selected widgets refreshed and sends their latest values to the hosted dashboard.

flowchart TD
    A["Forge Markdown"] --> B{"Execution mode"}

    B -->|"generate"| C["Run once"]
    C --> D["Generate Markdown"]
    D --> E["Optional PDF export"]

    B -->|"agent"| F["Run periodically"]
    F --> G["Publish widget state"]
    G --> H["Live hosted dashboard"]

The important part is that these are not two separate products.

They are two execution modes over the same source.

A Lightweight Publish Mode

A persistent agent does not even need to be the first implementation.

A simpler intermediate command could be:

forge publish production.md

That command would:

1. retrieve or read the Markdown,
2. execute the widgets locally,
3. send the resulting widget state to Forge SaaS,
4. update the dashboard,
5. exit.

The operating system can handle scheduling.

For example:

*/5 * * * * forge publish production.md

This would provide a dashboard refreshed every five minutes without requiring Forge to initially build a persistent daemon.

The progression can therefore be incremental:

flowchart LR
    A["forge generate"] --> B["forge publish"]
    B --> C["forge agent"]
    C --> D["Installed Forge runner service"]

Each stage adds capability without invalidating the previous one.

Elevated Execution Remains Local

One particularly useful property of the local execution model is that some widgets may inspect information requiring elevated privileges.

For example:

smartctl -H /dev/nvme0

or protected service information.

Forge should not silently escalate privileges.

Instead, the document can declare that a widget requires elevation:

type: shell
title: SMART Health
command: smartctl -H /dev/nvme0
elevation: required

The CLI can inspect the document before execution:

forge inspect production.md

and report which widgets require additional permissions.

Execution might then support options such as:

forge generate production.md --skip-elevated

or:

forge generate production.md --allow-elevation

The key security principle is:

The SaaS may request privileged execution, but only the local environment can approve it.

flowchart TD
    A["Markdown requests elevated action"] --> B["Forge CLI"]
    B --> C{"Approved locally?"}

    C -->|"Yes"| D["Execute with permitted elevation"]
    C -->|"No"| E["Skip or fail widget"]

    D --> F["Publish result"]
    E --> F

The user remains in control of the machine.

For persistent agents, it is preferable that the entire Forge process does not run as root. Individual approved actions can be elevated when necessary.

Turning the Dashboard Back into Documentation

The flow also works in reverse.

A user looking at the dashboard may want to capture its current state.

Forge can generate a Markdown snapshot using the latest published widget values.

flowchart LR
    A["Live Dashboard"] --> B["Generate Snapshot"]
    B --> C["Markdown document"]
    C --> D["Forge Library"]
    C --> E["PDF export"]

This creates a useful connection between operational visibility and documentation.

Examples might include:

• release-readiness reports,
• weekly engineering summaries,
• deployment snapshots,
• environment status reports,
• incident records,
• infrastructure inventories,
• audit evidence.

The live view answers:

What does the system look like now?

The generated document answers:

What did the system look like at this point in time?

Static Context and Live Data Can Coexist

A Forge dashboard does not have to consist only of metrics.

Because the source is a document, static explanatory text and dynamic data can exist together.

For example:

## Redis

The Redis instance is intentionally undersized during beta.

:::
type: redis-memory
refresh: 1m
:::

The planned upgrade threshold is 85%.

The dashboard can display both the explanation and the current value.

That is useful because technical status rarely makes complete sense without context.

A conventional monitoring dashboard might tell someone that Redis memory is at 78%.

Forge can also explain why 78% is currently acceptable.

Not Another Prometheus or Grafana

This extension does not require Forge to become a full observability platform.

The aim is not to implement:

• high-frequency metrics ingestion,
• distributed tracing,
• log aggregation,
• long-term time-series storage,
• metric query languages,
• or complex alert-routing systems.

Forge can deliberately remain lightweight.

Its job is closer to:

retrieve → execute → structure → display → document

Where historical monitoring already exists, Forge can consume it.

A widget could retrieve information from Prometheus, CloudWatch, Grafana, or another source rather than replacing them.

This makes Forge useful both for developers who have no monitoring infrastructure and for teams that already do.

The Resulting Architecture

The resulting architecture extends the existing Forge model rather than replacing it.

flowchart TD
    A["Forge Tenant Library"] --> B["Markdown Source of Truth"]
    B --> C["Forge Editor"]
    B --> D["Forge CLI / Runner"]

    D --> E["Execute local widgets"]
    D --> F["Execute remote/API widgets"]

    E --> G["Structured widget results"]
    F --> G

    G --> H["Markdown renderer"]
    G --> I["Dashboard renderer"]

    H --> J["Generated Markdown"]
    J --> K["PDF export"]
    J --> L["Optional post back to library"]

    I --> M["Customisable hosted dashboard"]
    M --> N["Generate snapshot"]
    N --> J

The architecture retains the original strengths of Forge:

• portable Markdown,
• local execution,
• reusable blocks,
• document generation,
• tenant-hosted source,
• and optional publication back to the SaaS platform.

It adds:

• structured widget output,
• live or periodically refreshed state,
• automatic dashboards,
• visual dashboard layouts,
• local runner execution,
• dashboard snapshots,
• and a path toward lightweight operational visibility.

The defining principle remains simple:

Define the technical state once in Markdown, execute it where the truth lives, display it live when useful, and generate a document whenever a durable snapshot is needed.

That scene is not a demonstration. NeuroDesk is currently an early concept and architecture project — there is documentation and a standalone project configurator, but no implemented runtime, no sensor pipeline, no AI gateway, and no hardware prototype. The scene describes the experience we want to test, and the rest of this post is about why that experience seems worth investigating and what has to be true for it to work.

The research question underneath it is deliberately narrow: how little reliable human input is needed to direct a capable AI agent?

The problem with the devices we have

Keyboards, mice, and voice assistants are excellent, and none of them is going anywhere. But each assumes conditions that are not always available.

A keyboard assumes free hands and a surface. A mouse assumes both, plus fine motor control. Voice assumes you are somewhere you can speak, that the people around you don’t mind, and that you don’t mind them hearing. Every one of those assumptions fails regularly: walking, cooking, carrying something, sitting in a shared office, riding public transport, being in a meeting, being in a quiet home at night with someone asleep in the next room.

There is also a group of people for whom conventional input is difficult or exhausting rather than merely inconvenient. Their needs are not an afterthought here, but they are also not a solved problem, and I will come back to why.

Something else has changed alongside this. When computers only did what you told them step by step, input bandwidth was the bottleneck — you needed a keyboard because you had a lot of characters to transmit. As AI systems become able to carry out longer, more open-ended tasks, the balance shifts. Increasingly the valuable human contributions are specifying a goal and reviewing a result, not entering each individual instruction. Those two acts might not need a keyboard’s worth of bandwidth.

What the experience could feel like

The interaction NeuroDesk is exploring has a consistent shape, whatever the task.

Something presents itself as a possible target — a notification, an item in a short list, a device in the room. Your attention lands on it. Then you make a small, deliberate signal to say that one. Contextual AI turns that minimal selection into a concrete proposal for work. You see the proposal. You approve it, adjust it, or cancel. If you approve it, something happens, and you get told what happened.

Three examples of the same loop:

• Checking on a coding agent. You are away from your desk. An agent has stalled. You select the alert and confirm a proposed next step: look into why this is failing and summarise it. You review the summary later, at a keyboard, where reviewing is easy.
• A discreet personal assistant. In a meeting, you want to note a follow-up, or ask a private assistant something you would not say out loud in the room. A silent selection is more appropriate than speech here — though silence is a matter of social discretion, not a privacy guarantee.
• A familiar smart-home device. Hands full, you look at a lamp or a speaker and select the one action you almost always want from it. The vocabulary is tiny and the context does the rest.

Coding agents are one application. The broader objective is interacting with a computer without traditional input devices at all.

How it works, conceptually

Several kinds of signal can feed the same intent, and the AI layer sits between that intent and anything that actually runs.

flowchart LR
    A["Eye movement"] --> D["Deliberate user intent"]
    B["Subtle gestures"] --> D
    C["Experimental neuro-signals"] --> D
    D --> E["Contextual AI"]
    E --> F["Proposed action"]
    F --> G["User review and authorization"]
    G --> H["Computer or connected device"]
    H --> I["Feedback to the user"]

The diagram’s key point is that no single input method carries the whole burden, and nothing reaches a device or a piece of software without passing through a step where the person reviews and authorises it.

The complementary signals, in plain language:

• Eye movement is good for navigation — moving among candidates, indicating what you are currently considering.
• Subtle muscle activity or small gestures are good for selection — a discrete, intentional act that you either did or did not perform.
• Experimental brain-signal input may be useful for constrained choices, where the system only needs to distinguish between a small number of options.

Not every interaction needs all three. A given task might use one. The point of having several is that each is asked to do the thing it is plausibly good at.

The most important distinction in the whole design is between looking and selecting. Attention must never, on its own, become permission to act. If merely resting your gaze on something could trigger it, the system becomes a minefield — you would have to be careful about where you looked, which is an absurd thing to ask of a person. Looking is a proposal for consideration. Selecting is an act.

What the AI is and is not doing

The AI’s job is to take a small, contextual selection and expand it into a richer, well-specified task, using context you have authorised it to see — what you are working on, what is on screen, what device you are near, what happened a minute ago.

It is not decoding thoughts. It is not inferring intentions you never expressed. When the selection is ambiguous, the correct behaviour is to ask, not to guess and act.

The loop, end to end

flowchart TD
    A["User identifies a target"] --> B["Deliberately selects a request"]
    B --> C["AI interprets the available context"]
    C --> D["User reviews the proposed action"]
    D --> E{"Approve?"}
    E -->|Yes| F["Authorized action runs"]
    E -->|Revise| B
    E -->|Cancel| G["No action"]
    F --> H["Result returned to the user"]

Two things matter in that flow. The first is that revision loops back rather than dead-ends: getting it slightly wrong should cost one more small interaction, not a restart. The second is that cancelling is a first-class outcome. A system built around very small inputs will sometimes misread them, so an easy, obvious way to say no, stop is part of the design rather than an error path.

Who this might be for

• People looking for accessible input alternatives, where a keyboard and mouse are difficult, tiring, or unavailable.
• People whose hands are occupied — in a workshop, a kitchen, a lab, a vehicle, or simply carrying things.
• People in shared or quiet environments where speaking to a computer is intrusive or awkward.
• People supervising AI work away from their desk, who need to check in, redirect, and approve rather than author.

On accessibility specifically: I want to be careful. Accessibility here is a design opportunity that demands user research and individual adaptation. It is not a proven clinical benefit, and it is certainly not a universal solution — the range of individual difference in this space is large, and anything that works will work because it was adapted to a person, not because it was shipped to everyone.

Why the approach seems worth trying

These are reasons to investigate, not results.

• Communicating a goal can take fewer inputs than performing every step. “Find out why this is failing” is a smaller message than the sequence of clicks and keystrokes that would investigate it manually.
• Context reduces what has to be specified. If the system already knows what you are looking at and what you were doing, the part you must supply gets much smaller.
• Complementary signals avoid overloading any one channel. Asking eye tracking alone to handle both navigation and confirmation is where a lot of gaze-based interaction historically becomes uncomfortable.
• Control comes from feedback, correction, cancellation, and deliberate confirmation. Small inputs are only safe when the person can always see what is about to happen and stop it.
• Private or locally controlled AI is a design goal, because this interaction model depends on the system seeing context that is genuinely personal.
• A phone is a realistic first display. It is already in your pocket and already good at short glanceable feedback. Wearable displays are interesting later, not a prerequisite.

The honest uncertainties

This is not arbitrary thought reading, and it will not be. Silent, free-form text — composing a paragraph without moving or speaking — remains genuinely hard. Constrained selections and contextual requests are a far more realistic starting point, and that constraint is doing real work in the design rather than being a temporary limitation to be engineered away.

Open questions that need actual testing:

• Signal reliability. Small signals are noisy, and noise near a confirmation step is a serious problem.
• Accidental activation. How often does the system act when you did not mean it to, and how bad is it when that happens?
• Individual variation. Signals differ enormously between people, and probably between days for the same person.
• Comfort. Anything worn or held has to be tolerable for hours, not minutes.
• Privacy. Contextual AI requires access to context; being silent in a room is not the same as being private in a system.

And two claims I will not make: silence does not guarantee privacy, and conventional input devices are not going to become obsolete. Keyboards will remain the best tool for writing a lot of text for a long time.

What we are actually chasing

The possibility that motivates NeuroDesk is a simple one. If a person can express what they want and stay genuinely in control of the resulting work through a handful of silent, deliberate interactions — chosen on purpose, reviewed before anything happens, and reversible when they are wrong — then a large amount of useful computer work stops requiring a desk, a keyboard, or a voice.

Whether that holds up is exactly what there is to find out.

A working note on why AI-assisted development keeps running into the same wall, and what a project-scoped context layer would have to get right.

There’s a particular kind of pull request that has become common enough to be recognisable. The code is clean. The tests pass. The naming is idiomatic. And the first substantive review comment is some version of: this isn’t how we do it here.

This post is about the gap that comment reveals, and about PACE — Persistent AI Context Engine — a project I’ve been building to explore whether that gap can be closed with infrastructure rather than with more careful prompting. PACE is early. Its core works; large parts of the ambition around it do not exist yet. I’ll be specific about which is which, because a post that blurs the two isn’t worth reading.

The review comment that keeps recurring

Picture a developer adding a feature to an established service — a billing service, say, five years old, with the accumulated scar tissue that implies. They describe the feature to an assistant. They get back a reasonable-looking implementation: a new handler, a couple of helpers, some tests.

Review finds three things. The handler talks to the customer database directly, bypassing an access layer the team introduced specifically to keep that dependency in one place. It reimplements a retry-and-idempotency pattern that already exists two directories over under a name nobody would guess. And it takes an approach that was explicitly considered and rejected eighteen months ago, for reasons written down in a decision record that nobody reads and the assistant never saw.

None of this is dramatic. It’s a normal review. But notice what happens next.

The developer explains the abstraction in follow-up prompts. They paste in a chunk of the decision record. They point at the existing helper. The second attempt is better. The change ships. The explanation evaporates — it lived in a chat session that ends when the tab closes.

Three weeks later a teammate touches the same service and reconstructs the same explanation from scratch, slightly differently. The reviewer catches slightly different things, because reviewers are human and attention is finite. And the same two or three people who actually hold the system’s history in their heads get pulled into another review, because they’re the only ones who reliably notice.

The cost here isn’t the bad first draft. Bad first drafts are cheap now. The cost is that project knowledge gets reconstructed by hand, per person, per task, per tool, and then thrown away. Multiply that across a team and a year and it becomes one of the more expensive things an engineering organisation does without ever putting it on a roadmap.

To be fair about the landscape: modern assistants are not blind. Many index the repository, read instruction files, and follow rules the team has written down. The problem I’m describing isn’t that tools can’t see code. It’s that seeing code is not the same as knowing which of the many things visible in a repository actually govern the change in front of you — and context is not the only reason AI-generated code goes wrong.

Code shows you what exists, not what was decided

A repository is a complete record of what a system currently is and a very incomplete record of why. That gap has a specific shape, and it’s worth naming the parts.

Rejected alternatives leave no trace. The simpler design that would have been obvious to any competent engineer, and that failed for a reason nobody wants to rediscover — it isn’t in the code, because it isn’t in the code. An assistant reading the repository sees a structure that looks needlessly indirect and has every reason to propose the simpler thing. So does a new hire, for the same reason.

Deliberate compromises look like mistakes. A duplicated model in two services can be an accident or a considered decoupling choice. The code reads identically either way. “Clean this up” is correct in one case and a regression in the other, and only the reasoning distinguishes them.

Constraints outlive their explanations. A service can’t call another synchronously because of a latency budget agreed with a downstream team. A table can’t gain a column without a migration window. These are real, current, binding — and typically recorded, if at all, somewhere other than the code.

The knowledge is scattered by nature. Decision records answer why. Documentation answers how it’s meant to work. The dependency graph answers what breaks if I change this. Review history answers what we keep getting wrong. Recent commits answer what’s in flux right now. Test coverage answers how confident should I be. Each of those answers a different part of a single engineering question — “is this change safe and appropriate?” — and they live in different systems with different lifecycles. That fragmentation is the underlying problem. I want to be careful here: PACE does not connect to everywhere this knowledge might live, and any tool claiming otherwise deserves scrutiny about which sources it actually reads.

More context is not automatically better context

The obvious response — throw everything at the model, context windows are large now — is wrong in an interesting way, and understanding why is most of the design problem.

Four properties matter independently:

Relevance. A change to a payment handler is governed by a handful of decisions and constraints out of possibly hundreds. Including the rest doesn’t just waste budget; it dilutes the signal that mattered.

Freshness. A decision record from 2023 may have been superseded in 2024. A cached summary may describe a module that has since been rewritten. Stale material is worse than absent material, because it’s confidently wrong.

Authority. Not all project knowledge carries the same weight, and this is the distinction I find most important in practice. An accepted architectural decision is a commitment the team made. The code is the ground truth of what currently runs. An inferred summary — a heuristic risk score, a generated description of a module’s purpose — is a guess produced by a machine reading other machine-readable things. Those three are not interchangeable, and a system that flattens them into one undifferentiated pile of “context” will eventually let a guess override a decision.

flowchart TB
    A["Recorded facts<br/>(code, dependencies, commits, coverage)"] --> D["Assembled context<br/>for this task"]
    B["Accepted decisions<br/>(ADRs, constraints, conventions)"] --> D
    C["Inferred signals<br/>(risk scores, summaries, derived hints)"] --> D
    D --> E["Guidance the developer reads<br/>and is expected to question"]
    B -. "outranks" .-> C
    A -. "outranks" .-> C

The dotted edges are the point: an inferred signal is a hint, not a ruling. When a derived summary contradicts an accepted decision or the actual code, the derived summary should lose, and the disagreement should be visible rather than silently resolved.

Attention. Even with a large window, models weight what they’re given unevenly. A long, contradictory, partially-stale context is not a superset of a short, well-chosen one. It can be strictly worse.

So the engineering problem isn’t storage. It’s selection under a budget: given a task, decide what small subset of everything known about this project actually bears on it, and assemble that within a fixed token allowance. Getting freshness and conflict handling right at that level is genuinely hard, and I’d describe PACE’s current handling as functional rather than solved — snapshot invalidation is incomplete, and there’s no universal policy for resolving a superseded decision record against a conflicting convention file.

The individual solves this; the team doesn’t

One more failure mode deserves its own paragraph, because it’s the one that quietly determines whether AI assistance improves a team or just improves a few individuals on it.

An experienced engineer will, over a few weeks, develop a genuinely good working prompt for a codebase. It names the abstractions, mentions the constraints, warns about the traps. It’s effective. It’s also private — sitting in their notes, their shell history, their editor config.

Instruction files in the repository are the natural fix, and for many teams they’re a good one. They’re versioned, reviewed, shared. But they’re also a single flat document that everyone reads for every task, which means they get long, then get skimmed, then get stale, then get contradicted by a decision nobody went back to update. They work well up to a size and then stop scaling — not because the idea is wrong, but because “what governs this change” is a query, and a static file can’t answer a query.

That, roughly, is the line where a dedicated context service starts to be worth its cost: when the knowledge is large enough that selection matters, distributed enough that no single document holds it, and valuable enough that a handful of people keep getting interrupted to restate it.

What PACE actually is

PACE is a self-hostable developer-context service, scoped to a project. Its implemented core does five things:

1. Gathers evidence about the project. It ingests repository content and developer events, and derives code and architecture signals from them — structure, relationships, change activity, coverage, risk indicators.
2. Stores that as durable project intelligence, rather than as a per-session index that disappears.
3. Selects what matters for a specific task, rather than returning everything it knows.
4. Assembles that selection into context within a token budget, and can use it in model-assisted guidance.
5. Retains inspectable records — persisted context snapshots, guidance sessions, project guidance, and versioned artifacts with review workflows — so that what was assembled can be examined later rather than being taken on faith.

You reach it through a dashboard, a CLI, a REST API, and a VS Code extension. Those differ in maturity: the API and dashboard are the most developed, the CLI covers a useful slice, and the extension is a working prototype rather than a polished product. Model access works against Ollama, Anthropic, and OpenAI-compatible services — which is not the same as saying every coding tool you already use is integrated. It isn’t.

I sometimes describe PACE as a control plane for project context. In ordinary language: it’s the place a team configures and manages what their AI tooling knows about their project, separate from the tools themselves — one authority that clients ask, rather than each tool maintaining its own private idea of the codebase.

The diagram reads left to right. On the left are the sources: developer tools, repositories, and inputs from the team itself. In the centre, two distinct bodies of knowledge sit side by side — code evidence derived from the repository, and recorded project guidance contributed by people. The pipeline between them gathers candidate material, selects what’s relevant to the task, applies the project’s constraints, and compiles a bounded context. On the right are intended outcomes: more relevant guidance, easier onboarding, earlier visibility of risk, and artifacts that can be reviewed rather than trusted blindly. A feedback loop runs back from outcomes into project evidence, so that what happened informs what gets assembled next time.

Two labels deserve honest treatment.

“Project Bible” is the diagram’s name for the body of accepted decisions, constraints, terminology, and guidance that a team has deliberately recorded. The label is evocative and slightly misleading, so let me defuse it: it is not infallible and not automatically authoritative. It’s a maintained artifact, and like any maintained artifact it can be out of date, internally inconsistent, or simply wrong. Its value is that it’s explicit — someone chose to write it down, and someone can be pointed at it when it turns out to be stale.

The organisational-governance elements are labelled ROADMAP, and that label is accurate. Organisation-wide policy, cross-team knowledge, and team-awareness features are ambitions, not shipped capabilities. Similarly, “architecture-safe guidance” describes an intent, not a guarantee — PACE can surface a constraint that a proposed change appears to violate; it cannot promise that a change is architecturally sound. And the infrastructure boxes in the diagram indicate where things run, not evidence of comprehensive security review or enforced tenant isolation. More on that below.

Treat the whole image as a conceptual overview: it shows relationships and intent, not a runtime trace and not a completion certificate.

Persistent evidence is not perfect memory

It’s worth separating two ideas that get conflated. PACE persists project evidence: repository-derived intelligence, recorded decisions, snapshots of what was assembled for a task, guidance sessions. That’s durable and inspectable.

It does not follow you between applications, remember every conversation you’ve had with every tool, or maintain an accurate model of your unfinished intentions. First-class memory — durable task threads, promoted summaries, goals that survive across sessions — is a design direction, not a current capability. Anyone promising automatic cross-tool memory today should be asked exactly which tools, storing exactly what.

Who this is for

These are intended audiences and plausible use cases. They’re hypotheses about who benefits, not validated customer segments — PACE has no adoption data I could honestly cite.

Developers in established codebases are the everyday users. They need to know, while writing a change, which conventions apply and which decisions constrain them — not in review, when the cost of being wrong is a rewrite.

Staff engineers and architects are the people currently paying the highest tax. They are the ones repeatedly explaining why a boundary exists. The value proposition for them is leverage: write the reasoning down once in a form the tooling can select from, instead of restating it in every review.

Platform and developer-experience teams are the likeliest internal champions, because they own the question “how do we make AI-assisted development work consistently across a team?” rather than for whoever happens to be good at prompting.

Engineering managers and CTOs are the ones who decide whether this is worth hosting. Their questions are about review cycles, maintainability, onboarding time, and whether AI adoption is actually improving delivery rather than shifting effort from writing to reviewing.

New team members may get the most immediate benefit, since a context layer is essentially a queryable version of what experienced colleagues already carry around.

Regulated and security-sensitive organisations are a potential future audience with demanding prerequisites — not a current one. Enforced access isolation, privacy-aware ingestion, and production hardening are prerequisites for that setting, and PACE does not meet them today. No compliance posture is claimed.

When you don’t need this

A context service has real setup and maintenance costs: hosting it, ingesting repositories, keeping decisions and constraints current, connecting clients. Skip it if you’re working on a small or short-lived project, a codebase straightforward enough that reading it answers most questions, or a team whose documentation and existing assistant workflows already work. “We wrote a good instructions file and it’s enough” is a legitimate resting place, and probably the right one for a lot of teams.

Three situations, honestly framed

Crossing a service boundary. A developer adds a feature that needs data owned by another service. What matters: the recorded decision that established the boundary, any constraint on how the services communicate, the existing access path, and whether anyone changed that area recently. PACE can bring those into view while the change is being designed, and can produce a snapshot showing what informed it. What it can’t do: confirm the constraint is still current if nobody updated it, or judge whether this case warrants an exception. That’s an architect’s call, and it stays one.

Onboarding into a codebase with history. A new engineer meets a module whose structure looks strange. What matters: the decision that produced it, the constraint that keeps it that way, and the surrounding code relationships. PACE can surface the reasoning alongside the code so it’s discoverable rather than tribal. The limits are honest ones — if the reasoning was never recorded, no context layer conjures it, and inferred explanations of why code looks the way it does are guesses that should be labelled as such.

Planning a refactor. Before committing, you want to know what depends on the target, where coverage is thin, and what’s changed recently. PACE can assemble dependency relationships, coverage information, and change activity into one bounded picture, which is genuinely useful for sequencing work. But derived risk signals are heuristics, code analysis fidelity varies by language, and no context layer tells you whether the refactor is a good idea. Tests and review still decide that.

What this cannot promise

A short, blunt list, because the failure mode of posts like this is a limitations section that reads like modesty theatre.

• Better context does not guarantee correct code. It improves the odds that generated code fits the system. It doesn’t make the model right.
• Stale or conflicting knowledge degrades guidance. If your decision records are wrong, PACE will faithfully surface wrong decisions. Freshness and conflict resolution are ongoing engineering problems here, not solved ones.
• Architecture checks and risk signals are heuristic. They surface concerns worth a human look. They don’t enforce correctness, and they will produce both false positives and misses.
• Human review and testing remain necessary. Nothing about this shifts responsibility for a change away from the engineer making it and the reviewer approving it.
• Ingesting a repository creates obligations. Source code contains secrets, personal data, and material that shouldn’t leave a boundary. Content-level privacy controls and enforced project-level access isolation are prerequisites for sensitive use, and they are not complete in PACE today. I’ll say that plainly rather than publish details.
• It costs effort to run. A service to host, evidence to keep current, guidance to maintain. That’s a real ongoing tax, and if the knowledge burden isn’t large it won’t pay for itself.

And a few things PACE explicitly does not do, since adjacent products sometimes claim them: it is not a universal transparent proxy in front of your existing AI tools, it does not enforce organisation-wide policy, it does not provide automatic memory across tools, it does not coordinate multi-agent work, and it does not prevent conflicting concurrent changes.

How you’d know whether it’s working

If you were evaluating this idea — PACE or anything like it — these are the questions I’d want answered. They’re evaluation criteria, not results I can report.

• Does the guidance actually reference relevant project decisions, or generic best practice dressed up as project knowledge?
• Do reviewers spend less time restating conventions the team already agreed on?
• Can a new developer find the reasoning behind a surprising piece of code without asking a person?
• Are architectural concerns surfaced early enough that acting on them is cheap?
• Is the assembled context inspectable — can you see what informed a suggestion and judge whether it was the right material?
• Does the benefit exceed the cost of running the service and keeping its knowledge current?

That last one is the real test, and it’s the one most likely to come back negative for a given team. I’d rather that be answered honestly than assumed.

Back to the pull request

Return to the billing service. The version of that afternoon I’m building toward isn’t one where the assistant is smarter. It’s one where the constraint on direct database access, the existence of the retry helper, and the record of the rejected approach are available at the moment the change is being written — because the project holds them, not because the developer remembered to paste them in.

The change still needs review. The tests still need to pass. The engineer still owns it. What changes is that the review is about the substance of the feature rather than about re-teaching the system’s history for the fourth time this quarter, and the explanation the developer gave last time doesn’t have to be given again.

PACE is one attempt at that, with a working core and a good deal still unbuilt. Whether the approach is right is an open question, and I’d rather hold it open than close it with a claim I can’t support.

So here’s the question I’d genuinely like other people’s answers to: what do you find yourself explaining to your AI tools over and over — the constraint, the convention, the decision that keeps getting rediscovered — and what would it take for your project to hold that instead of you?

Nothing in that scene is dramatic. That’s rather the point. It’s just a small team doing several jobs at once, and the audience’s contributions — the whole reason the show exists — becoming one more thing to keep track of.

Studiocaster started as my attempt to make that moment less fraught. It began as a labour of love, it’s still very much an active project, and it’s now used by charities. That last part is what changed how I think about it.

The problem, in plain terms

Listener messages arrive through whatever channel the listener happens to prefer. Some people text. Some use WhatsApp. Some reply to a post on social media. From the station’s side, each of those is a separate inbox with its own notifications, its own layout, and its own way of showing you what’s new.

That fragmentation costs more than it looks like it should. Requests and dedications get missed simply because nobody was looking at the right window when they arrived. A genuinely good contribution scrolls past during a track. And every message needs a moment of judgement before it goes anywhere near a microphone — is this appropriate, is it from someone who’s been abusive before, is it what it appears to be? Making that call well is hard when the raw material is scattered across four applications and one personal phone.

Bringing it all into one place doesn’t make the work disappear. It makes the work visible, which turns out to be most of the battle.

flowchart LR
    A["SMS"] --> E["One live stream"]
    B["WhatsApp"] --> E
    C["Social channels"] --> E
    D["Other messaging apps"] --> E
    E --> F["Screen and organise"]
    F --> G["Choose what goes on air"]

The diagram makes a simple claim: channels should be inputs, not separate workflows. Where a message came from is a technical detail. What matters to the team is the single editorial decision between message received and microphone live.

Which channels it takes messages from

Being specific about this matters, because “supports social media” can mean almost anything. Studiocaster’s ingestion is built around per-provider adapters, so each source has its own small piece of code that knows how to authenticate that provider’s webhook and pull the useful fields out of its payload.

The channels with adapters in the platform today are:

Two honest caveats. The Twitter/X path is poll-based and depends on which API tier a station has access to — the adapter exists, but I’d treat it as unfinished rather than something to rely on this Saturday. And a handful of other providers are designed for but not built: YouTube live chat and comments is the one I most want, alongside Discord, Slack, TikTok and LinkedIn. They’re all gated on API access and approval rather than on the adapter itself, which is the easy part.

The reason the list can grow that way is that adapters do very little. A provider adapter authenticates the request, extracts the sender, the text, a timestamp and an ID, and hands over a normalised message. It is explicitly not allowed to implement banning, filtering, keyword matching or competitions. Every channel goes through exactly the same processing afterwards, which means a new source can’t quietly behave differently from the others.

The part with hardware in it

Not every message arrives over an API. Some stations have a studio number that’s been on posters, car stickers, the back of a mug and the bottom of every jingle for a decade, and it lives in a SIM card. They are, reasonably, not willing to give it up in order to move to a hosted provider. The number is part of the relationship with the audience; asking listeners to learn a new one costs more than the tidiness is worth.

So for those stations the ingestion point is a physical one: a GSM module attached to a Raspberry Pi, sitting in the building with the original SIM in it. Texts arrive exactly as they always have. The Pi reads them off the module, stores them locally, and pushes them up to the cloud, where they join the same pipeline as everything else — same normalisation, same moderation, same dashboard. From the producer’s side of the desk there is nothing to distinguish a message that came through a hosted SMS provider from one that came through a device on a shelf in the back room.

Storing on the Pi first is the same reasoning as keeping the raw webhook payload: the local copy is what survives a broken internet connection, and the backlog goes up when the link returns.

One of those units has been running at a charity for more than eight years and is still going. Unattended — nobody there gives it a thought, which is the correct amount of thought to give it. I can reach it remotely for the occasional bit of maintenance, and occasionally do. That’s the whole of it: eight years of Saturday evenings on a board that costs less than a decent microphone.

What Studiocaster actually does

At its centre is a live dashboard. Messages appear as they arrive, in real time, from every connected channel at once. From there the useful part is what you can do with them.

You can filter and label, so a request show can pull up requests and leave the rest for later. You can favourite the ones worth keeping, and hold back or block senders who’ve caused problems before, so that judgement doesn’t have to be made afresh every week. Messages can be claimed or assigned, which sounds like a small thing until you’ve had two people in a small team both reply to the same listener — or neither of them.

It handles competitions, where entries arrive by keyword and need collecting, tracking and drawing without someone maintaining a spreadsheet during a live show. And it lets you search back through what’s come in before, which matters more than I expected: stations get asked to find a message from last Tuesday surprisingly often.

What it isn’t, deliberately, is a replacement for your scheduling or playout system. Studiocaster is about the audience side of the desk. The music software can carry on doing what it does well.

What happens to a message

Between a listener pressing send and their text appearing on the studio screen, a fair amount happens — and most of it is the work a producer would otherwise be doing by hand.

flowchart TD
    A["Message arrives at the webhook"] --> B["Acknowledge immediately, store the raw event"]
    B --> C["Queue for processing"]
    C --> D["Normalise into a common shape"]
    D --> E["Identify the sender, or create them"]
    E --> F["Apply moderation: bans, blacklists, expletive filter"]
    F --> G["Flag priority senders and first-time contributors"]
    G --> H["Match keywords and competition entries"]
    H --> I["Save message, sender and conversation together"]
    I --> J["Push to the live dashboard"]

A few of those steps are worth pulling out.

The webhook accepts and acknowledges the message straight away, before doing any real work, and keeps a copy of the raw payload. That matters because providers give up and retry if you’re slow, and because when something does go wrong you want the original to replay rather than a lost message. Duplicates are caught by the provider’s own message ID, so a retried delivery doesn’t turn into a second entry on screen.

The actual processing then happens on a queue, off the request path. That’s where the useful automation lives: the sender is matched to their history, bans and blacklists are applied, the expletive filter runs — keeping both the original and the censored version — regular contributors are marked as priority, first-timers are flagged as first-timers, keywords are matched, and competition entries are recognised and linked to the right competition. All of it is written in a single transaction, so a message and its entry either both exist or neither does.

One detail I think is right and would defend: a message from a banned sender is still stored. It’s just marked as not for display. Deleting it would throw away the moderation history, and a station occasionally needs to show what was received, not only what was aired.

Finally the message is pushed to the dashboard over a live connection, so it appears without anyone refreshing anything. The dashboard also reconciles against the database behind the scenes, on the assumption that a live connection is an acceleration rather than a guarantee — the sort of belt-and-braces you want in something running during a broadcast.

Who it’s for

The people I picture using it are presenters, producers and station operators — the ones actually in the room while the programme is going out.

Community and charity broadcasters fit particularly well, and that’s borne out by the fact that charities are the confirmed users today. In those stations the roles blur: the person presenting may also be the person screening messages, and the person screening messages may also be on the rota to lock up afterwards. A shared workspace helps precisely because responsibilities move around. If everything lives in one place with a visible state, a volunteer picking up a shift can see where things stand rather than having to be briefed.

Beyond that there are other kinds of stations it could suit — student radio, hospital radio, small commercial outfits, anyone running phone-ins or request shows. I’d rather describe those as plausible than claim them. And I’d rather not suggest that every charity needs broadcast software; most don’t. The ones that broadcast do.

Listeners benefit indirectly, and I think that’s the honest framing. Nobody sending a dedication cares what software the station runs. They care whether their message gets noticed.

Why it still matters to me

There’s a particular shift that happens when a personal project acquires actual users. Before that, the project belongs to you: you build what interests you, you break things when you feel like it, and the only person inconvenienced is you at two in the morning.

Afterwards, someone is depending on it during a live broadcast. That’s a genuine responsibility, and it changes the work in ways I didn’t fully anticipate. Reliability stops being an abstract virtue. Small friction that I’d learned to work around becomes something I have to actually fix, because a volunteer meeting it for the first time on a Saturday evening won’t know the workaround.

That responsibility is also what makes it worth continuing. Feedback from people using it in anger has been more useful than any amount of my own speculation about what a station might want. It has repeatedly redirected what I build next.

Some of the work isn’t visible from the outside at all. A good deal of effort has gone into moving from an older application towards a more maintainable modern platform — not because rewriting is fun, but because a tool people rely on needs to be something I can still change safely in five years’ time. That’s an investment in the project’s future rather than a feature anyone will notice.

I want to be careful about what I claim. There’s been meaningful progress, and there’s plenty still in flight. Some capabilities exist in the codebase or on the roadmap without being available to everyone using it today — live polls, for instance, are something I’m working towards rather than something you can switch on. The project is evolving, and I’d rather say so than imply it’s finished.

Still going

Studiocaster remains what it started as: something I build because I want it to exist, now with the added weight of people who’d notice if it stopped working. I don’t have grand plans to announce. I have a list of things to improve, a handful of stations whose feedback shapes that list, and a fairly clear sense of what the tool is for.

If the result is that a presenter spots a dedication they’d otherwise have missed, and a listener hears their name on the radio — that’s a good enough reason to keep going.

It is late on a Thursday and an engineer has to produce a release handover before the change window opens. The explanatory part is the easy part — they know what changed, which behaviour the on-call team should watch, and which config flag is new. The tedious part is everything else. Which commit is actually deployed? Are the health endpoints returning what they should right now? Which artifacts came out of this build, and are they the ones referenced in the ticket? So the engineer opens four browser tabs and a terminal, copies values into the document by hand, and hopes nothing shifts between now and the handover call.

Two days later somebody asks whether the document still reflects reality. Nobody can answer with confidence, because the document is a photograph with no timestamp and no record of where the picture was taken.

The problem is not writing. It is transcription.

Technical documents rarely go stale because the prose was wrong. They go stale because the facts wrapped inside the prose were copied out of systems that kept moving. Release references, service health results, artifact details, file contents — all of it drifts while the surrounding explanation remains perfectly useful.

The work this creates is familiar and quietly expensive:

• Repeated checking. Before every review, somebody re-verifies the same handful of values by hand.
• Copy-and-paste updates. Fixing a stale document means visiting each source system again and pasting the new value in the right place.
• Inconsistent reports. Two engineers documenting the same release pull different fields, in different formats, from different places.
• Uncertainty. A reader cannot tell whether a value was true when it was written, true last week, or never checked at all.

Teams usually respond by writing less documentation, or by accepting that some of it is decorative. Neither is a good outcome when the document is meant to serve as evidence for a review, or as the first thing an on-call engineer reads at 3 a.m.

What “executable documentation” means here

Forge source documents are written in Markdown, the way any technical document would be. What makes them executable is that selected sections behave as reusable instructions for gathering and presenting facts, rather than as static text. Instead of pasting the current commit reference into a sentence, the author writes the sentence and marks the place where that reference should be retrieved.

When the document is generated, those sections are carried out. The narrative stays exactly as the author wrote it; the factual parts are filled in from the systems that hold the answers. Alongside the readable output, Forge produces provenance information so a reader can see where each generated fact came from.

The division of labour is the whole idea: people write the meaning and context, and connected systems supply the changing facts.

flowchart LR
    A["Human-written context"] --> C["Generate document"]
    B["Facts from source systems"] --> C
    C --> D["Readable snapshot"]
    C --> E["Provenance record"]

The diagram above is the shape of every Forge document. Two inputs meet at generation time — the explanation a person wrote, and the facts retrieved from source systems — and two things come out: a document a human can read, and a record of where its facts came from. The snapshot is what you circulate; the provenance is what you consult when someone asks how a value got there.

The documented integrations today are deliberately unglamorous categories: HTTP endpoints, Git repositories, and local files. Between them they cover much of the release-handover problem — service checks, source-control references, and information about files produced by a build.

It is worth being clear about what Forge is not. It is not an AI writing tool. It does not draft your explanation, summarise your release, or generate prose on your behalf. The writing is yours.

From authoring to generation

Forge separates the work of composing a document from the act of running it.

flowchart LR
    subgraph Authoring["Authoring and publishing"]
        A["Compose document"] --> B["Publish version"]
        R["Reusable building blocks"] --> A
    end
    subgraph Execution["User or team-controlled environment"]
        C["Generate published document"] --> D["Document snapshot and provenance"]
        S["Accessible source systems"] --> C
    end
    B --> C

Reading left to right: authoring and publishing happen in the browser, and generation happens elsewhere — on an engineer’s machine or in an automation environment the team controls. The single arrow between the two halves is a published version. That is the only thing generation consumes.

In sequence:

1. An author writes a document in Markdown and includes sections that retrieve facts rather than restating them.
2. Teams organise documents and reusable building blocks in shared libraries, so the same fact-gathering section can be reused across many documents instead of being reinvented.
3. Authors deliberately publish a version when it is ready to be generated. Drafts stay drafts.
4. A user generates the document with the command-line tool, either locally or in a team-controlled automation environment.
5. Forge retrieves the relevant facts and produces a readable snapshot together with provenance information.

Generated output stays in the environment where generation ran, by default — including when the source document came from the shared library. Authoring is collaborative; execution is local to whoever ran it.

One property matters more than any other: a snapshot reflects the moment it was generated. It is not a live dashboard and does not keep itself current. If you want a current picture, you generate again.

Why the design choices earn their keep

That last row deserves emphasis. The failure mode to avoid is not an error message; it is a document that looks complete and is not.

Where this fits

• Developers preparing release handovers — explanatory notes, a source-control reference, endpoint health results, and artifact information in one generated document rather than five tabs.
• Platform and DevOps teams documenting operational state — runbooks and environment overviews whose factual sections are gathered rather than remembered.
• Technical writers maintaining explanations wrapped around changing technical facts — the prose stays owned by the writer, and the values that keep invalidating it stop being their problem.
• Teams collecting traceable technical evidence for review — a snapshot plus provenance, generated at a known moment, in an environment the team controls.

These are applications the approach suits, not claims about existing customers or certifications.

The honest caveats

Forge moves the effort of gathering facts; it does not abolish the conditions that make facts gatherable. Source systems have to be available and reachable from wherever generation runs, access permissions have to permit the retrieval, and the output is bounded by the quality of the sources: a document faithfully reporting a misconfigured health endpoint is faithful, not correct. Provenance helps a reader trace a value to its origin — it does not vouch for that origin.

Nor is a snapshot a reproducibility guarantee. Versioning stabilises what the document asks for; if the systems answering have changed, the answers change with them, so two generations of the same version can legitimately differ.

Back to Thursday afternoon

The engineer still has to write the handover, and they should — nobody else knows why this release matters, what to watch, or which flag is new. What they no longer have to do is act as a courier between five systems and a Markdown file, then defend the freshness of numbers they typed by hand.

They write the explanation. Forge gathers the facts for that particular snapshot, records where each one came from, and stamps it with the moment it was true.

The source code may tell us exactly what the system does today, but it does not necessarily tell us what the system should do, why certain decisions were made, or whether those decisions comply with the wider organisation’s rules.

A more useful model is to think of software development as operating within three layers of organisational truth:

1. Code source of truth — what the system actually does.
2. Project bible — what the project intends, assumes, and has decided.
3. Organisation governance — what the organisation permits, requires, and standardises.

These layers overlap, but they answer fundamentally different questions.

flowchart TB
    G["Organisation Governance<br/>What are we allowed and required to do?"]
    P["Project Bible<br/>What should this project do and why?"]
    C["Code Source of Truth<br/>What does the system actually do?"]

    G --> P
    P --> C

    C -. "Implementation feedback" .-> P
    P -. "Project feedback" .-> G

The important point is that truth flows downward as constraints and intent, while information also needs to flow upward when implementation exposes assumptions, problems, or new requirements.

1. Code Source of Truth

At the lowest and most concrete level is the codebase.

The repository contains the executable reality of the system:

• application code;
• configuration;
• database migrations;
• infrastructure definitions;
• API contracts;
• automated tests;
• dependency definitions;
• build and deployment configuration.

If the documentation says that an API endpoint accepts one parameter but the deployed application accepts another, the running code ultimately determines what actually happens.

In that sense, code is the source of truth for implementation.

But this phrase is sometimes stretched too far.

Code is generally very good at answering:

What does the system currently do?

It is much less reliable at answering:

Why does it do this?

Consider a seemingly arbitrary rule:

if (failedAttempts >= 5) {
    lockAccount();
}

The code clearly tells us that five failed attempts result in an account lock.

It does not tell us whether five attempts were chosen because of:

• a security policy;
• a regulatory requirement;
• a product decision;
• a historical incident;
• a temporary workaround;
• or simply a developer’s judgement several years ago.

The implementation is authoritative about behaviour, but not necessarily about intent.

This becomes especially important when someone — human or AI — changes the code.

A developer might reasonably look at that logic and decide that ten attempts would create a better user experience. From a purely technical perspective, the change may be perfectly valid.

From an organisational perspective, it could be completely wrong.

2. The Project Bible

Between organisational policy and source code sits a layer that many projects have informally but few maintain deliberately.

I think of it as the project bible.

This is not simply conventional technical documentation. It is the authoritative body of knowledge describing what the project is supposed to be.

It may include:

• architecture principles;
• domain terminology;
• functional requirements;
• important business rules;
• design decisions;
• architectural decision records;
• integration contracts;
• security assumptions;
• data ownership;
• expected system behaviour;
• constraints and non-goals;
• accepted technical debt;
• deployment assumptions;
• conventions specific to the project.

For example, imagine an organisation building a multi-tenant SaaS platform.

The code may currently contain:

tenant_id

throughout its database queries.

The project bible should contain the more important rule behind that implementation:

All tenant-owned data must be isolated by tenant at every persistence and service boundary.

That statement survives implementation changes.

The team could move from PostgreSQL row filtering to separate schemas, separate databases, or some future storage architecture. The source code would change substantially, but the project truth would remain: tenant isolation is a fundamental system requirement.

This is what makes the project bible different from generated documentation.

Generated documentation can describe the system.

A project bible helps define the system.

It also records why

Software projects accumulate decisions that are almost invisible when looking only at the finished code.

Perhaps the team evaluated three message brokers and deliberately chose one.

Perhaps a particular service is separate because it has a very different security boundary.

Perhaps an apparently inefficient database structure exists because historical records are legally required to remain immutable.

Without project-level context, future developers can mistake deliberate design decisions for mistakes.

Worse, they may successfully “fix” them.

3. Organisation Governance

Above individual projects sits a third source of truth: the organisation itself.

An engineering team does not operate in isolation.

The organisation may have rules covering:

• approved technologies;
• cybersecurity;
• authentication;
• encryption;
• data retention;
• personally identifiable information;
• logging and auditing;
• regulatory compliance;
• infrastructure providers;
• software licensing;
• dependency management;
• accessibility;
• coding standards;
• deployment processes;
• disaster recovery;
• observability;
• source-control practices;
• change management;
• AI usage;
• architecture standards.

These rules may apply to dozens or hundreds of projects.

A project team should therefore not duplicate every organisational rule into its own documentation. Instead, the project should inherit applicable governance and document where project-specific decisions refine it.

For example:

Organisation rule:
Customer secrets must never be stored unencrypted.

Project rule:
Integration credentials are stored using the organisation's approved
secrets-management platform.

Implementation:
The application retrieves credentials through the secrets service at runtime.

These are three different statements at three different levels of authority.

They are related, but they are not interchangeable.

The Three Layers Together

A useful way of thinking about the relationship is:

A healthy project should be able to trace important behaviour through all three layers.

flowchart LR
    A["Governance<br/>Customer data must be encrypted"]
    B["Project Bible<br/>Customer records use approved encryption strategy"]
    C["Code<br/>Encryption implementation and configuration"]
    D["Tests<br/>Verify encrypted storage"]

    A --> B
    B --> C
    C --> D

This traceability becomes particularly valuable when something changes.

The Real Problem Is Divergence

The biggest danger is not missing documentation.

It is contradictory truth.

Suppose organisational governance states:

Production services must use the organisation’s central identity provider.

The project’s architecture documentation agrees.

But six months later, a developer introduces a local authentication mechanism while building a new administration service.

Now the organisation contains three versions of reality:

flowchart TB
    G["Governance<br/>Use central identity provider"]
    P["Project Bible<br/>Authentication uses central identity provider"]
    C["Code<br/>New admin service uses local authentication"]

    G -->|"aligned"| P
    P -->|"DIVERGENCE"| C

Nothing may fail technically.

The application compiles.

The tests pass.

CI is green.

The feature works perfectly.

And the implementation is still wrong.

This is one reason conventional code review alone cannot guarantee organisational correctness.

Source of Truth Is Also About Authority

Once multiple sources of truth exist, another question becomes important:

Which source wins when they disagree?

There should be a hierarchy.

As a general principle:

Organisation governance
        ↓
Project requirements and architecture
        ↓
Implementation

If code contradicts a documented project requirement, either the code needs changing or the requirement needs formally revising.

If the project bible contradicts organisational governance, either the project must change or an explicit exception needs to be approved.

What should not happen is silent divergence.

That distinction matters.

A source of truth is not authoritative because somebody wrote it in Markdown.

It is authoritative because the organisation has agreed that this is where a particular category of decision is defined.

Changes Need to Move in Both Directions

The hierarchy does not mean information only travels downward.

Sometimes implementation teaches us something.

A team may discover that a project requirement is technically impossible, unnecessarily expensive, insecure, or simply based on an incorrect assumption.

The correct response is not to quietly make the code behave differently.

Instead:

flowchart LR
    A["Requirement"]
    B["Implementation"]
    C["Problem discovered"]
    D["Review decision"]
    E["Update Project Bible"]
    F["Update Code"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

The source of truth itself changes first — or as part of the same controlled change.

The implementation then remains aligned with it.

The same principle applies between a project and organisational governance. If enough projects discover that an organisational rule no longer makes sense, perhaps the governance itself needs revision.

Truth should be controlled, but it should not be fossilised.

AI Makes This More Important

AI-assisted software development makes this distinction considerably more important.

An AI coding agent can inspect a repository and become remarkably good at understanding the local implementation.

But the repository may not contain the information required to understand the organisation.

The agent may see:

export async function saveDocument(document: Document) {
    return repository.save(document);
}

and produce a technically excellent enhancement.

What it may not know is:

• documents have a seven-year retention requirement;
• deletion must be soft deletion;
• audit records must be immutable;
• a tenant can only access documents belonging to that tenant;
• certain document categories cannot leave a particular jurisdiction.

None of those rules can safely be inferred from programming language syntax.

An AI agent therefore needs access to more than code if it is expected to make decisions rather than simply implement tightly specified instructions.

flowchart TB
    AI["Developer / AI Coding Agent"]

    G["Organisation Governance"]
    P["Project Bible"]
    C["Codebase"]

    G --> AI
    P --> AI
    C --> AI

    AI --> R["Proposed Change"]
    R --> V["Validate against all three sources"]

The more autonomous development tooling becomes, the more important context governance becomes.

Otherwise we risk producing code faster than ever while simultaneously increasing the rate at which systems drift away from their intended architecture and organisational rules.

Documentation Alone Does Not Solve It

There is another uncomfortable problem.

Most organisations already have plenty of documentation.

The problem is often discovering:

• which document is authoritative;
• whether it is current;
• whether another document supersedes it;
• who owns it;
• which projects it applies to;
• which rules are mandatory;
• whether the implementation still complies with it.

A folder containing 2,000 pages of Confluence documentation is not necessarily a source of truth.

It may simply be a large collection of information.

For something to function as organisational truth, it needs characteristics such as:

• clear ownership;
• defined authority;
• versioning;
• scope;
• review;
• traceability;
• controlled change;
• discoverability.

Otherwise developers are forced to decide which pieces of documentation they believe.

And an AI agent faces exactly the same problem, only much faster.

Source-of-Truth Validation Should Become Part of Development

This suggests that source-of-truth validation belongs inside the software development lifecycle rather than outside it.

A simplified workflow might look like this:

flowchart TD
    A["Specification / Task"]
    B["Check Organisation Governance"]
    C["Check Project Bible"]
    D["Implement Change"]
    E["Code Review"]
    F["Source-of-Truth Validation"]
    G["Testing"]
    H["Update Documentation if Required"]
    I["Commit / Deploy"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I

    F -->|"Conflict found"| C

That validation does not necessarily need to be a bureaucratic manual process.

Some rules can be automated.

A system could detect that:

• a prohibited dependency has been introduced;
• an API no longer matches its contract;
• a database entity violates a tenant-isolation rule;
• a new infrastructure resource uses an unapproved provider;
• implementation has changed while its associated architectural decision has not;
• code contradicts a project-level requirement.

Other decisions still require human judgement.

The objective is not to turn governance into a giant set of linting rules.

It is to make organisational intent visible at the point where software is being changed.

Not One Source of Truth, but a Chain of Truth

The phrase “single source of truth” remains useful, provided we apply it to the right scope.

There can be a single authoritative source for organisational policy.

There can be an authoritative project knowledge base.

There can be an authoritative source repository.

But trying to collapse all three into one thing creates a different problem.

Code should not become the organisation’s policy manual.

Corporate governance should not describe individual implementation details.

And the project bible should not attempt to reproduce every line of code.

A better model is a chain of truth:

flowchart TB
    O["ORGANISATION<br/>Principles, policies, standards and constraints"]
    P["PROJECT<br/>Requirements, architecture, decisions and intent"]
    C["CODE<br/>Actual implementation"]
    R["RUNTIME<br/>Actual behaviour in production"]

    O -->|"governs"| P
    P -->|"defines"| C
    C -->|"produces"| R

    R -. "observations" .-> C
    C -. "changes & discoveries" .-> P
    P -. "exceptions & lessons" .-> O

Each layer has a different responsibility.

Each can change.

Each needs ownership.

And the connections between them matter as much as the individual repositories of information.

When those connections are maintained, a developer can understand not only what the code does, but why it exists and what boundaries it must respect.

That becomes increasingly important as software development moves from humans writing every line themselves toward humans, AI agents, automated tooling, and organisational systems collectively producing software.

The challenge is no longer simply keeping the code correct.

It is keeping the code aligned with the project, and keeping the project aligned with the organisation.

AI is changing more than the act of writing code.

It is changing the surrounding development process as well. The specification becomes the artefact that matters, review becomes the bottleneck, and the loop between an idea and something running gets very short.

Example diagram

flowchart LR
    A[Specification] --> B[Development]
    B --> C[Review]
    C --> D[Test]
    D --> E[Refine]
    E --> A

Code still needs to be read

const posts = files
  .map(parseFrontmatter)
  .filter((post) => !post.draft)
  .sort((a, b) => b.date - a.date);

The volume of generated code goes up, so the value of code that is obvious on first reading goes up with it.

Custom HTML

Once security, identity, realtime communication, asynchronous processing, CI/CD, observability, customer support, analytics, external services, multiple hosting models and now AI are taken into account, the “application” becomes only one component in a much larger technology ecosystem.

The diagram above is an attempt to represent that ecosystem as a complete reference architecture. It is deliberately broad: not every SaaS product needs every component, but almost every mature SaaS platform will eventually encounter most of these architectural concerns in one form or another.

The application is only one layer

At the centre is the part we traditionally think of as the application:

• the front-end UI;
• backend services and APIs;
• business logic;
• product modules;
• tenant management;
• configuration and entitlements;
• administration interfaces.

That is only Layer 7 in the reference model.

Before a request even reaches that application it may already have passed through DNS, a CDN, DDoS protection, a WAF, bot protection, a load balancer, TLS termination, identity services, JWT validation, API rate limiting, request-schema validation and a reverse proxy.

After the application performs its work, it may interact with databases, caches, queues, event streams, object storage, external APIs, analytics systems, email providers, observability platforms and support systems.

Meanwhile, an entirely separate delivery system is responsible for getting the code into production safely.

A simplified view looks something like this:

flowchart LR
    U["Users & Clients"] --> E["Edge & Network Security"]
    E --> I["Identity & Access"]
    I --> A["API Security"]
    A --> C["Client / API Communication"]
    C --> W["Web Server / Reverse Proxy"]
    W --> APP["Application Services"]

    APP --> D["Data"]
    APP --> M["Messaging & Async"]
    APP --> R["Realtime Services"]
    APP --> X["External Integrations"]

    CI["CI/CD & Release Engineering"] --> APP

    APP --> O["Observability & Incident Management"]
    APP --> P["Ancillary Operational Services"]

    G["Governance & Compliance"] -.-> APP
    G -.-> D
    G -.-> CI
    G -.-> O

The important point is not the exact placement of every box. It is that the application sits inside an operating system of services around it.

Sixteen architectural layers

The reference model breaks the ecosystem into sixteen main areas.

1. Users and client access

Modern SaaS rarely means only “a website.”

Clients may include:

• web browsers;
• iOS and Android applications;
• desktop applications;
• command-line tools;
• developer and DevOps tooling;
• API and SDK consumers;
• tenant administrators;
• B2B partners and resellers.

Those clients may themselves be implemented using React, Next.js, Angular, Vue, Swift, Kotlin, Flutter, React Native, Electron, Tauri or other technologies.

Immediately, one product can have several distinct client architectures.

2. Edge and network security

Before application code sees a request, an edge layer may handle:

• DNS;
• CDN delivery;
• WAF rules;
• DDoS protection;
• bot mitigation;
• traffic filtering;
• load balancing;
• TLS certificates;
• geographic and IP restrictions.

Cloudflare, AWS, Azure, Google Cloud, Fastly and Akamai can provide overlapping parts of this layer.

This is one of the first places where modern architecture becomes less about writing code and more about composing capabilities.

3. Identity and access management

Authentication has grown far beyond a login form.

A serious SaaS platform may need:

• SSO;
• SAML;
• OpenID Connect;
• OAuth;
• MFA;
• WebAuthn;
• JWT access tokens;
• refresh tokens;
• token rotation and revocation;
• SCIM provisioning;
• RBAC;
• fine-grained permissions;
• session management;
• access auditing.

An enterprise customer may consider SSO, SCIM, RBAC and audit logs basic requirements rather than optional extras.

4. API security and request processing

An authenticated request is not automatically a safe request.

The API layer may need to perform:

• endpoint-specific rate limiting;
• JWT validation;
• JSON schema validation;
• required and allowed field checking;
• numeric and string range checking;
• query/path/header validation;
• payload-size restrictions;
• MIME-type validation;
• upload controls;
• injection protection;
• SSRF protection;
• idempotency;
• replay protection;
• correlation IDs;
• safe response handling.

This layer can involve both application code and dedicated API-security products such as Cloudflare API Shield, Kong, 42Crunch, Wallarm, Salt Security or similar platforms.

5. Client-to-API communication

REST is only one communication mechanism.

Applications increasingly combine:

• REST;
• GraphQL;
• WebSockets;
• Server-Sent Events;
• gRPC;
• gRPC-Web;
• webhooks;
• occasionally WebRTC or long polling.

A normal request/response API, a live collaboration session and an AI response being streamed token by token have very different communication characteristics.

6. Web servers and reverse proxies

There is often another layer between the network and application runtime:

• NGINX;
• Apache;
• Caddy;
• Traefik;
• IIS;
• Envoy.

These can deal with routing, caching, compression, TLS termination, static content and application hand-off.

Behind them may sit Node.js, Kestrel, Spring, Tomcat, Gunicorn, Uvicorn, Go, PHP-FPM or another runtime.

The once-simple phrase “web server” now covers several quite different responsibilities.

7. The application itself

Only now do we reach the product’s actual business services.

This may contain:

• front-end applications;
• backend services;
• BFFs for web or mobile;
• domain services;
• tenant management;
• administration;
• feature flags;
• configuration;
• subscription entitlements;
• notifications;
• business rules.

This is the part users normally perceive as “the product.”

Everything else exists partly to make this layer secure, reliable, scalable, supportable and commercially viable.

8. Realtime communication

Realtime features introduce another architectural category.

Examples include:

• WebSocket gateways;
• SSE streams;
• user presence;
• collaborative editing;
• live notifications;
• AI streaming;
• job-progress updates;
• cross-node realtime distribution.

Once an application runs on multiple server instances, realtime messaging must usually be distributed through something such as Redis, NATS or Kafka rather than relying on one process’s memory.

9. Messaging, events and asynchronous processing

Some work should not happen inside an HTTP request.

Modern platforms often rely on:

• RabbitMQ;
• SQS;
• Azure Service Bus;
• Kafka;
• Redpanda;
• Kinesis;
• NATS;
• EventBridge;
• BullMQ;
• Celery;
• Sidekiq;
• worker processes;
• schedulers;
• dead-letter queues.

Then there are the less glamorous but essential concerns:

• retries;
• backoff;
• duplicate handling;
• idempotent consumers;
• poison messages;
• event-version compatibility.

Asynchronous architecture solves one class of problems while introducing an entirely new class of operational complexity.

10. The data layer is no longer “the database”

A modern data layer may contain several specialised stores:

• PostgreSQL or MySQL for relational data;
• MongoDB or DynamoDB for document/NoSQL workloads;
• Redis for caching;
• S3 or equivalent object storage;
• OpenSearch or Elasticsearch for search;
• Snowflake, BigQuery or Redshift for analytics;
• vector databases such as pgvector, Pinecone, Weaviate, Qdrant or Milvus;
• backup and archival systems.

Data lifecycle then adds:

• retention;
• deletion;
• residency;
• legal hold;
• export;
• encryption;
• tenant isolation.

AI adds another reason to think about data architecture carefully because embeddings, semantic search and RAG knowledge stores create additional representations of information that also need governance.

11. CI/CD and release engineering

The development process itself has become part of the production architecture.

Source repositories may live in:

• GitHub;
• GitLab;
• Bitbucket;
• Azure Repos.

From there a release can pass through:

• build pipelines;
• automated tests;
• dependency scanning;
• secret scanning;
• SAST and DAST;
• container scanning;
• artifact registries;
• deployment pipelines;
• DEV, TEST, STAGING and PROD environments;
• infrastructure as code;
• database migrations;
• smoke tests;
• release gates;
• blue/green deployments;
• canary releases;
• rollback;
• release notes.

A modern deployment is not ideally “build something and copy it to a server.” It is a controlled progression of an immutable change through a chain of validation and increasingly production-like environments.

12. External integrations

Most SaaS products depend on other SaaS products.

Typical examples include:

• Stripe for payments;
• Resend, SendGrid, Postmark, Mailgun or SES for email;
• Auth0, Okta or Entra for identity;
• Salesforce or HubSpot for CRM;
• GitHub, GitLab, Jira and Slack;
• OpenAI, Anthropic or other AI providers;
• incoming and outgoing webhooks.

This creates a significant architectural reality: part of your application’s behaviour lives outside your application.

A provider outage, API change, rate limit or authentication problem can become your outage even while every service you operate is healthy.

13. Ancillary platform and operational services

This is one of the easiest parts of a SaaS architecture to overlook because these tools often do not participate directly in normal application requests.

They nevertheless form a large part of the operating ecosystem.

Email and notifications

Examples include:

• Resend;
• SendGrid;
• Mailgun;
• Postmark;
• Amazon SES;
• Twilio;
• Firebase Cloud Messaging.

Without them, features such as account verification, password recovery, notifications and operational alerts may stop working.

Engineering and operations communication

Teams may rely on:

• Slack;
• Microsoft Teams;
• Discord;
• Mattermost;
• Google Chat;
• webhook-driven channels.

These can become the nervous system connecting development, deployment, support and NOC operations.

Incident and on-call systems

Examples include:

• PagerDuty;
• Opsgenie;
• Better Stack;
• Splunk On-Call;
• Jira incident workflows.

Monitoring only tells you something is wrong. Somebody still has to be told, respond, coordinate and eventually close the incident.

Error tracking and application performance

Platforms such as:

• Sentry;
• Rollbar;
• Bugsnag;
• Datadog;
• New Relic

provide visibility into what the application is actually doing in production.

Product analytics

Services such as:

• PostHog;
• Amplitude;
• Mixpanel;
• Heap;
• Google Analytics

answer a very different question:

Is the system working technically?

becomes:

Are people actually using it the way we expected?

UX and session analytics

Tools such as:

• Hotjar;
• FullStory;
• Microsoft Clarity

can expose usability problems that logs and metrics will never reveal.

A technically healthy application can still be a terrible user experience.

Customer support and feedback

A production ecosystem may additionally contain:

• Intercom;
• Zendesk;
• Freshdesk;
• Crisp;
• Help Scout;
• Canny;
• Productboard;
• UserVoice.

Support, feedback and product-development systems form another loop around the application:

flowchart LR
    P["Product"] --> U["User"]
    U --> A["Analytics / Session Data"]
    U --> S["Support / Feedback"]

    A --> T["Product Team"]
    S --> T

    T --> B["Backlog / Roadmap"]
    B --> D["Development"]
    D --> P

The product is therefore not merely deployed and left running. It lives inside a continuous feedback system.

14. Observability and incident management

Observability itself deserves a separate architecture layer.

A mature stack may combine:

• Sentry for errors;
• Prometheus for metrics;
• Grafana for dashboards;
• ELK, Loki or Splunk for logs;
• OpenTelemetry for traces;
• uptime and synthetic monitoring;
• alerting;
• incident management;
• public status pages;
• SLO and SLA measurement.

The challenge is not merely collecting telemetry.

It is correlating it.

A single user failure might involve:

• an API trace;
• three microservices;
• a queue;
• a Redis lookup;
• a database query;
• an external payment API;
• six log streams;
• two metrics alerts.

More observability data does not automatically mean more observability.

15. Business and customer systems

Commercial SaaS architecture also contains systems that have little to do with serving an HTTP request but are essential to operating the business:

• subscriptions;
• plans;
• entitlements;
• usage metering;
• invoicing;
• tax;
• dunning;
• CRM;
• ticketing;
• knowledge bases;
• customer success;
• onboarding;
• feedback;
• business analytics.

This is where software architecture and business architecture begin to overlap.

For example, a subscription tier may ultimately influence an API request:

Authenticated user
    ↓
Tenant
    ↓
Subscription
    ↓
Entitlements
    ↓
Feature / quota
    ↓
Application behaviour

A pricing decision can therefore become an architectural concern.

16. Governance and compliance

Finally, all of the previous layers sit inside governance constraints.

These may include:

• audit logging;
• GDPR;
• SOC 2;
• ISO 27001;
• PCI-DSS;
• HIPAA where relevant;
• data residency;
• retention;
• encryption;
• secrets management;
• KMS;
• least privilege;
• access reviews;
• vulnerability management;
• disaster recovery;
• RPO and RTO;
• privacy;
• subprocessors;
• incident response.

Importantly, compliance is not a single box that can be added at the end.

Its requirements flow through the entire architecture.

Cloud makes complexity disappear — but only operationally

One useful aspect of the architecture is that the same logical capability can be implemented in very different ways.

A queue could be:

• AWS SQS;
• Azure Service Bus;
• Google Pub/Sub;
• RabbitMQ;
• NATS.

Object storage could be:

• S3;
• Azure Blob Storage;
• Google Cloud Storage;
• MinIO;
• Ceph.

A managed cloud provider may hide database replication, hardware failure, backups or load-balancer maintenance behind a service boundary.

A self-hosted system does not eliminate those concerns. It simply transfers responsibility for them back to the organisation.

This is why the architecture should be thought of in terms of capabilities first, products second.

Self-hosting changes the responsibility boundary

If an application runs on Linux, Windows Server or private infrastructure, a team may additionally own:

• OS patching;
• host firewalls;
• runtime updates;
• certificates;
• storage;
• backup;
• failover;
• monitoring;
• capacity;
• network configuration;
• vulnerability remediation.

A managed PostgreSQL service and a PostgreSQL server running on a VM may provide similar database functionality to the application, but they represent very different operational responsibilities.

This distinction matters when judging the complexity of a system.

Then AI arrives at every layer

AI is unusual because it is not simply another isolated architecture component.

It can potentially augment almost every existing layer.

Examples include:

And then AI itself introduces another operating concern:

• model selection;
• prompt management;
• model gateways;
• vector stores;
• evaluations;
• guardrails;
• token usage;
• inference costs;
• model monitoring;
• model versioning;
• agent permissions;
• human approval gates.

So AI does not simplify the architecture automatically. In many cases it adds another cross-cutting architectural dimension.

Agentic systems make boundaries more important

A conventional AI assistant may produce text.

An agent can potentially do something.

That changes the risk profile dramatically.

An agent involved in deployment, for example, may need:

• credentials;
• API access;
• infrastructure visibility;
• permission to modify a system;
• monitoring feedback;
• rollback ability.

A useful agentic deployment model therefore looks less like:

AI → Production

and more like:

AI recommendation
    ↓
Policy evaluation
    ↓
Approval gate
    ↓
Restricted action
    ↓
Verification
    ↓
Audit trail
    ↓
Rollback if required

The smarter the automation becomes, the more important identity, observability, permissions and governance become around it.

The real complexity is interaction

A diagram with this many boxes can make the problem appear to be the number of technologies.

That is not quite the hardest part.

The harder problem is the number of interactions between them.

Consider something as ordinary as signing up a new customer.

A single workflow might involve:

1. Cloudflare accepting the request.
2. A WAF allowing it.
3. The API gateway routing it.
4. Request validation accepting the payload.
5. The application creating the user.
6. The database storing the account.
7. A tenant being provisioned.
8. An identity token being created.
9. A background job being queued.
10. Resend or SES sending verification mail.
11. PostHog recording the signup event.
12. Sentry recording an error if anything fails.
13. Prometheus incrementing a metric.
14. Grafana displaying that metric.
15. Slack receiving an operational alert if failure rates rise.
16. A support platform receiving a ticket if the customer cannot proceed.

Nothing about that workflow is individually extraordinary.

The complexity emerges from having to make all of it behave as one system.

Vendor sprawl creates its own architecture

There is also a point where every solved problem creates another external dependency.

A team can easily end up with:

• Cloudflare;
• AWS;
• GitHub;
• Sentry;
• Grafana;
• Prometheus;
• PostHog;
• Hotjar;
• Resend;
• Stripe;
• Slack;
• PagerDuty;
• Zendesk;
• Auth0;
• OpenAI.

Each service may be an excellent choice.

Collectively they create questions around:

• authentication;
• secrets;
• billing;
• data residency;
• access control;
• vendor outages;
• API limits;
• ownership;
• auditability;
• configuration;
• offboarding;
• cost.

That is why adding a SaaS service is still an architectural decision even when it takes five minutes to install its SDK.

Mature architecture is not the architecture with the most boxes

The reference diagram should not be interpreted as a checklist where every empty box is a failure.

A small application may have absolutely no need for Kafka, Kubernetes, SCIM, a vector database or a multi-region failover architecture.

Adding them “because enterprise systems have them” can make a platform worse.

Architecture should instead answer:

What capability does this system actually require, and what is the simplest reliable way of providing it?

Sometimes the correct answer is Kafka.

Sometimes it is RabbitMQ.

Sometimes it is a Redis-backed queue.

Sometimes it is simply: we do not need asynchronous messaging yet.

The same applies across the diagram.

The modern architect’s job is increasingly one of composition

There was a time when a large part of software architecture meant deciding how application code itself should be structured.

That remains important, but a modern SaaS architect must increasingly reason about a wider system:

• which capabilities belong inside the application;
• which belong at the edge;
• which should be managed cloud services;
• which should be external SaaS providers;
• which should be self-hosted;
• how identity propagates between them;
• how failures propagate between them;
• where data is allowed to travel;
• how the whole system is observed;
• how it is deployed;
• how it is supported;
• where AI can safely participate.

The architecture is no longer merely the codebase.

It is the ecosystem of technologies, services, policies, people and operational processes required to keep that code useful in production.

And that is perhaps the most striking thing about looking at the complete diagram: the little box marked Application Layer is important, but it is surrounded by an enormous amount of machinery whose job is to make that application dependable enough for somebody else to trust.

There is no database here, no CMS, and no admin interface. Publishing works like this:

1. Add a Markdown file to blog/.
2. Run npm run build.
3. Serve dist/.

The filename becomes the URL. blog/hello-ikoonman.md is published at /blog/hello-ikoonman/, unless the frontmatter overrides the slug.

Why keep it this small

Every feature added to a publishing tool is a feature that has to keep working for as long as the writing does. Markdown files outlive engines, so the engine should be replaceable in an afternoon.

The blog exists to publish ideas, not to become another software platform.

What the build does

flowchart TD
    Scan[Scan blog/] --> Parse[Parse frontmatter]
    Parse --> Skip[Skip drafts]
    Skip --> Render[Markdown to HTML]
    Render --> Pages[Write post pages]
    Pages --> Index[Build index and feed]
    Index --> Assets[Copy public assets]

Images live in public/ and are referenced from a post with a normal absolute path, so nothing about them is special either.