router planning

2025-12-02 18:38:32 +02:00
parent 790801f329
commit 0c9e8d5d18
15 changed files with 6439 additions and 0 deletions
--- a/docs/router/03-Step.md
+++ b/docs/router/03-Step.md
@@ -0,0 +1,144 @@
+For this step, you’re not writing any real logic yet – you’re just making sure the projects depend on each other in the right direction so future work doesn’t turn into spaghetti.
+
+Think of it as locking in the dependency graph.
+
+---
+
+## 1. Pin the desired dependency graph
+
+First, make explicit what is allowed to depend on what.
+
+Target graph:
+
+* `StellaOps.Router.Common`
+
+  * Lowest layer.
+  * **No** project references to any other StellaOps projects.
+
+* `StellaOps.Router.Config`
+
+  * References:
+
+    * `StellaOps.Router.Common`.
+
+* `StellaOps.Microservice`
+
+  * References:
+
+    * `StellaOps.Router.Common`.
+
+* `StellaOps.Microservice.SourceGen`
+
+  * For now: no references, or only to Common if needed for types in generated code.
+  * Later: will be consumed as an analyzer by `StellaOps.Microservice`, not via normal project reference.
+
+* `StellaOps.Gateway.WebService`
+
+  * References:
+
+    * `StellaOps.Router.Common`
+    * `StellaOps.Router.Config`.
+
+Test projects:
+
+* `StellaOps.Router.Common.Tests` → `StellaOps.Router.Common`
+* `StellaOps.Gateway.WebService.Tests` → `StellaOps.Gateway.WebService`
+* `StellaOps.Microservice.Tests` → `StellaOps.Microservice`
+
+Explicitly: there should be **no** circular references, and nothing should reference the Gateway from libraries.
+
+---
+
+## 2. Add the project references
+
+From repo root, for each needed edge:
+
+```bash
+# Gateway → Common + Config
+dotnet add src/StellaOps.Gateway.WebService/StellaOps.Gateway.WebService.csproj reference \
+  src/__Libraries/StellaOps.Router.Common/StellaOps.Router.Common.csproj \
+  src/__Libraries/StellaOps.Router.Config/StellaOps.Router.Config.csproj
+
+# Microservice → Common
+dotnet add src/__Libraries/StellaOps.Microservice/StellaOps.Microservice.csproj reference \
+  src/__Libraries/StellaOps.Router.Common/StellaOps.Router.Common.csproj
+
+# Config → Common
+dotnet add src/__Libraries/StellaOps.Router.Config/StellaOps.Router.Config.csproj reference \
+  src/__Libraries/StellaOps.Router.Common/StellaOps.Router.Common.csproj
+
+# Tests → main projects
+dotnet add tests/StellaOps.Router.Common.Tests/StellaOps.Router.Common.Tests.csproj reference \
+  src/__Libraries/StellaOps.Router.Common/StellaOps.Router.Common.csproj
+
+dotnet add tests/StellaOps.Gateway.WebService.Tests/StellaOps.Gateway.WebService.Tests.csproj reference \
+  src/StellaOps.Gateway.WebService/StellaOps.Gateway.WebService.csproj
+
+dotnet add tests/StellaOps.Microservice.Tests/StellaOps.Microservice.Tests.csproj reference \
+  src/__Libraries/StellaOps.Microservice/StellaOps.Microservice.csproj
+```
+
+Do **not** add any references:
+
+* From `Common` → anything.
+* From `Config` → Gateway or Microservice.
+* From `Microservice` → Gateway.
+* From tests → libraries other than their primary target (unless you explicitly want shared test utils later).
+
+---
+
+## 3. Verify the .csproj contents
+
+Have one agent open each `.csproj` and confirm:
+
+* `StellaOps.Router.Common.csproj`
+
+  * No `<ProjectReference>` elements.
+
+* `StellaOps.Router.Config.csproj`
+
+  * Exactly one `<ProjectReference>`: Common.
+
+* `StellaOps.Microservice.csproj`
+
+  * Exactly one `<ProjectReference>`: Common.
+
+* `StellaOps.Microservice.SourceGen.csproj`
+
+  * No project references for now (we’ll convert it to a proper analyzer / source-generator package later).
+
+* `StellaOps.Gateway.WebService.csproj`
+
+  * Exactly two `<ProjectReference>`s: Common + Config.
+  * No reference to Microservice.
+
+* Test projects:
+
+  * Each test project references only its corresponding main project (no cross-test coupling).
+
+If anything else is present (e.g. leftover references from templates), remove them.
+
+---
+
+## 4. Run a full build & test as a sanity check
+
+From repo root:
+
+```bash
+dotnet restore
+dotnet build StellaOps.Router.sln -c Debug
+dotnet test  StellaOps.Router.sln -c Debug
+```
+
+Acceptance criteria for this step:
+
+* Solution builds without reference errors.
+* All test projects compile and run (even if they only have dummy tests).
+* Intellisense / navigation in IDE shows:
+
+  * Gateway can see Common & Config types.
+  * Microservice can see Common types.
+  * Config can see Common types.
+  * No library can see Gateway unless through tests.
+
+Once this is stable, your devs can safely move on to implementing the Common model and know they won’t have to rewrite references later.