@opengroundplan/core 0.1.1

package/templates/architectures/hexagonal/files/docs/architecture/hexagonal.md

@@ -0,0 +1,102 @@
+# Hexagonal (Ports and Adapters)
+
+**Style:** hexagonal — **Stack:** {{ stack }}
+
+Cockburn's stated intent: let {{ solutionName | title }} be driven equally by people, other
+programs, automated tests, or batch scripts, and let it be built and tested in isolation
+from the databases and devices it eventually runs against.
+
+## The one rule
+
+> **The application defines the ports. Adapters depend on the application — the application
+> never depends on an adapter. Only the composition root names a concrete adapter.**
+
+Everything below is a consequence of that sentence. If you find yourself importing a driver,
+a client library, or an ORM type from `application/` or `domain/`, the hexagon has leaked and
+the boundary check will fail.
+
+## The zones
+
+| Zone | Holds | May depend on |
+|---|---|---|
+| `domain` | entities, value objects, invariants | nothing in this repo |
+| `ports/inbound` | driving ports — the use cases offered to the outside | `domain` |
+| `ports/outbound` | driven ports — what the application needs from the outside | `domain` |
+| `application` | use-case services; implements inbound, calls outbound | `domain`, `ports` |
+| `adapters/inbound` | driving adapters, one per technology (HTTP, CLI, queue consumer) | `ports`, `domain` |
+| `adapters/outbound` | driven adapters, one per technology (SQL, in-memory, HTTP client) | `ports`, `domain` |
+| `bootstrap` | the composition root — wires ports to adapters, reads config | everything |
+
+Two things follow that people get wrong:
+
+- **A port is named for what the application needs, not for the tool behind it.**
+  `NotificationPort` — not `SendGridPort`. Naming the port after the tool inverts the
+  pattern: you end up designing the application around the vendor's API.
+- **Driving and driven adapters never import each other.** An HTTP handler that reaches
+  into the repository adapter has bypassed the hexagon entirely. That one is enforced.
+
+An adapter you can swap is the point of the whole exercise: the in-memory outbound adapter
+exists so tests drive the real application with no database at all.
+
+## Layout on this stack
+
+```
+dotnet                          python                        node
+src/                            src/<package>/                src/
+  <Sln>.Domain/                   domain/                       domain/
+  <Sln>.Application/              ports/                        ports/
+    Ports/Inbound/                  inbound/                      inbound/
+    Ports/Outbound/                 outbound/                     outbound/
+    UseCases/                     application/                  application/
+  <Sln>.Adapters.Inbound.Http/    adapters/                     adapters/
+  <Sln>.Adapters.Outbound.*/        inbound/http/                 inbound/http/
+  <Sln>.Bootstrap/                  outbound/persistence/         outbound/persistence/
+tests/                              outbound/in_memory/           outbound/in-memory/
+  <Sln>.ArchitectureTests/        bootstrap/                    bootstrap/
+```
+
+```
+go
+internal/
+  domain/           ports/inbound/    application/    bootstrap/
+  ports/outbound/   adapters/inbound/rest/            adapters/outbound/postgres/
+  architecture/     adapters/outbound/memory/
+```
+
+On .NET the zones are separate projects, so the compiler enforces most of the rule through
+the direction of the `ProjectReference` edges. On the other stacks they are folders, and the
+boundary check below is the only thing standing between you and a shortcut.
+
+## Enforcing it
+
+| Stack | Tool | Command |
+|---|---|---|
+| dotnet | NetArchTest, in `tests/<Sln>.ArchitectureTests` | `dotnet test` |
+| python | [import-linter](https://import-linter.readthedocs.io) contracts in `.importlinter` | `lint-imports` |
+| node | a dependency-free scanner in `scripts/check-architecture.mjs` | `npm run arch:check` |
+| go | a stdlib fitness test in `internal/architecture` | `go test ./...` |
+
+Wire that command into CI next to the unit tests. A boundary rule that only lives in a
+document is a boundary rule that gets violated in the third sprint.
+
+Notes:
+
+- Python: `lint-imports` resolves the root package by import, so run it after an editable
+  install (`uv sync`), or as `PYTHONPATH=src lint-imports`.
+- Node: the check follows relative imports only. A `tsconfig` path alias that crosses a
+  boundary is invisible to it — and to reviewers, which is the better reason not to add one.
+- dependency-cruiser is the obvious tool on Node and is deliberately not used: it needs a
+  `typescript` version it supports and otherwise reports a clean cruise of zero modules, so
+  the check would pass without having checked anything.
+
+## Wiring the composition root
+
+The base template's entry point (`Program.cs`, `main.py`, `src/index.ts`, `cmd/`) is still the
+process host. Point it at `bootstrap` and delete the base's example endpoint once your first
+real use case exists — the host should construct adapters, hand them to the application, and
+do nothing else.
+
+## Sources
+
+- Alistair Cockburn, *Hexagonal Architecture* — <https://alistair.cockburn.us/hexagonal-architecture/>
+- Herberto Graça, *Ports and Adapters Architecture* — <https://herbertograca.com/2017/09/14/ports-adapters-architecture/>

package/templates/architectures/hexagonal/files/internal/adapters/inbound/rest/doc.go

@@ -0,0 +1,2 @@
+// Package rest is the HTTP driving adapter: it turns requests into inbound-port calls.
+package rest

package/templates/architectures/hexagonal/files/internal/adapters/outbound/memory/doc.go

@@ -0,0 +1,2 @@
+// Package memory is the in-memory driven adapter: same ports, no database — tests drive this one.
+package memory

package/templates/architectures/hexagonal/files/internal/adapters/outbound/postgres/doc.go

@@ -0,0 +1,2 @@
+// Package postgres is the Postgres driven adapter: it implements a repository outbound port.
+package postgres

package/templates/architectures/hexagonal/files/internal/application/doc.go

@@ -0,0 +1,2 @@
+// Package application implements the inbound ports by calling the outbound ports.
+package application

package/templates/architectures/hexagonal/files/internal/architecture/architecture_test.go

@@ -0,0 +1,150 @@
+package architecture
+
+import (
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// repoRoot is two levels up from internal/architecture.
+const repoRoot = "../.."
+
+// Zone dependency rules. A file in `zone` may import an internal package only when that
+// package sits under one of `mayImport`. Packages outside every zone (the base template's
+// own, and cmd/) are not policed — they are the process host, not the hexagon.
+var zoneRules = []struct {
+	zone      string
+	mayImport []string
+}{
+	{"internal/domain", []string{"internal/domain"}},
+	{"internal/ports", []string{"internal/domain", "internal/ports"}},
+	{"internal/application", []string{"internal/domain", "internal/ports", "internal/application"}},
+	// Adapters may reach the application and its ports; they may not reach the other side of
+	// the hexagon (inbound <-> outbound) or the composition root. bootstrap is in no list, so
+	// nothing may import it — only it may import concrete adapters.
+	{"internal/adapters/inbound", []string{"internal/domain", "internal/ports", "internal/application", "internal/adapters/inbound"}},
+	{"internal/adapters/outbound", []string{"internal/domain", "internal/ports", "internal/application", "internal/adapters/outbound"}},
+}
+
+// I/O the domain must reach through an outbound port instead of importing directly.
+var domainForbiddenStdlib = []string{"net/http", "database/sql", "os", "os/exec"}
+
+var skipDirs = map[string]bool{".git": true, "vendor": true, "testdata": true, "node_modules": true}
+
+func TestZonesDependOnlyInward(t *testing.T) {
+	for _, file := range goFiles(t) {
+		for _, rule := range zoneRules {
+			if !inZone(file.pkgDir, rule.zone) {
+				continue
+			}
+			for _, imported := range file.imports {
+				zone, ok := internalZone(imported)
+				if !ok || allowed(zone, rule.mayImport) {
+					continue
+				}
+				t.Errorf("%s imports %q: %s may only import %s",
+					file.path, imported, rule.zone, strings.Join(rule.mayImport, ", "))
+			}
+		}
+	}
+}
+
+func TestDomainDoesNoIO(t *testing.T) {
+	for _, file := range goFiles(t) {
+		if !inZone(file.pkgDir, "internal/domain") {
+			continue
+		}
+		for _, imported := range file.imports {
+			for _, forbidden := range domainForbiddenStdlib {
+				if imported == forbidden {
+					t.Errorf("%s imports %q — the domain talks to the outside through an outbound port",
+						file.path, imported)
+				}
+			}
+		}
+	}
+}
+
+type goFile struct {
+	path    string // slash-separated, relative to the repo root
+	pkgDir  string
+	imports []string
+}
+
+func goFiles(t *testing.T) []goFile {
+	t.Helper()
+
+	var files []goFile
+	fset := token.NewFileSet()
+
+	err := filepath.WalkDir(repoRoot, func(walked string, entry fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if entry.IsDir() {
+			if skipDirs[entry.Name()] {
+				return fs.SkipDir
+			}
+			return nil
+		}
+		if !strings.HasSuffix(entry.Name(), ".go") {
+			return nil
+		}
+
+		parsed, err := parser.ParseFile(fset, walked, nil, parser.ImportsOnly)
+		if err != nil {
+			return err
+		}
+
+		relative, err := filepath.Rel(repoRoot, walked)
+		if err != nil {
+			return err
+		}
+		slashed := filepath.ToSlash(relative)
+
+		file := goFile{path: slashed, pkgDir: path.Dir(slashed)}
+		for _, spec := range parsed.Imports {
+			file.imports = append(file.imports, strings.Trim(spec.Path.Value, `"`))
+		}
+		files = append(files, file)
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("walking %s: %v", repoRoot, err)
+	}
+
+	// An empty walk would make every rule pass silently.
+	if len(files) == 0 {
+		wd, _ := os.Getwd()
+		t.Fatalf("no Go files found under %s (cwd %s)", repoRoot, wd)
+	}
+	return files
+}
+
+// internalZone maps an import path onto its repo-relative package dir, ignoring the module
+// prefix so this test needs no knowledge of the module path.
+func internalZone(importPath string) (string, bool) {
+	index := strings.Index(importPath, "/internal/")
+	if index < 0 {
+		return "", false
+	}
+	return importPath[index+1:], true
+}
+
+func inZone(pkgDir, zone string) bool {
+	return pkgDir == zone || strings.HasPrefix(pkgDir, zone+"/")
+}
+
+func allowed(zone string, permitted []string) bool {
+	for _, prefix := range permitted {
+		if inZone(zone, prefix) {
+			return true
+		}
+	}
+	return false
+}

package/templates/architectures/hexagonal/files/internal/architecture/doc.go

@@ -0,0 +1,2 @@
+// Package architecture holds the fitness test that enforces the hexagon boundaries.
+package architecture

package/templates/architectures/hexagonal/files/internal/bootstrap/doc.go

@@ -0,0 +1,2 @@
+// Package bootstrap is the composition root: the only package allowed to name a concrete adapter.
+package bootstrap

package/templates/architectures/hexagonal/files/internal/domain/doc.go

@@ -0,0 +1,2 @@
+// Package domain holds entities, value objects and invariants. It imports nothing else under internal/.
+package domain

package/templates/architectures/hexagonal/files/internal/ports/inbound/doc.go

@@ -0,0 +1,2 @@
+// Package inbound declares the driving ports — the use cases this application offers.
+package inbound

package/templates/architectures/hexagonal/files/internal/ports/outbound/doc.go

@@ -0,0 +1,2 @@
+// Package outbound declares the driven ports — what the application requires from the outside.
+package outbound

package/templates/architectures/hexagonal/files/pyproject.toml

@@ -0,0 +1,2 @@
+[dependency-groups]
+dev = ["import-linter==2.13"]

package/templates/architectures/hexagonal/files/scripts/check-architecture.mjs

@@ -0,0 +1,104 @@
+// Boundary check for the hexagon. Run `npm run arch:check` — see docs/architecture/hexagonal.md.
+// Deliberately dependency-free: the import linters in this ecosystem are pinned to a
+// TypeScript version, and a boundary check that silently scans nothing is worse than none.
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const ZONES = ['domain', 'ports', 'application', 'adapters/inbound', 'adapters/outbound', 'bootstrap'];
+
+// A file in `zone` may import another zone only when it is listed here. Zones with no rule
+// (bootstrap, and anything the base ships outside the hexagon) are not policed as importers —
+// but they are still recognised as targets, so nothing else may import them.
+const ZONE_RULES = [
+  { zone: 'domain', mayImport: ['domain'] },
+  { zone: 'ports', mayImport: ['domain', 'ports'] },
+  { zone: 'application', mayImport: ['domain', 'ports', 'application'] },
+  { zone: 'adapters/inbound', mayImport: ['domain', 'ports', 'adapters/inbound'] },
+  { zone: 'adapters/outbound', mayImport: ['domain', 'ports', 'adapters/outbound'] },
+];
+
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+const SKIP_DIRECTORIES = new Set(['node_modules', 'dist', 'build', 'coverage', '.turbo', '.next', '.git']);
+
+// `from '…'`, `import('…')`, `require('…')`, and bare `import '…'`.
+const SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|\bimport\s+)['"]([^'"]+)['"]/g;
+
+const roots = process.argv.slice(2);
+if (roots.length === 0) {
+  console.error('usage: node scripts/check-architecture.mjs <dir> [dir...]');
+  process.exit(2);
+}
+
+const files = roots.flatMap(collectSources);
+if (files.length === 0) {
+  console.error(`No source files found under: ${roots.join(', ')} — nothing was checked.`);
+  process.exit(2);
+}
+
+const violations = [];
+for (const file of files) {
+  const rule = ZONE_RULES.find((candidate) => candidate.zone === zoneOf(file));
+  if (!rule) continue;
+
+  for (const specifier of importsOf(file)) {
+    if (!specifier.startsWith('.')) continue; // package import — not a boundary crossing
+
+    const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(toPosix(file)), specifier));
+    const importedZone = zoneOf(resolved);
+    if (!importedZone || rule.mayImport.includes(importedZone)) continue;
+
+    violations.push(
+      `${file}\n  imports ${specifier} → ${importedZone}\n  ${rule.zone} may import only: ${rule.mayImport.join(', ')}`,
+    );
+  }
+}
+
+if (violations.length > 0) {
+  console.error(`\nHexagon boundary violated (${violations.length}):\n`);
+  console.error(violations.join('\n\n'));
+  console.error('\nSee docs/architecture/hexagonal.md.\n');
+  process.exit(1);
+}
+
+console.log(`Hexagon boundaries hold — ${files.length} files checked.`);
+
+function collectSources(root) {
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries.flatMap((entry) => {
+    const full = toPosix(path.join(root, entry.name));
+    if (entry.isDirectory()) return SKIP_DIRECTORIES.has(entry.name) ? [] : collectSources(full);
+    return SOURCE_EXTENSIONS.includes(path.extname(entry.name)) ? [full] : [];
+  });
+}
+
+/** The zone a path belongs to, matched under any `src/` so a monorepo workspace works too. */
+function zoneOf(filePath) {
+  const match = toPosix(filePath).match(/(?:^|\/)src\/(.+)$/);
+  if (!match) return undefined;
+
+  const withinSrc = match[1];
+  // Longest first, so `adapters/inbound` wins over a bare `adapters`.
+  return [...ZONES]
+    .sort((a, b) => b.length - a.length)
+    .find((zone) => withinSrc === zone || withinSrc.startsWith(`${zone}/`));
+}
+
+function importsOf(file) {
+  const source = stripComments(readFileSync(file, 'utf8'));
+  return [...source.matchAll(SPECIFIER)].map((match) => match[1]);
+}
+
+// A commented-out import must not fail the build.
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Adapters.Inbound.Http/HttpAdapterMarker.cs

@@ -0,0 +1,4 @@
+namespace {{ solutionName | dot }}.Adapters.Inbound.Http;
+
+// Anchors the assembly for the architecture tests until real endpoints exist.
+public sealed class HttpAdapterMarker;

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Adapters.Inbound.Http/__solutionName.dot__.Adapters.Inbound.Http.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Adapters.Inbound.Http</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Adapters.Inbound.Http</AssemblyName>
+  </PropertyGroup>
+
+  <!-- A driving adapter references the application to reach its inbound ports, and nothing
+       else. One project per driving technology: CLI, queue consumer, scheduled job. -->
+  <ItemGroup>
+    <ProjectReference Include="../{{ solutionName | dot }}.Application/{{ solutionName | dot }}.Application.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Adapters.Outbound.InMemory/InMemoryAdapterMarker.cs

@@ -0,0 +1,4 @@
+namespace {{ solutionName | dot }}.Adapters.Outbound.InMemory;
+
+// Anchors the assembly for the architecture tests until real in-memory adapters exist.
+public sealed class InMemoryAdapterMarker;

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Adapters.Outbound.InMemory/__solutionName.dot__.Adapters.Outbound.InMemory.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Adapters.Outbound.InMemory</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Adapters.Outbound.InMemory</AssemblyName>
+  </PropertyGroup>
+
+  <!-- The same outbound ports with no database behind them. This is the adapter tests drive,
+       and the reason the pattern exists at all. -->
+  <ItemGroup>
+    <ProjectReference Include="../{{ solutionName | dot }}.Application/{{ solutionName | dot }}.Application.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Adapters.Outbound.Persistence/PersistenceAdapterMarker.cs

@@ -0,0 +1,4 @@
+namespace {{ solutionName | dot }}.Adapters.Outbound.Persistence;
+
+// Anchors the assembly for the architecture tests until real repositories exist.
+public sealed class PersistenceAdapterMarker;

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Adapters.Outbound.Persistence/__solutionName.dot__.Adapters.Outbound.Persistence.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Adapters.Outbound.Persistence</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Adapters.Outbound.Persistence</AssemblyName>
+  </PropertyGroup>
+
+  <!-- A driven adapter implements outbound ports. Database packages belong here and only
+       here — one project per driven technology. -->
+  <ItemGroup>
+    <ProjectReference Include="../{{ solutionName | dot }}.Application/{{ solutionName | dot }}.Application.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Application/ApplicationMarker.cs

@@ -0,0 +1,4 @@
+namespace {{ solutionName | dot }}.Application;
+
+// Anchors the assembly for the architecture tests until real use cases exist.
+public sealed class ApplicationMarker;

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Application/Ports/Inbound/.gitkeep

@@ -0,0 +1 @@
+# Driving ports: the use cases this application offers. One interface per use case.

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Application/Ports/Outbound/.gitkeep

@@ -0,0 +1 @@
+# Driven ports: what the application requires. Named for the need, never for the tool.

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Application/UseCases/.gitkeep

@@ -0,0 +1 @@
+# Use-case services: implement Ports/Inbound, depend on Ports/Outbound.

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Application/__solutionName.dot__.Application.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Application</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Application</AssemblyName>
+  </PropertyGroup>
+
+  <!-- The only edge out of the application. Adding an adapter reference here inverts the
+       pattern and the architecture tests will fail. -->
+  <ItemGroup>
+    <ProjectReference Include="../{{ solutionName | dot }}.Domain/{{ solutionName | dot }}.Domain.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Bootstrap/CompositionRoot.cs

@@ -0,0 +1,8 @@
+namespace {{ solutionName | dot }}.Bootstrap;
+
+// Register each outbound port against the adapter that implements it here, then let the host
+// project (Program.cs) call this and nothing else. Swapping Persistence for InMemory is a
+// one-line change in this file — that swap is the whole point of the style.
+public static class CompositionRoot
+{
+}

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Bootstrap/__solutionName.dot__.Bootstrap.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Bootstrap</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Bootstrap</AssemblyName>
+  </PropertyGroup>
+
+  <!-- The composition root is the one project that may see every adapter. Reference the host
+       project (the API) at this project, never the other way around. -->
+  <ItemGroup>
+    <ProjectReference Include="../{{ solutionName | dot }}.Application/{{ solutionName | dot }}.Application.csproj" />
+    <ProjectReference Include="../{{ solutionName | dot }}.Adapters.Inbound.Http/{{ solutionName | dot }}.Adapters.Inbound.Http.csproj" />
+    <ProjectReference Include="../{{ solutionName | dot }}.Adapters.Outbound.Persistence/{{ solutionName | dot }}.Adapters.Outbound.Persistence.csproj" />
+    <ProjectReference Include="../{{ solutionName | dot }}.Adapters.Outbound.InMemory/{{ solutionName | dot }}.Adapters.Outbound.InMemory.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Domain/DomainMarker.cs

@@ -0,0 +1,4 @@
+namespace {{ solutionName | dot }}.Domain;
+
+// Anchors the assembly for the architecture tests until real domain types exist.
+public sealed class DomainMarker;

package/templates/architectures/hexagonal/files/src/__solutionName.dot__.Domain/__solutionName.dot__.Domain.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Domain</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Domain</AssemblyName>
+  </PropertyGroup>
+
+  <!-- No ProjectReference, no PackageReference. This is the middle of the hexagon: the
+       moment it needs something from outside, that something is an outbound port. -->
+
+</Project>

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters. One subpackage per technology; none of them may import each other."""

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/adapters/inbound/__init__.py

@@ -0,0 +1 @@
+"""Driving adapters — things that call the application (HTTP, CLI, queue consumer)."""

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/adapters/inbound/http/__init__.py

@@ -0,0 +1 @@
+"""HTTP driving adapter: translates requests into inbound-port calls and back."""

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/adapters/outbound/__init__.py

@@ -0,0 +1 @@
+"""Driven adapters — things the application calls through an outbound port."""

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/adapters/outbound/in_memory/__init__.py

@@ -0,0 +1 @@
+"""In-memory driven adapter: the same ports, no database — this is what tests drive."""

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/adapters/outbound/persistence/__init__.py

@@ -0,0 +1 @@
+"""Persistence driven adapter: implements the repository outbound port."""

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/application/__init__.py

@@ -0,0 +1 @@
+"""Use-case services: implement the inbound ports, call the outbound ports."""

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/bootstrap/__init__.py

@@ -0,0 +1 @@
+"""Composition root: the only place allowed to name a concrete adapter."""

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/domain/__init__.py

@@ -0,0 +1 @@
+"""Entities, value objects and invariants. Imports nothing else in this package."""

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/ports/__init__.py

@@ -0,0 +1 @@
+"""Ports: interfaces the application owns. Named for what the application needs."""

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/ports/inbound/__init__.py

@@ -0,0 +1 @@
+"""Driving ports — the use cases this application offers to the outside world."""

package/templates/architectures/hexagonal/files/src/__solutionName.snake__/ports/outbound/__init__.py

@@ -0,0 +1 @@
+"""Driven ports — what the application requires from the outside world."""

package/templates/architectures/hexagonal/files/src/adapters/inbound/http/index.ts

@@ -0,0 +1,2 @@
+// HTTP driving adapter: turns requests into inbound-port calls and back.
+export {};

package/templates/architectures/hexagonal/files/src/adapters/outbound/in-memory/index.ts

@@ -0,0 +1,2 @@
+// In-memory driven adapter: same ports, no database — this is what tests drive.
+export {};

package/templates/architectures/hexagonal/files/src/adapters/outbound/persistence/index.ts

@@ -0,0 +1,2 @@
+// Persistence driven adapter: implements the repository outbound port.
+export {};

package/templates/architectures/hexagonal/files/src/application/index.ts

@@ -0,0 +1,2 @@
+// Use-case services: implement the inbound ports, call the outbound ports.
+export {};

package/templates/architectures/hexagonal/files/src/bootstrap/index.ts

@@ -0,0 +1,2 @@
+// Composition root: the only file allowed to import a concrete adapter.
+export {};

package/templates/architectures/hexagonal/files/src/domain/index.ts

@@ -0,0 +1,2 @@
+// Entities, value objects and invariants. Imports nothing else under src/.
+export {};

package/templates/architectures/hexagonal/files/src/ports/inbound/index.ts

@@ -0,0 +1,2 @@
+// Driving ports — the use cases this application offers to the outside world.
+export {};

package/templates/architectures/hexagonal/files/src/ports/outbound/index.ts

@@ -0,0 +1,2 @@
+// Driven ports — what the application requires. Named for the need, not the tool.
+export {};