Services Layer¶

The services package is the application boundary between the UI and the domain. It exposes typed Protocol contracts (IGraphService, IWorkspaceService) that the UI layer programs against, and provides the concrete implementations (GraphService, WorkspaceService).

Why Protocol Contracts?¶

The UI layer imports only the Protocol types. This means:

• The UI can be tested with stub/mock implementations of the service.
• Concrete implementations can be swapped (e.g. a remote API backend) without touching any UI code.
• The static type-checker enforces that the UI only calls methods defined on the contract.

graph LR
    UI["UI MainWindow and OutlineView"] -->|depends on| IFace["Service Protocols"]
    GS["GraphService"] -.->|implements| IFace
    WS["WorkspaceService"] -.->|implements| IFace
    GS --> Engine["GraphEngine"]
    GS --> TR["TypeRegistry"]
    WS --> Repo["SqliteGraphRepository"]

Modules in this Layer¶

Module	Purpose
services.interfaces	IGraphService and IWorkspaceService — the UI-facing contracts
services.graph_service	GraphService — validates types and delegates to GraphEngine
services.workspace_service	WorkspaceService — manages workspace lifecycle and per-workspace repositories