Protocol Buffer Development

Relevant source files

• proto/api/v1/attachment_service.proto
• proto/api/v1/shortcut_service.proto
• proto/buf.gen.yaml
• proto/gen/api/v1/apiv1connect/shortcut_service.connect.go
• proto/gen/api/v1/attachment_service.pb.go
• proto/gen/api/v1/shortcut_service.pb.go
• proto/gen/api/v1/shortcut_service_grpc.pb.go
• server/router/api/v1/acl_config.go
• server/router/api/v1/acl_config_test.go
• server/router/api/v1/authz_test.go
• server/router/api/v1/connect_services.go
• server/router/api/v1/test/authz_test.go
• web/src/types/proto/api/v1/attachment_service_pb.ts
• web/src/types/proto/api/v1/auth_service_pb.ts
• web/src/types/proto/api/v1/common_pb.ts
• web/src/types/proto/api/v1/idp_service_pb.ts
• web/src/types/proto/api/v1/shortcut_service_pb.ts
• web/src/types/proto/google/api/annotations_pb.ts
• web/src/types/proto/google/api/client_pb.ts
• web/src/types/proto/google/api/field_behavior_pb.ts

This guide covers the development workflow for Protocol Buffer (protobuf) definitions in Memos, including how to define new services and messages, generate code, and maintain API contracts.

Protocol Buffer File Structure

The Memos codebase uses Protocol Buffers v3 to define all API contracts. Proto files are organized by service domain:

proto/
├── api/v1/                          # API version 1 definitions
│   ├── instance_service.proto       # Instance configuration and stats
│   ├── user_service.proto           # User management and settings
│   ├── memo_service.proto           # Memo CRUD and operations
│   ├── attachment_service.proto     # File attachment management
│   └── ...
└── store/                           # Internal storage types
    ├── instance_setting.proto       # Instance settings storage schema
    └── user_setting.proto           # User settings storage

Generated Code Locations:

Language	Output Directory	Purpose
Go	proto/gen/api/v1/	Server-side service implementation
Go (Store)	proto/gen/store/	Internal storage serialization
TypeScript	web/src/types/proto/api/v1/	Client-side type definitions
OpenAPI	proto/gen/openapi.yaml	API documentation and MCP tools

Sources: proto/api/v1/attachment_service.proto1-13 proto/api/v1/shortcut_service.proto1-13 proto/buf.gen.yaml1-30

---

Code Generation Pipeline

The codebase uses buf for managing protocol buffer compilation. Generation is configured in buf.gen.yaml and executed via the buf generate command. This pipeline generates Go code for gRPC and Connect RPC, as well as TypeScript types for the frontend using the protoc-gen-es plugin.

Diagram: Code Generation Pipeline

Sources: proto/buf.gen.yaml1-31 proto/gen/api/v1/attachment_service.pb.go1-15 web/src/types/proto/api/v1/attachment_service_pb.ts1-19

---

Service and Message Architecture

Service Definition Structure

Services in Memos follow Google's API Improvement Proposals (AIP) conventions, utilizing resource names and standard methods.

Diagram: Service Definition to Backend Implementation

Sources: proto/api/v1/attachment_service.proto15-23 proto/gen/api/v1/attachment_service.pb.go205-220 server/router/api/v1/connect_services.go12-24

API Access Control (ACL)

Memos implements a centralized Access Control List (ACL) for API methods. This is managed in server/router/api/v1/acl_config.go. Methods are categorized into PublicMethods and AuthBootstrapMethods.

• PublicMethods: Accessible without any authentication server/router/api/v1/acl_config.go11-41
• AuthBootstrapMethods: A subset of public methods allowed even when an instance is set to private (e.g., SignIn, CreateUser) server/router/api/v1/acl_config.go56-74

Table: Method Access Examples

Method Path	Category	Reason
/memos.api.v1.AuthService/SignIn	Bootstrap	Required for login on private instances
/memos.api.v1.MemoService/ListMemos	Public	Browsing public content
/memos.api.v1.MemoService/CreateMemo	Protected	Requires valid session/token

Sources: server/router/api/v1/acl_config.go11-74 server/router/api/v1/acl_config_test.go44-67

---

Implementation Details

Connect RPC Integration

Memos uses Connect RPC to bridge gRPC and web clients. The ConnectServiceHandler in server/router/api/v1/connect_services.go acts as a proxy, delegating calls to the underlying APIV1Service implementation.

Example delegation from server/router/api/v1/connect_services.go18-24:

Authorization Logic

The Authorizer struct evaluates whether a request identity (from Authenticate) has permission to execute a specific procedure (the full gRPC method path).

Diagram: Authorization Data Flow

Sources: server/router/api/v1/acl_config.go45-48 server/router/api/v1/test/authz_test.go25-43 server/router/api/v1/authz_test.go16-57

---

Development Workflow Commands

Generating Code

When modifying .proto files, run buf generate from the root directory. This updates:

• Go gRPC/Connect code in proto/gen/.
• TypeScript definitions in web/src/types/proto/.
• OpenAPI documentation in proto/gen/openapi.yaml.

Field Behavior and Resource Definitions

API definitions use Google API annotations for validation and documentation:

• google.api.field_behavior = REQUIRED: Marks mandatory fields proto/api/v1/attachment_service.proto92
• google.api.resource: Defines the resource type and pattern proto/api/v1/attachment_service.proto77-82
• google.api.http: Maps RPC methods to RESTful HTTP paths proto/api/v1/attachment_service.proto18-21

Example Resource Definition from proto/api/v1/shortcut_service.proto22-26:

Sources: proto/api/v1/attachment_service.proto76-82 web/src/types/proto/api/v1/shortcut_service_pb.ts24-31 proto/buf.gen.yaml1-31