@opengroundplan/core 0.1.1

package/templates/architectures/mvc-mvvm/files/docs/architecture/mvc-mvvm.python.md

@@ -0,0 +1,69 @@
+# Separated Presentation (MVC) — Python
+
+{{ solutionName | title }} splits the request path three ways. A controller decides *what
+happens*, a model holds *what is true*, a view decides *how it looks*. This is Django's MTV
+under its usual names.
+
+```
+src/{{ solutionName | snake }}/
+  models/
+    {{ firstScreen | snake }}.py        # domain data — imports nothing above it
+    repository.py                       # the ONLY place data is fetched
+  views/
+    {{ firstScreen | snake }}_view.py   # model -> template context; pure
+  controllers/
+    {{ firstScreen | snake }}_controller.py   # the only layer that knows the web framework
+.importlinter                           # the contracts
+tests/
+  test_presentation_boundaries.py       # runs them under pytest too
+```
+
+Django users: `views.py` in a Django app is the *controller* in this vocabulary, and the
+template is the view. The folder names here are the classical ones so the boundary rules read
+the way the pattern states them.
+
+## The one rule that matters
+
+> **A view may not contain business logic, and a model may not import a view.**
+
+Direction is **controllers → views → models**, and never the other way. Two corollaries that
+are where this pattern actually rots:
+
+- **A view never fetches.** If a template or a presenter has to go get something, the
+  controller failed to hand it over. `views` importing `models.repository` fails the build.
+- **A model never formats.** Currency symbols, date formats, and empty-state copy are the
+  view's business. Rules about what is valid or what something costs are the model's.
+
+## What fails the build
+
+```
+lint-imports          # or: pytest tests/test_presentation_boundaries.py
+```
+
+`.importlinter` declares two contracts:
+
+| Contract | Fires when |
+|---|---|
+| `presentation-layers` (layers) | a model imports views or controllers; a view imports controllers |
+| `views-never-fetch` (forbidden) | anything under `views/` imports `models.repository` |
+
+The package must be importable first — run `uv sync` (or `pip install -e .`). The pytest wrapper
+exists so CI fails on a violation whether it calls the linter directly or just runs the suite.
+
+## What is not enforced mechanically
+
+**import-linter checks direction, not content.** Two things it cannot see:
+
+- Business logic written *inline* in a view module or a template — a discount calculated in a
+  Jinja expression imports nothing, so no contract fires. Review for it.
+- A controller that skips the model and does domain work itself. The layers contract permits
+  `controllers → views`, so a fat controller is legal here.
+
+If either becomes a real problem in this repo, the cheapest fix is to make the seam importable
+(put the rule in `models/`) so the linter has something to see.
+
+## References
+
+- [Fowler — GUI Architectures](https://martinfowler.com/eaaDev/uiArchs.html)
+- [Django — FAQ: is Django an MVC framework?](https://docs.djangoproject.com/en/stable/faq/general/)
+- [Herberto Graça — MVC and its variants](https://herbertograca.com/2017/08/17/mvc-and-its-variants/)

package/templates/architectures/mvc-mvvm/files/docs/architecture/mvc-mvvm.typescript.md

@@ -0,0 +1,85 @@
+# Separated Presentation (MVVM) — TypeScript / React
+
+{{ solutionName | title }} keeps every screen in two halves: a **hook that is the ViewModel**,
+and a **component that only renders**. That is the modern React spelling of MVVM — the hook's
+return value is the binding, `useState` is the change notification.
+
+```
+src/
+  models/
+    index.ts                  # plain data + pure functions; no React, no DOM
+  viewmodels/
+    index.ts                  # the ViewModel<TState, TCommands> contract
+    use-{{ firstScreen | kebab }}.ts        # all state, effects, handlers for one screen
+  views/
+    {{ firstScreen | kebab }}.view.tsx      # calls the hook, renders its state
+scripts/
+  check-mvvm-boundaries.mjs   # the gate
+```
+
+The shape:
+
+```ts
+// viewmodels/use-home.ts — the ViewModel
+export function useHome(): ViewModel<HomeState, HomeCommands> {
+  const [items, setItems] = useState<string[]>([]);
+  useEffect(() => { load().then(setItems); }, []);
+  return { state: { items, isEmpty: items.length === 0 }, commands: { reload } };
+}
+
+// views/home.view.tsx — the View
+export function HomeView() {
+  const { state, commands } = useHome();
+  return state.isEmpty ? <Empty /> : <List items={state.items} onReload={commands.reload} />;
+}
+```
+
+## The one rule that matters
+
+> **A view may not contain business logic, and a model may not import a view.**
+
+Concretely, in this layout: **a component under `views/` owns no state and performs no
+effects.** If a `.view.tsx` file calls `useState`, it has taken on presentation state that
+belongs in the hook, and the screen has stopped being testable without rendering. Direction is
+**views → viewmodels → models**, one way.
+
+The payoff is the reason to accept the extra file: `useHome` is testable with a hook renderer
+and no DOM assertions, and `HomeView` becomes a snapshot of pure props. The cost is real —
+a trivial screen gets a hook that is pure plumbing. Don't split a screen that has no state.
+
+## What fails the build
+
+```
+npm run check:mvvm        # also wired as pretest, so `npm test` fails too
+```
+
+`scripts/check-mvvm-boundaries.mjs` has no dependencies and reads specifiers as written, so it
+runs before `install` and is immune to bundler resolution quirks. It fails on:
+
+| Rule | Fires when |
+|---|---|
+| direction | `models/` imports `viewmodels/` or `views/`; `viewmodels/` imports `views/` |
+| no-logic | a file under `views/` calls `useState`, `useReducer`, `useEffect`, `useLayoutEffect`, `useSyncExternalStore`, or `fetch` |
+| binding | a view *value*-imports from `models/` — bypassing its view model (`import type` is allowed) |
+| no-markup | a `.tsx`/`.jsx` file sits under `viewmodels/` or `models/` |
+
+Run `node scripts/check-mvvm-boundaries.mjs --self-test` to prove the rules still fire. Roots
+and the forbidden-call list are overridable per repo via `MVVM_MODELS_DIR`,
+`MVVM_VIEWMODELS_DIR`, `MVVM_VIEWS_DIR`, `MVVM_EXTENSIONS`, and `MVVM_VIEW_FORBIDDEN_CALLS`.
+
+Under pnpm, the `pretest` hook needs `enable-pre-post-scripts=true` in `.npmrc`.
+
+## What is not enforced mechanically
+
+- **Logic written inline in JSX.** A ternary computing a discount inside the returned markup
+  imports nothing and calls no hook, so nothing fires. That is the failure mode to watch for in
+  review — if a `.view.tsx` file has a conditional you have to think about, it belongs in the
+  hook's state.
+- **A fat view model.** Nothing stops a hook from holding domain rules that belong in
+  `models/`. The signal is a hook you cannot describe without saying "and then it decides".
+
+## References
+
+- [Fowler — GUI Architectures](https://martinfowler.com/eaaDev/uiArchs.html) (Presentation Model)
+- [Microsoft Learn — Model-View-ViewModel (MVVM)](https://learn.microsoft.com/en-us/dotnet/architecture/maui/mvvm)
+- [React — Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks)

package/templates/architectures/mvc-mvvm/files/scripts/check-mvvm-boundaries.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/**
+ * Separated-presentation boundary gate.
+ *
+ *   direction    models never import viewmodels or views; viewmodels never import views
+ *   no-logic     a view holds no state, no effects, and no data access
+ *   binding      a view binds to its view model; it may name model TYPES, not model behaviour
+ *   no-markup    viewmodels and models contain no JSX, because they must be testable headless
+ *
+ * Zero dependencies on purpose: the bases disagree on linter (ESLint vs Biome), so this has to
+ * work without editing whichever config the base already owns. `--self-test` proves the rules
+ * still fire. Reference: https://martinfowler.com/eaaDev/uiArchs.html
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+/** The only place these are written. Environment overrides them per repo. */
+const defaults = {
+  modelsDir: 'src/models',
+  viewModelsDir: 'src/viewmodels',
+  viewsDir: 'src/views',
+  extensions: '.ts,.tsx,.mts,.cts,.js,.jsx,.mjs,.cjs',
+  /** Calls that make a component own state, effects, or I/O — the view model's job. */
+  viewForbiddenCalls: 'useState,useReducer,useEffect,useLayoutEffect,useSyncExternalStore,fetch',
+};
+
+const toPosix = (value) => value.split(path.sep).join('/');
+
+const dirs = {
+  models: toPosix(process.env.MVVM_MODELS_DIR || defaults.modelsDir),
+  viewModels: toPosix(process.env.MVVM_VIEWMODELS_DIR || defaults.viewModelsDir),
+  views: toPosix(process.env.MVVM_VIEWS_DIR || defaults.viewsDir),
+};
+
+const extensions = new Set(
+  (process.env.MVVM_EXTENSIONS || defaults.extensions).split(',').map((e) => e.trim()),
+);
+
+const forbiddenCalls = (process.env.MVVM_VIEW_FORBIDDEN_CALLS || defaults.viewForbiddenCalls)
+  .split(',')
+  .map((name) => name.trim())
+  .filter(Boolean);
+
+const LABELS = { models: 'model', viewModels: 'view model', views: 'view' };
+
+/** Directional bans. Every one of these is an inverted dependency, not a style preference. */
+const FORBIDDEN_IMPORTS = [
+  { from: 'models', to: 'viewModels', why: 'a model must not know what presents it' },
+  { from: 'models', to: 'views', why: 'a model must not import a view' },
+  { from: 'viewModels', to: 'views', why: 'the view model is the half you test without a UI' },
+];
+
+/** A view may name model types; pulling model behaviour means it bypassed its view model. */
+const VALUE_IMPORT_BANS = [
+  { from: 'views', to: 'models', why: 'the view binds to its view model, not to the model' },
+];
+
+/* ── source scanning ────────────────────────────────────────────────────────── */
+
+/** Comments quote import syntax and hook names as documentation; scanning them reports fiction. */
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+
+// Bounded and lazy so an unterminated clause cannot swallow the rest of the file.
+const STATIC_IMPORT = /\b(?:import|export)\s+([\s\S]{0,400}?)\bfrom\s*['"]([^'"]+)['"]/g;
+const VALUE_ONLY_IMPORT = [
+  /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\bimport\s+['"]([^'"]+)['"]/g,
+];
+
+/** `import type X` and `import { type A, type B }` erase at compile time — no runtime edge. */
+function isTypeOnly(clause) {
+  const trimmed = clause.trim();
+  if (trimmed.startsWith('type ')) return true;
+
+  const braces = trimmed.match(/\{([^}]*)\}/);
+  if (!braces) return false;
+  const bindings = braces[1].split(',').map((b) => b.trim()).filter(Boolean);
+  return bindings.length > 0 && bindings.every((b) => b.startsWith('type '));
+}
+
+function importsIn(source) {
+  const found = [];
+  const code = stripComments(source);
+
+  for (const match of code.matchAll(STATIC_IMPORT)) {
+    found.push({ specifier: match[2], typeOnly: isTypeOnly(match[1]) });
+  }
+  for (const pattern of VALUE_ONLY_IMPORT) {
+    for (const match of code.matchAll(pattern)) found.push({ specifier: match[1], typeOnly: false });
+  }
+  return found;
+}
+
+function callsIn(source) {
+  const code = stripComments(source);
+  return forbiddenCalls.filter((name) => new RegExp(`\\b${name}\\s*\\(`).test(code));
+}
+
+/* ── layer resolution ───────────────────────────────────────────────────────── */
+
+/** The last segment of each root, as it appears inside alias imports like `@/viewmodels/x`. */
+const segments = Object.fromEntries(
+  Object.entries(dirs).map(([layer, dir]) => [layer, dir.split('/').filter(Boolean).at(-1)]),
+);
+
+function layerOfPath(posixPath) {
+  for (const [layer, dir] of Object.entries(dirs)) {
+    if (posixPath === dir || posixPath.startsWith(`${dir}/`)) return layer;
+  }
+  return null;
+}
+
+/** Alias and package specifiers carry no repo path, so match on the root's own segment. */
+function layerOfSpecifier(specifier, fromFile) {
+  const target = toPosix(specifier);
+  if (target.startsWith('.')) {
+    return layerOfPath(path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), target)));
+  }
+  const parts = target.split('/');
+  for (const [layer, segment] of Object.entries(segments)) {
+    if (parts.includes(segment)) return layer;
+  }
+  return null;
+}
+
+/* ── the rules ──────────────────────────────────────────────────────────────── */
+
+/** Every rule runs here, so `--self-test` exercises exactly what the walk exercises. */
+export function inspect(file, source) {
+  const owner = layerOfPath(toPosix(file));
+  if (owner === null) return [];
+  const violations = [];
+
+  if (owner !== 'views' && /\.[jt]sx$/.test(file)) {
+    violations.push(`${file}: JSX in the ${LABELS[owner]} layer — markup belongs in ${dirs.views}/`);
+  }
+
+  for (const { specifier, typeOnly } of importsIn(source)) {
+    const target = layerOfSpecifier(specifier, toPosix(file));
+    if (target === null || target === owner) continue;
+
+    const banned = FORBIDDEN_IMPORTS.find((r) => r.from === owner && r.to === target);
+    if (banned) {
+      violations.push(
+        `${file}: ${LABELS[owner]} imports ${LABELS[target]} "${specifier}" — ${banned.why}`,
+      );
+      continue;
+    }
+
+    const valueBan = VALUE_IMPORT_BANS.find((r) => r.from === owner && r.to === target);
+    if (valueBan && !typeOnly) {
+      violations.push(
+        `${file}: ${LABELS[owner]} value-imports ${LABELS[target]} "${specifier}" — ` +
+          `${valueBan.why} (use \`import type\` if you only need the shape)`,
+      );
+    }
+  }
+
+  if (owner === 'views') {
+    for (const call of callsIn(source)) {
+      violations.push(
+        `${file}: view calls ${call}() — state, effects, and I/O live in the view-model hook`,
+      );
+    }
+  }
+
+  return violations;
+}
+
+/* ── walk ───────────────────────────────────────────────────────────────────── */
+
+async function listFiles(dir) {
+  const found = [];
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+
+  for (const entry of entries) {
+    const child = `${dir}/${entry.name}`;
+    if (entry.isDirectory()) found.push(...(await listFiles(child)));
+    else if (extensions.has(path.extname(entry.name))) found.push(child);
+  }
+  return found;
+}
+
+async function findViolations() {
+  const violations = [];
+  for (const dir of Object.values(dirs)) {
+    for (const file of await listFiles(dir)) {
+      violations.push(...inspect(file, await readFile(file, 'utf8')));
+    }
+  }
+  return violations;
+}
+
+/* ── entry point ────────────────────────────────────────────────────────────── */
+
+/** Guards the guard: a checker that silently stops firing is worse than none. */
+function selfTest() {
+  const cases = [
+    [`${dirs.viewModels}/use-home.ts`, "import { HomeView } from '../views/home.view';", true],
+    [`${dirs.models}/home.ts`, "import { useHome } from '@/viewmodels/use-home';", true],
+    [`${dirs.views}/home.view.tsx`, 'const [n, set] = useState(0);', true],
+    [`${dirs.views}/home.view.tsx`, "import { loadHome } from '../models/home';", true],
+    [`${dirs.viewModels}/use-home.tsx`, 'export const x = 1;', true],
+    [`${dirs.views}/home.view.tsx`, "import type { Home } from '../models/home';", false],
+    [`${dirs.views}/home.view.tsx`, "import { useHome } from '../viewmodels/use-home';", false],
+    [`${dirs.models}/home.ts`, '// useState() named in a comment\nexport const x = 1;', false],
+  ];
+
+  const failures = cases
+    .filter(([file, source, shouldFire]) => inspect(file, source).length > 0 !== shouldFire)
+    .map(([file, source, shouldFire]) => `  ${shouldFire ? 'missed' : 'false positive'}: ${file} — ${source}`);
+
+  if (failures.length > 0) {
+    console.error(`Self-test failed (${failures.length}):\n${failures.join('\n')}`);
+    process.exit(1);
+  }
+  console.log(`Self-test passed: ${cases.length} cases.`);
+}
+
+if (process.argv.includes('--self-test')) {
+  selfTest();
+} else {
+  const violations = await findViolations();
+  if (violations.length > 0) {
+    console.error(`Presentation boundary violations (${violations.length}):`);
+    for (const violation of violations) console.error(`  ${violation}`);
+    process.exit(1);
+  }
+  console.log(`Presentation boundaries hold across ${Object.values(dirs).join(', ')}.`);
+}

package/templates/architectures/mvc-mvvm/files/src/__solutionName.dot__.Presentation/Models/__firstScreen.pascal__.cs

@@ -0,0 +1,8 @@
+namespace {{ solutionName | dot }}.Presentation.Models;
+
+/// <summary>What the {{ firstScreen | title }} screen is about, with no notion of how it is shown.</summary>
+// A model never references a ViewModel or a View — PresentationBoundaryTests fails the build if it does.
+public sealed record {{ firstScreen | pascal }}(string Title, IReadOnlyList<string> Items)
+{
+    public static {{ firstScreen | pascal }} Empty { get; } = new(string.Empty, []);
+}

package/templates/architectures/mvc-mvvm/files/src/__solutionName.dot__.Presentation/ViewModels/RelayCommand.cs

@@ -0,0 +1,18 @@
+using System.Windows.Input;
+
+namespace {{ solutionName | dot }}.Presentation.ViewModels;
+
+/// <summary>Binds a gesture to a view-model method without the view knowing which method.</summary>
+// System.Windows.Input.ICommand is a BCL contract, not a WPF view type — it is the one
+// "System.Windows" namespace the architecture test deliberately allows.
+public sealed class RelayCommand(Action<object?> execute, Func<object?, bool>? canExecute = null) : ICommand
+{
+    public event EventHandler? CanExecuteChanged;
+
+    public bool CanExecute(object? parameter) => canExecute?.Invoke(parameter) ?? true;
+
+    public void Execute(object? parameter) => execute(parameter);
+
+    /// <summary>Call when the guard's inputs changed so the view re-queries CanExecute.</summary>
+    public void RaiseCanExecuteChanged() => CanExecuteChanged?.Invoke(this, EventArgs.Empty);
+}

package/templates/architectures/mvc-mvvm/files/src/__solutionName.dot__.Presentation/ViewModels/ViewModelBase.cs

@@ -0,0 +1,27 @@
+using System.ComponentModel;
+using System.Runtime.CompilerServices;
+
+namespace {{ solutionName | dot }}.Presentation.ViewModels;
+
+/// <summary>Change notification is the wire a view binds to; without it MVVM is just folders.</summary>
+public abstract class ViewModelBase : INotifyPropertyChanged
+{
+    public event PropertyChangedEventHandler? PropertyChanged;
+
+    /// <summary>Assigns and notifies only on a real change, so bindings do not churn.</summary>
+    protected bool SetProperty<T>(ref T field, T value, [CallerMemberName] string? propertyName = null)
+    {
+        if (EqualityComparer<T>.Default.Equals(field, value))
+        {
+            return false;
+        }
+
+        field = value;
+        RaisePropertyChanged(propertyName);
+        return true;
+    }
+
+    /// <summary>For computed properties, whose source changed without them having a field.</summary>
+    protected void RaisePropertyChanged([CallerMemberName] string? propertyName = null) =>
+        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
+}

package/templates/architectures/mvc-mvvm/files/src/__solutionName.dot__.Presentation/ViewModels/__firstScreen.pascal__ViewModel.cs

@@ -0,0 +1,55 @@
+using System.Windows.Input;
+using {{ solutionName | dot }}.Presentation.Models;
+
+namespace {{ solutionName | dot }}.Presentation.ViewModels;
+
+/// <summary>Presentation state and behaviour for the {{ firstScreen | title }} screen.</summary>
+// Everything the view needs is a bindable property or a command, so the view holds no logic —
+// and this class is testable with no UI present. The load function is injected rather than
+// resolved here: a view model that constructs its own data source cannot be tested.
+public sealed class {{ firstScreen | pascal }}ViewModel : ViewModelBase
+{
+    private readonly Func<{{ firstScreen | pascal }}> _load;
+    private readonly RelayCommand _loadCommand;
+    private {{ firstScreen | pascal }} _model = {{ firstScreen | pascal }}.Empty;
+    private bool _isBusy;
+
+    public {{ firstScreen | pascal }}ViewModel(Func<{{ firstScreen | pascal }}> load)
+    {
+        _load = load;
+        _loadCommand = new RelayCommand(_ => Load(), _ => !IsBusy);
+    }
+
+    public string Title => _model.Title;
+
+    public IReadOnlyList<string> Items => _model.Items;
+
+    public bool IsBusy
+    {
+        get => _isBusy;
+        private set
+        {
+            if (SetProperty(ref _isBusy, value))
+            {
+                _loadCommand.RaiseCanExecuteChanged();
+            }
+        }
+    }
+
+    public ICommand LoadCommand => _loadCommand;
+
+    private void Load()
+    {
+        IsBusy = true;
+        try
+        {
+            _model = _load();
+            RaisePropertyChanged(nameof(Title));
+            RaisePropertyChanged(nameof(Items));
+        }
+        finally
+        {
+            IsBusy = false;
+        }
+    }
+}

package/templates/architectures/mvc-mvvm/files/src/__solutionName.dot__.Presentation/Views/README.md

@@ -0,0 +1,12 @@
+# Views
+
+Markup only. XAML pages, Razor views, or Blazor components go here — or in the UI head project
+that references this library, if the head owns its own SDK (MAUI, WPF, WinUI).
+
+**A view may not contain business logic.** In practice that means code-behind holds nothing but
+`InitializeComponent()` and a `DataContext`/`BindingContext` assignment. Everything else —
+state, validation, commands, data access — belongs in `../ViewModels/`.
+
+The direction is one-way: a view names its view model, a view model never names a view.
+`tests/*.ArchitectureTests` fails `dotnet test` the moment that inverts, and it fails today if
+any type in this library references a UI framework namespace.

package/templates/architectures/mvc-mvvm/files/src/__solutionName.dot__.Presentation/__solutionName.dot__.Presentation.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Presentation</RootNamespace>
+    <!-- No UI package reference, ever. Presentation logic that cannot name a view type is
+         presentation logic you can unit-test without spinning one up. -->
+    <NoWarn>$(NoWarn);CA1045</NoWarn>
+  </PropertyGroup>
+
+</Project>

package/templates/architectures/mvc-mvvm/files/src/__solutionName.snake__/controllers/__firstScreen.snake___controller.py

@@ -0,0 +1,17 @@
+"""Controller for the {{ firstScreen | title }} screen."""
+
+from __future__ import annotations
+
+from ..models.repository import {{ firstScreen | pascal }}Repository
+from ..views.{{ firstScreen | snake }}_view import render
+
+
+class {{ firstScreen | pascal }}Controller:
+    """Wire this to a route; the framework's request type stops here and goes no deeper."""
+
+    def __init__(self, repository: {{ firstScreen | pascal }}Repository | None = None) -> None:
+        # Injected so a test can drive the controller without a data source.
+        self._repository = repository or {{ firstScreen | pascal }}Repository()
+
+    def index(self) -> dict[str, object]:
+        return render(self._repository.get())

package/templates/architectures/mvc-mvvm/files/src/__solutionName.snake__/controllers/__init__.py

@@ -0,0 +1,5 @@
+"""Controllers: accept the request, ask the model, choose the view, return the result.
+
+This is the only layer that knows the web framework. Keeping the framework here is what lets
+models and views be tested with no server running.
+"""

package/templates/architectures/mvc-mvvm/files/src/__solutionName.snake__/models/__firstScreen.snake__.py

@@ -0,0 +1,13 @@
+"""The model behind the {{ firstScreen | title }} screen."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class {{ firstScreen | pascal }}:
+    """What the screen is about, expressed with no notion of how it is shown."""
+
+    title: str
+    items: tuple[str, ...] = field(default_factory=tuple)

package/templates/architectures/mvc-mvvm/files/src/__solutionName.snake__/models/__init__.py

@@ -0,0 +1,5 @@
+"""Models: the data and the rules that operate on it.
+
+Nothing here knows a request, a template, or a response. A model that imports a view or a
+controller is an inverted dependency, and `lint-imports` fails the build on it.
+"""

package/templates/architectures/mvc-mvvm/files/src/__solutionName.snake__/models/repository.py

@@ -0,0 +1,17 @@
+"""The only place data is fetched.
+
+Views are forbidden from importing this module (see `.importlinter`): a view renders what the
+controller handed it and never goes looking for more. That single ban is what keeps query
+logic out of templates.
+"""
+
+from __future__ import annotations
+
+from .{{ firstScreen | snake }} import {{ firstScreen | pascal }}
+
+
+class {{ firstScreen | pascal }}Repository:
+    """Swap the body for your data source; the seam the controller depends on stays the same."""
+
+    def get(self) -> {{ firstScreen | pascal }}:
+        return {{ firstScreen | pascal }}(title="{{ solutionName | title }}")

package/templates/architectures/mvc-mvvm/files/src/__solutionName.snake__/views/__firstScreen.snake___view.py

@@ -0,0 +1,17 @@
+"""Renders the {{ firstScreen | title }} model into a template context."""
+
+from __future__ import annotations
+
+from ..models.{{ firstScreen | snake }} import {{ firstScreen | pascal }}
+
+# Presentation-only default, so an empty model still renders something sensible.
+EMPTY_LABEL = "Nothing yet"
+
+
+def render(model: {{ firstScreen | pascal }}) -> dict[str, object]:
+    """Formatting decisions only. If a rule belongs in the domain, it belongs in models/."""
+    return {
+        "title": model.title,
+        "items": list(model.items),
+        "summary": f"{len(model.items)} items" if model.items else EMPTY_LABEL,
+    }

package/templates/architectures/mvc-mvvm/files/src/__solutionName.snake__/views/__init__.py

@@ -0,0 +1,6 @@
+"""Views: turn a model into what gets rendered.
+
+A view is pure — same model in, same output out. No queries, no branching on business rules,
+no imports from `controllers`. Jinja/Django templates live beside these modules; the functions
+here decide what the template is handed, not what is true.
+"""

package/templates/architectures/mvc-mvvm/files/src/models/index.ts

@@ -0,0 +1,4 @@
+// Models: plain data and pure functions. No React, no DOM, no fetch — a model that a test can
+// exercise without mounting anything. Importing `viewmodels/` or `views/` from here fails
+// `node scripts/check-mvvm-boundaries.mjs`.
+export {};

package/templates/architectures/mvc-mvvm/files/src/viewmodels/index.ts

@@ -0,0 +1,12 @@
+// View models: one `use<Screen>()` hook per screen, holding all state, effects, and handlers.
+// The hook is the ViewModel; the component that consumes it only renders.
+//
+//   export function useHome(): ViewModel<HomeState, HomeCommands> { ... }
+//
+// Nothing here renders, so nothing here needs a DOM to be tested.
+
+/** The shape every view-model hook returns: what to render, and what can be invoked. */
+export interface ViewModel<TState, TCommands> {
+  readonly state: TState;
+  readonly commands: TCommands;
+}

package/templates/architectures/mvc-mvvm/files/src/views/index.ts

@@ -0,0 +1,10 @@
+// Views: components that call their view-model hook and render its state. Nothing else.
+//
+//   export function HomeView() {
+//     const { state, commands } = useHome();
+//     return <section>...</section>;
+//   }
+//
+// No useState, no useEffect, no fetch, no value import from `models/` — the boundary check
+// fails the build on each of those.
+export {};