happyz
/
memos
mirror of https://github.com/usememos/memos.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
memos/CLAUDE.md

3.0 KiB
Raw Permalink Blame History

Memos Codebase Guide

Project Overview

Memos is a self-hosted knowledge management platform with a Go backend and React frontend. The architecture uses gRPC for internal communication with REST access via gRPC-Gateway.

Architecture Decision Context

Why gRPC + gRPC-Gateway?

  • Native gRPC for performance, REST API for compatibility
  • Both protocols served on same port via cmux connection multiplexer
  • Frontend uses gRPC-Web (nice-grpc-web) for type-safe API calls

Why multi-database support?

  • Store interface (store/driver.go) abstracts persistence
  • Three implementations: SQLite (default), MySQL, PostgreSQL
  • Each driver has its own migration files in store/db/{driver}/migration/
  • Schema version tracked in instance_setting table (key: bb.general.version)

Why MobX for frontend state?

  • Simpler than Redux for this application's needs
  • Stores in web/src/store/ handle global state (user, memos, editor, dialogs)

Critical Development Commands

Backend:

go run ./cmd/memos --mode dev --port 8081    # Start dev server
go test ./...                                 # Run tests
golangci-lint run                            # Lint

Frontend:

cd web && pnpm dev                           # Start dev server
cd web && pnpm lint:fix                      # Lint and fix
cd web && pnpm release                       # Build and copy to backend

Protocol Buffers:

cd proto && buf generate                     # Regenerate Go + TypeScript from .proto

Key Workflows

Modifying APIs:

  1. Edit .proto files in proto/api/v1/
  2. Run buf generate to regenerate code
  3. Implement in server/router/api/v1/
  4. Frontend types auto-update in web/src/types/proto/

Database Schema Changes:

  1. Create migration files: store/migration/{sqlite,mysql,postgres}/{version}/NN__description.sql
  2. Update LATEST.sql in each driver directory
  3. Schema version auto-determined from migration files
  4. If adding new tables/models, also update store/driver.go interface and implementations

Authentication Flow:

  • Interceptor runs on all gRPC methods (server/router/api/v1/acl.go)
  • Public endpoints listed in acl_config.go
  • Supports both session cookies and JWT bearer tokens

Critical Path Components

Entry point: cmd/memos/ starts the server API layer: server/router/api/v1/ implements gRPC services Data layer: store/ handles all persistence Frontend: web/src/ React app with MobX state management

Testing Expectations

Go tests are required for store and API changes. Frontend relies on TypeScript checking and manual validation.

Run go test ./store/... and go test ./server/router/api/v1/test/... before committing backend changes.

Configuration

Backend accepts flags or MEMOS_* environment variables:

  • --mode / MEMOS_MODE: dev, prod, demo
  • --port / MEMOS_PORT: HTTP/gRPC port (default: 5230)
  • --data / MEMOS_DATA: Data directory (default: ~/.memos)
  • --driver / MEMOS_DRIVER: sqlite, mysql, postgres