Gram Management API

Gram's management API is the internal HTTP-RPC surface that the dashboard, CLI, and SDK use to administer projects, toolsets, deployments, access, and related resources. Every endpoint lives at /rpc/<service>.<method>, is authored in Goa DSL under server/design/, implemented in a single Service struct per package under server/internal/<service>/, and exposed through generated server stubs, OpenAPI, CLI bindings, and a TypeScript SDK.

Concepts and terminology

Service. A named collection of related endpoints (e.g. remoteMcp, access, auditlogs). Each service maps one-to-one to a Go package of the same name.

Method. A single endpoint on a service. Exposed as /rpc/<service>.<method>.

Payload / Result. The input and output types for a method. Payloads are composed from shared security payloads plus method-specific form attributes.

Security scheme. The authentication mechanism a method accepts. Gram's management endpoints use three schemes: Session (browser cookie), ByKey (API key header), and ProjectSlug (project-selector header). Additional schemes exist for non-management surfaces and are out of scope here.

Model views (mv). Stateless functions that convert database row types into API response types. Keep database types out of the API boundary — handlers always return a view, never a repo struct.

Handler. One method implementation on the Service struct.

Management API vs public SDK. The same Goa design produces two OpenAPI outputs: an internal spec used to generate the TypeScript SDK that powers the dashboard and CLI, and a public spec derived from it via redaction overlays. Only the internal SDK sees every endpoint.

Changeset. A short changelog file written alongside a change that identifies which package bumps (server, dashboard, sdk) and by how much (patch, minor, major).

Server

The design, implementation, tests, and per-service generated code for every management endpoint live under server/.

Conventions

Naming. Goa service names (e.g. remoteMcp, auditlogs) and method names (e.g. createServer) are camelCase. DSL types (e.g. CreateServerForm, RemoteMcpServer) are PascalCase. Go package names under server/internal/ and server/design/ are lowercase with no separators (e.g. remotemcp).

Design layout. Service DSL lives at server/design/<svc>/design.go. The service package must be blank-imported in server/design/gram.go (alphabetised) for the generator to pick it up.

HTTP methods. Read methods use GET; mutations use POST. Deletes that carry only an id query parameter use DELETE.

Security DSL helpers. server/design/security/ exports the Session, ByKey, and ProjectSlug schemes plus paired helpers — SessionPayload()/SessionHeader(), ByKeyPayload()/ByKeyHeader(), ProjectPayload()/ProjectHeader() — that attach the right payload field and HTTP header to a method.

Security composition. Most management endpoints advertise Session and ByKey side-by-side via repeated Security(...) calls on the service so the dashboard and API-key clients can both reach them. Project-scoped endpoints additionally layer ProjectSlug via ProjectPayload() / ProjectHeader() so the caller must name a project.

Shared errors. Every service calls shared.DeclareErrorResponses() (from server/design/shared/errors.go) exactly once so the standard Gram error envelope applies to every method.

Shared types. When a payload or result type is reused across services, add Meta("struct:pkg:path", "types") so the generator emits it under server/gen/types/ instead of the per-service package.

OpenAPI meta keys. Every method has three metadata keys that control the downstream SDK/CLI names:

• Meta("openapi:operationId", "verbNounSubject") — OpenAPI operation id.
• Meta("openapi:extension:x-speakeasy-name-override", "methodName") — method name on the SDK service class.
• Meta("openapi:extension:x-speakeasy-react-hook", '{"name": "HookName"}') — React Query hook name.

impl.go layout. Lives at server/internal/<svc>/impl.go. Contains the Service struct (injected dependencies — tracer, logger, database pool, *auth.Auth, *access.Manager, plus feature-specific fields), compile-time assertions (var _ gen.Service = (*Service)(nil), and var _ gen.Auther = (*Service)(nil) when ByKey is advertised), a NewService(...) constructor, an Attach(mux, service) wiring function, APIKeyAuth when ByKey is advertised, and one method per Goa Method declaration.

Model view files. server/internal/mv/<svc>.go (singular or per-resource — e.g. remotemcpserver.go). Exported functions are named Build<Subject>View and Build<Subject>ListView. The package doc calls these "model views", which is where the package name comes from.

Wiring. New services are attached in server/cmd/gram/start.go with <svc>.Attach(mux, <svc>.NewService(...)) near the other service attachments.

SQLc. Per-service queries live in server/internal/<svc>/queries.sql. Every new service requires a stanza in server/database/sqlc.yaml pointing at its queries file and writing to server/internal/<svc>/repo/.

Resource URNs. Every resource owned by the service gets a URN type under server/internal/urn/<resource>.go (template: server/internal/urn/api_key.go). URN types wrap uuid.UUID and give callers compile-time protection against mixing ids from different subjects. Audit event structs require them for subject identifier fields (see gram-audit-logging); other consumers can adopt them opportunistically.

Test layout. Tests live in package <svc>_test (black-box). A single setup_test.go per service defines TestMain (calling testenv.Launch) and a newTestService(t) factory that clones a fresh test database, seeds an auth context, and returns the live *Service. Package-local helpers typically include withExactAccessGrants for scope setup and requireOopsCode for error-shape assertions. One <method>_test.go per handler.

Common code flows

Handler skeleton. Inside each method: extract authCtx from context → s.access.Require(...) → validate inputs → repo work → return mv.Build<Subject>View(...). Handlers never return repo types directly. For mutation handlers, wrap the repo work in a transaction — s.db.Begin(ctx) → defer o11y.NoLogDefer(func() error { return dbtx.Rollback(ctx) }) → repo writes → audit.Log* → dbtx.Commit(ctx) — so the audit row and the state it describes commit atomically. Read handlers typically don't need a transaction or audit call.

Cascading soft-deletes. When a delete handler tombstones a parent row whose children reference it, the children have to be soft-deleted in the same handler. ON DELETE CASCADE foreign keys only fire on hard deletes, so a soft-deleted parent otherwise leaves orphan children that still resolve in the active set and point at a tombstone. Run the child cleanup inside the same dbtx as the parent write so the cascade is atomic with it. Scope the cleanup query by both the parent id and project_id (per the postgresql skill) and filter on deleted IS FALSE so re-deletes are no-ops. If the child subject is independently audited, make the cleanup query :many with RETURNING * and emit one audit.Log<Verb> per affected row before the parent's audit event — see "How to audit a cascading delete of child resources" in gram-audit-logging. Tests should both assert no active children remain pointing at the deleted parent and assert the expected child audit-event delta.

Attach wiring. func Attach(mux goahttp.Muxer, service *Service) constructs gen.NewEndpoints(service), layers the middleware.MapErrors() and middleware.TraceMethods(tracer) middleware, and mounts the endpoints via srv.Mount(mux, srv.New(endpoints, mux, goahttp.RequestDecoder, goahttp.ResponseEncoder, nil, nil)).

Non-generated files

Substitute the service name for <svc> and the method name for <method>.

Generated files

Files under server/gen/** and any repo/ subdirectory carry a DO NOT EDIT header.

Server-client contract

The server's design authors the contract; clients receive it through generated OpenAPI, a TypeScript SDK, and CLI bindings. The contract is versioned through changesets.

HTTP routes. /rpc/<service>.<method>. Method names are derived from the Goa Service/Method names — renaming them is a breaking change for CLI and any direct HTTP callers.

OpenAPI. server/gen/http/openapi3.yaml is the raw Goa output (Goa also emits a sibling openapi3.json, but it is gitignored — nothing consumes it). .speakeasy/workflow.yaml defines two sources (Gram-Internal, Gram-Public) that apply overlays from .speakeasy/overlays/ to produce .speakeasy/out.openapi.yaml and .speakeasy/openapi-public.yaml. The TypeScript SDK is generated from the internal spec.

TypeScript SDK. client/dashboard/src/sdk/ — per-operation modules under src/funcs/, a per-service class under src/sdk/, React Query hooks under src/react-query/, and model types under src/models/{components,operations}/.

CLI bindings. server/gen/http/cli/gram/cli.go provides command bindings over the same endpoints.

Changesets. .changeset/<kebab-slug>.md with YAML frontmatter of the form "server": minor (or "dashboard": patch, etc.) and a one-paragraph body. A new endpoint is usually "server": minor; a bug fix or dashboard-only change is patch.

Regeneration. After any design change, run mise run gen:goa-server (server stubs, OpenAPI, CLI), then mise run gen:sdk (Speakeasy overlays, TypeScript SDK, the public OpenAPI output). gen:sdk accepts --check (fail if outputs drift), --skip-versioning (no version bump during iteration), and --skip-upload-spec (skip the Speakeasy registry upload).

Jobs to be done