Architecture

Overview

ShoreGuard is a Python/FastAPI application that sits between the browser and one or more NVIDIA OpenShell gateways. It communicates with gateways over gRPC (optionally with mTLS) and stores its own state in SQLite or PostgreSQL.

graph TB
    Browser["Browser (:8888)"] --> API["ShoreGuard API<br/>FastAPI"]
    API --> Services["Service Layer<br/>Gateway · Sandbox · Policy · Provider<br/>Audit · Webhooks · Operations"]
    Services --> DB["Persistence<br/>SQLAlchemy — SQLite / PostgreSQL"]
    Services --> Client["gRPC Client<br/>mTLS · Protobuf"]
    Client --> GW1["Gateway 1"]
    Client --> GW2["Gateway 2"]
    Client --> GW3["Gateway 3"]
    API -.->|"OIDC"| IDP["Identity Provider<br/>Google · Entra · Okta"]
    Services -.->|"Webhooks"| WH["External Services<br/>Slack · Discord · Email"]
    style Browser fill:#0969da,color:#fff,stroke:#0969da
    style API fill:#0969da,color:#fff,stroke:#0969da
    style GW1 fill:#1a7f37,color:#fff,stroke:#1a7f37
    style GW2 fill:#1a7f37,color:#fff,stroke:#1a7f37
    style GW3 fill:#1a7f37,color:#fff,stroke:#1a7f37

Layers

API layer — shoreguard/api/

FastAPI routes, authentication middleware, WebSocket endpoints, error handlers, Jinja2 page rendering, OIDC login flow, rate limiting, and security headers. This layer handles HTTP/WS concerns and delegates business logic to the service layer.

Service layer — shoreguard/services/

Business logic for gateways, sandboxes, policies, providers, approvals, operations, audit logging, and webhook delivery. Services are the single source of truth for validation, orchestration, and state transitions. They call the client layer to talk to gateways and the persistence layer to store state.

Client layer — shoreguard/client/

A gRPC client with mTLS support and protobuf stubs generated from the OpenShell .proto definitions. The client layer translates between ShoreGuard's domain model and the protobuf wire format.

Persistence — shoreguard/db/, shoreguard/db/models/

SQLAlchemy ORM models (split per domain, re-exported via shoreguard.models) on a fully async engine — every data service and the auth subsystem use AsyncSession. Database migrations are handled by Alembic and applied automatically on startup. Supports both SQLite (default, single-node) and PostgreSQL (multi-instance). See Configuration for setup.

Frontend — frontend/

Preact + TypeScript islands built with Vite, mounted into server-rendered Jinja2 shells (Bootstrap 5 styling). Each page declares <div data-island="…"> and loads a code-split component; WebSocket connections power real-time features like log streaming, approval notifications, and the interactive terminal.

OpenShell metadata

The file shoreguard/openshell.yaml provides metadata about the OpenShell ecosystem: provider types, credential keys, and community sandbox images. ShoreGuard reads this at startup to populate the sandbox wizard and provider configuration forms.

Authentication

ShoreGuard supports multiple authentication mechanisms — session cookies, API keys, and OIDC/SSO. All resolve to the same role-based permission model. See the Security Model for details.