Skip to main content

Project structure

SmartHopper is a single Visual Studio solution (SmartHopper.sln) where each project maps to one layer of the architecture. Understanding the layering is the fastest way to know where a change belongs.

Solution layout​

SmartHopper/
├── src/
│ ├── SmartHopper.ProviderSdk/ # MIT-licensed plugin SDK — the only
│ │ # dependency provider authors need
│ ├── SmartHopper.Core/ # Component base classes, context providers,
│ │ # shared component infrastructure
│ ├── SmartHopper.Core.Grasshopper/ # Grasshopper utilities, GhJSON integration,
│ │ # AI tool implementations, canvas helpers
│ ├── SmartHopper.Infrastructure/ # ProviderManager, ToolManager, AIContextManager,
│ │ # ConversationSession, policies, settings, security
│ ├── SmartHopper.Components/ # Production Grasshopper components
│ ├── SmartHopper.Components.Test/ # Test-only components (never shipped, not built in Release)
│ ├── SmartHopper.Menu/ # Menu bar entries and settings UI wiring
│ ├── SmartHopper.Providers.<Name>/ # One project per provider (OpenAI, Anthropic,
│ │ # Gemini, MistralAI, DeepSeek, OpenRouter,
│ │ # Ollama, LocalAI…)
│ └── SmartHopper.*.Tests/ # xUnit test projects per layer
├── docs/ # Internal architecture docs (source of truth)
├── tools/ # Build and packaging scripts
└── .devin/rules/ # Repo conventions for contributors

Layers and dependencies​

Dependencies only ever point down this list — a lower layer never references a higher one:

  • SmartHopper.ProviderSdk is deliberately standalone: provider contracts (IAIProvider, IAIProviderFactory, IAIProviderSettings), AICall types (interactions, AIBody, AIRequestCall, AIReturn), capability/model types, settings descriptors, and compatibility attributes. It contains no ProviderManager, no tools, no UI, no persistence — the host supplies those through the Hosting/ interfaces. This is what allows third parties to ship providers without pulling in SmartHopper itself.
  • SmartHopper.Infrastructure owns runtime orchestration: discovering and trusting provider assemblies, the tool catalog, the conversation/session pipeline, policies, settings storage, security.
  • SmartHopper.Core owns everything shared between the canvas and the host that isn't orchestration: component base classes, context providers, codecs.
  • SmartHopper.Core.Grasshopper is where Grasshopper-specific intelligence lives: GhJSON read/write, canvas graph utilities, and the AI tool implementations that manipulate the document.
  • SmartHopper.Components contains only Grasshopper-facing components — thin wiring over the base classes and the pipeline.
  • SmartHopper.Providers.* are plugin projects. They produce SmartHopper.Providers.<Name>.dll assemblies that ProviderManager discovers at runtime — the host has no compile-time dependency on them.

"Where does my change go?"​

Use the highest layer that owns the concern:

ChangeBelongs in
Wire-format quirk of one vendorThat SmartHopper.Providers.<Name> project
Provider discovery, trust, settings persistenceSmartHopper.Infrastructure
A new tool the assistant can callSmartHopper.Core.Grasshopper/AITools
A new context providerSmartHopper.Core/AIContext
A new end-user componentSmartHopper.Components
A change to how all components behaveSmartHopper.Core/ComponentBase
Anything providers must call or implementSmartHopper.ProviderSdk
A component that exists only to exercise behavior in testsSmartHopper.Components.Test

If you find yourself reaching for an InternalsVisibleTo or an upward reference, the logic is at the wrong layer — move it down.

Target platforms​

  • Rhino 8 / Grasshopper 1, .NET 7 — net7.0-windows on Windows, net7.0 on macOS.
  • SmartHopper.ProviderSdk targets both net7.0 and net7.0-windows so providers can be built and tested without Windows-only APIs.

Building and testing​

TaskCommand
Full signed build (Windows).\tools\Build-Solution.ps1 (handles signing, prompts for the cert password)
SDK tests without a signing keydotnet test src/SmartHopper.ProviderSdk.Tests/SmartHopper.ProviderSdk.Tests.csproj -p:SignAssembly=false
Infrastructure/Core testsdotnet test on the matching *.Tests project

Testing rules worth knowing:

  • No unit test may reference Rhino/Grasshopper. If validation genuinely needs the canvas, write a testing component in SmartHopper.Components.Test (excluded from Release builds) rather than a unit test.
  • Test at the lowest layer that owns the behavior: Infrastructure.Tests for managers and pipeline logic, Core.Tests for non-Rhino core code, Core.Grasshopper.Tests for helpers that don't need the runtime.
  • ProviderSdk.Tests classes run in a single [Collection("ProviderSdk")] to serialize access to shared registries like AIModelCapabilityRegistry.Instance.
  • Internal architecture notes live in the SmartHopper repo's /docs folder (Providers/, Context/, Components/, Architecture/).
  • Contributor conventions live in .devin/rules/ — most importantly solution-structure.md, testing-and-build.md, and the infrastructure-*.md files this guide distills.