Where you are

This is the foundation volume. Nothing gets served, no model gets deployed, no RAG pipeline gets built. What you get instead is the thing those all depend on: a clear problem statement, a reasoned architecture, and a running Kubernetes cluster that the next three volumes stand on.

Skip this volume and everything later reads as a list of tools. Read it and everything later reads as a system.

Volume 1 Platform Foundations

There is a temptation, when you start a project like this, to open a terminal immediately. Pull a model, run a container, get a token stream on screen, feel productive.

I know the temptation because I have given in to it before, on other projects, and I know exactly how it ends. Three days later you have four services running, no idea which one owns which responsibility, no way to rebuild any of it, and a growing suspicion that you built a demo rather than a platform.

So Volume 1 does the unglamorous work first.

The three questions this volume answers

1. Why does this need to be a platform at all? Not every problem deserves a platform. This one does, and I want to prove it rather than assume it.

2. What are the layers, and what is each one responsible for? A component list is not an architecture. Responsibilities and boundaries are.

3. What am I actually running it on? With the resource ledger and the honest list of what is real versus collapsed.

The shape of the problem

Let me set the scene the way it actually happens.

A team builds an LLM feature. It works. Leadership likes it. Then a second team builds one, and a third. Now you have three model servers, three ways of handling API keys, three retrieval implementations with three chunking strategies, and zero shared visibility into what any of it costs.

Nobody did anything wrong. Each team solved their own problem competently. The failure is structural, and structural failures need structural answers.

Preparing diagram

The full argument, including when a platform is genuinely the wrong answer, is in why AI needs a platform.

The architecture in one breath

Six layers, each with one job. If a component cannot be placed cleanly in exactly one layer, that is a signal the design is confused, and I treat it as a bug.

Layer	Its one job	Main pieces
Experience	Let a human or a machine express intent, and prove who they are	UI, REST API, CLI, Keycloak
Control plane	Validate intent and turn it into Kubernetes objects and platform state	Python, FastAPI, Pydantic, Kubernetes SDK, PostgreSQL
AI platform	Actually serve models and retrieve knowledge	LiteLLM, vLLM, KServe, RAG pipeline, Qdrant, MLflow
Execution	Run workloads with isolation, scheduling, and scaling	Kubernetes namespaces, RBAC, NetworkPolicy, quotas, storage
Compute	Provide CPU, memory, and eventually GPU	K3s nodes on Multipass VMs, GPU nodes by design
Day two	Keep it observable, secure, affordable, and survivable	Prometheus, Grafana, Loki, OpenTelemetry, Langfuse, OPA, Trivy, Falco, Terraform, Helm, Argo CD, GitLab CI

Read the layers as a contract, not a stack diagram

The useful question is never "what is above what". It is "what may call what, and what must never know about what".

The control plane may create Kubernetes objects. It must never talk to a GPU. The RAG pipeline may query Qdrant. It must never decide who a user is. Those restrictions are what keep the system debuggable at 3am, and I go through every one of them in the reference architecture.

What I am running this on

Real virtual machines, real K3s, one laptop, no GPU.

Preparing diagram

The hardware truth, again, because it shapes this whole volume

No GPU. Small instruct models on CPU: Qwen2.5 0.5B and 1.5B Instruct, TinyLlama 1.1B, and small embedding models such as all-MiniLM-L6-v2.

The cluster therefore validates correctness, isolation, wiring, scheduling behaviour, observability coverage and failure handling. It does not validate throughput. Every GPU specific piece is written into the manifests and dashboards as configuration so the arrival of hardware is a values change, not a redesign.

I keep a deviation register in the lab on k3smp listing every gap between the lab and production, with the production equivalent written next to it. That register is what stops a lab from quietly becoming a lie you believe.

Why k3smp and not the easy options

I had three reasonable choices and picked the slowest one on purpose.

Option	Speed	Why I did not choose it
kind or k3d	Seconds	Nodes are containers sharing one kernel. Node loss, node pressure, and real scheduling constraints are simulated at best. Excellent tools, wrong tool here
A managed cloud cluster	Minutes	Realistic, and it bills me every hour whether I am learning or asleep. GPU nodes would end this project financially in a week
k3smp	Several minutes	This one. Real Multipass VMs, real kernels, real node boundaries, free, and disposable

Prior art, so this is not a first attempt

k3smp is my own tool, and AIForge is not its first serious workload. The APM project already used it to run a full SigNoz deployment with OpenTelemetry collectors across a k3s cluster.

That matters here for a practical reason: the cluster bootstrap path, the storage class behaviour, the NodePort access pattern, and the telemetry wiring were all already proven on this exact tooling before AIForge existed. Volume 4 reuses those lessons directly.

How this volume is organised

Three documents, in reading order.

#	Document	What you have when you finish it
1	Why AI needs a platform	The full gap between a prototype and a production AI system, the seven failure modes teams hit, the honest case against building a platform, and the scope AIForge commits to
2	The reference architecture	Every layer, every component, what each one is responsible for, the call rules between them, the request path end to end, and the alternatives I rejected
3	The lab on k3smp	A running K3s cluster, the resource budget that proves it fits, namespaces and quotas in place, the CPU model choice, and the deviation register

The gate that ends this volume

Documents being written is not the same as a volume being finished. Here is what has to be true on my machine.

k3smp builds the cluster from an empty state with one command, no manual steps
Destroy and rebuild reproduces the same cluster, proving it is disposable rather than precious
All nodes report Ready, and I can name what each node is for
The whole lab fits inside the documented RAM and disk budget, verified rather than hoped

The last tab is the one that counts

The first three are checklists. Checklists are easy to satisfy and easy to fake.

If I finish this volume and nothing I assumed turned out to be wrong, I should be suspicious rather than pleased. It almost certainly means I wrote the document to match my plan instead of letting the cluster argue back.