Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions docs/mde/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,18 @@ reviewer can read without an Overleaf account.

One directory per deadline, named after the course's own task numbering.

| Directory | Deliverable | Overleaf project | State |
|---|---|---|---|
| [`task-0-proposal/`](task-0-proposal/) | Task 0 — project description, the proposal that must be approved before work starts | `6aa2ba0c3920baa59ec20901` | re-mirrored 2026-09-14, after the simplification in #102 |
| `task-1-metamodelling/` | Task 1 — domain analysis and modelling decisions for the two metamodels, **Project Intent** (source) and **Resolved Deployment** (target), their diagrams and example models | — | not started |
| `task-2-transformations/` | Task 2 — the model-to-model transformation from **Project Intent** (resolved against the Platform document) to **Resolved Deployment**, its rules and limitations, evidence it runs | — | not started |
| `task-3-code-generation/` | Task 3 — the model-to-text transformation from **Resolved Deployment** to the Deliverable Set, the generated code, evidence it loads | — | not started |
| Directory | Due | Deliverable | Overleaf project | State |
|---|---|---|---|---|
| [`task-0-proposal/`](task-0-proposal/) | approved | Task 0 — project description, the proposal that must be approved before work starts | `6aa2ba0c3920baa59ec20901` | re-mirrored 2026-09-16, after the delivery and output-layout corrections in #56 |
| [`task-1-metamodelling/`](task-1-metamodelling/) | 2026-09-25 | Task 1 — domain analysis and modelling decisions for the two metamodels, **Project Intent** (source) and **Resolved Deployment** (target), their diagrams and example models | `6aaa9f1d3920baa59ec267f7` | drafted; both metamodels exist as Ecore under [`emf/bundles/metamodel/model/`](../../emf/bundles/metamodel/model/) |
| `task-2-transformations/` | 2026-10-16 | Task 2 — the model-to-model transformation from **Project Intent** (resolved against the Platform document) to **Resolved Deployment**, its rules and limitations, evidence it runs | — | not started |
| `task-3-code-generation/` | 2026-10-30 | Task 3 — the model-to-text transformation from **Resolved Deployment** to the Deliverable Set, the generated code, evidence it loads | — | not started |

Each task delivers an EMF artefact, and the table above says which directory
documents it. What the artefact *is* lives in
[`emf/docs/architecture.md`](../../emf/docs/architecture.md#modules), whose
module table carries the same task numbering, so the two are read together and
neither restates the other.

Add a new report as a sibling directory with the same internal shape, and fill
in its row above when its Overleaf project exists.
Expand Down
38 changes: 25 additions & 13 deletions docs/mde/task-0-proposal/Sections/02-solution.tex
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,33 @@ \section{Solution}
The project objective is to define this abstract model and the transformations
that turn it into a complete set of deployment YAML and JSON files.

For each release, CI gives the generator three inputs: the Project Intent
model, per-process environment files and an image lock that maps image names
to pinned digests. It also receives versioned platform data, including naming
and label rules, defaults, ingress and storage classes, the alert catalogue
and cluster capabilities. The generator uses only these inputs. It does not
read live cluster state or access secret values.
For each release the generator is given a closed set of inputs, every one of
them carried by digest: each project's own model with its per-process
environment files, one platform document stating what the estate offers, a
contract publishing what each machine can hold, an image lock mapping image
names to pinned digests, and a snapshot of the few cluster facts nothing else
can supply, such as which machine already holds a volume. The generator reads
these and nothing else. It does not read live cluster state and it does not
access secret values.

A model-to-model transformation turns these inputs into a \emph{Resolved
Deployment}. This complete, non-text model contains exact resource names,
namespaces, paths, image digests, replicas, resources, probes, ports, addresses,
policy peers, routes, secret references and monitoring rules. Renderers
only turn this model into files and make no deployment decisions.
policy peers, routes, secret references and monitor targets. Renderers only
turn this model into files and make no deployment decisions.

The model-to-text step generates a \emph{Deliverable Set} for each application.
It contains a \texttt{kustomization.yaml}, Kubernetes YAML files and policy JSON
files. After validation, release CI applies the Kubernetes resources with
\texttt{kubectl apply -k}. Platform facts come from one central, versioned
source, so every repository uses the same platform definition.
The model-to-text step generates one \emph{Deliverable Set} for the estate:
Kubernetes YAML, policy JSON and the index files that group them, laid out per
project and application by a plan the resolved model carries, so every file's
path is a decision recorded in the model rather than one a generator makes
while writing. Six generators produce it, each run once over the whole
composed input rather than once per application, which is what lets a value
one application derives from another be computed in one place.

How that set reaches a cluster is deliberately outside this project. The model
states what should be true and what must be applied before what; whether a
pipeline applies it directly or a cluster-side reconciler consumes the
pipeline's published output is a separate decision, and the specification is
written so that either can be chosen without changing it. Platform facts come
from one central, versioned source, so every repository resolves against the
same platform definition.
13 changes: 8 additions & 5 deletions docs/mde/task-0-proposal/Sections/04-generated-code.tex
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
\section{Generated Code}
\label{sec:generatedcode}

The generator creates one versioned Deliverable Set per application.
Table~\ref{tab:generated_resources} lists its resources and how they are derived.
The generators create one versioned Deliverable Set for the estate, laid out
per project and application by the path plan the resolved model carries.
Table~\ref{tab:generated_resources} lists its resources and how they are
derived.

\begin{table}[!htbp]
\centering
Expand Down Expand Up @@ -30,7 +32,8 @@ \section{Generated Code}
\end{table}

The transformation computes limits, startup probes, route precedence and policy
peers. For \texttt{auth}, about 90 source lines produce ten files with about 890
peers. For \texttt{auth}, 96 declared lines produce eleven files of about 620
lines. The repository contains hand-written expected files, which are used to
check the generated result. CI receives one Kustomize entry point for the
complete bundle.
check the generated result. The tree carries one index entry point at its root,
so the whole estate is applied through a single reference rather than one per
application.
Binary file modified docs/mde/task-0-proposal/main.pdf
Binary file not shown.
Loading