Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.
Go dockerfossgomarkdownmemomicroblognote-takingnotesopen-sourceown-your-datareactself-hostedsqlitetimeline
docs: update Memos Codebase Guide for clarity and structure
Johnnya86315422484
diff --git a/CLAUDE.md b/CLAUDE.mdindex a0686152d..053cabd41 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,347 +1,83 @@-# CLAUDE.md--This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.+# Memos Codebase Guide## Project Overview-Memos is a lightweight, self-hosted knowledge management and note-taking platform. The architecture pairs a Go backend with a React+Vite frontend, using gRPC for internal communication and providing REST API access via gRPC-Gateway.+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.-## Development Commands+## Architecture Decision Context-### Backend (Go)+**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-**Start Development Server:**-```bash-go run ./cmd/memos --mode dev --port 8081-```--**Build Binary:**-```bash-go build ./cmd/memos-```+**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`)-**Run Tests:**-```bash-go test ./... # All tests-go test ./store/... # Store layer tests only-go test ./server/router/api/v1/test/... # API tests-```+**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)-**Lint:**-```bash-golangci-lint run # Full lint check (uses .golangci.yaml)-```+## Critical Development Commands-**Generate Protocol Buffers:**-```bash-cd proto-buf generate # Generate Go/TypeScript from .proto files-buf format -w # Format proto files-```--### Frontend (React + Vite)--**Install Dependencies:**-```bash-cd web-pnpm install-```--**Development Server:**+**Backend:**```bash-cd web-pnpm dev # Hot-reload dev server (typically :5173)+go run ./cmd/memos --mode dev --port 8081 # Start dev server+go test ./... # Run tests+golangci-lint run # Lint```-**Build:**+**Frontend:**```bash-cd web-pnpm build # Build to web/dist/-pnpm release # Build and copy to server/router/frontend/dist/+cd web && pnpm dev # Start dev server+cd web && pnpm lint:fix # Lint and fix+cd web && pnpm release # Build and copy to backend```-**Lint and Format:**+**Protocol Buffers:**```bash-cd web-pnpm lint # TypeScript check + Biome lint-pnpm lint:fix # Auto-fix linting issues-pnpm format # Format code with Biome+cd proto && buf generate # Regenerate Go + TypeScript from .proto```-### CLI Flags and Environment Variables--The backend accepts the following configuration via flags or `MEMOS_*` environment variables:--- `--mode` / `MEMOS_MODE` - Runtime mode: `dev`, `prod`, `demo` (default: `prod`)-- `--addr` / `MEMOS_ADDR` - Bind address (default: `0.0.0.0`)-- `--port` / `MEMOS_PORT` - HTTP/gRPC port (default: `5230`)-- `--unix-sock` / `MEMOS_UNIX_SOCK` - Unix socket path (optional)-- `--data` / `MEMOS_DATA` - Data directory for SQLite (default: `~/.memos`)-- `--driver` / `MEMOS_DRIVER` - Database driver: `sqlite`, `mysql`, `postgres` (default: `sqlite`)-- `--dsn` / `MEMOS_DSN` - Database connection string (for MySQL/PostgreSQL)-- `--instance-url` / `MEMOS_INSTANCE_URL` - Public instance URL for webhooks/OAuth--## Architecture--### High-Level Structure--```-cmd/memos/ # CLI entry point, starts HTTP+gRPC server-server/ # HTTP server and routing- ├── router/api/v1/ # gRPC services + gRPC-Gateway REST handlers- ├── router/frontend/ # Embedded SPA static file serving- └── router/rss/ # RSS feed generation-internal/ # Shared domain logic and utilities- ├── base/ # Base types and constants- ├── profile/ # Configuration profile handling- ├── util/ # Utility functions- └── version/ # Version information-store/ # Data persistence layer (repository pattern)- ├── db/ # Database driver implementations- │ ├── sqlite/ # SQLite driver + migrations- │ ├── mysql/ # MySQL driver + migrations- │ └── postgres/ # PostgreSQL driver + migrations- └── cache/ # In-memory caching-proto/ # Protocol Buffer definitions- └── api/v1/ # API service contracts (.proto files)-web/ # Frontend React application- ├── src/- │ ├── components/ # React components- │ ├── pages/ # Page-level components- │ ├── store/ # MobX state management- │ ├── router/ # React Router configuration- │ ├── locales/ # i18n translation files- │ ├── hooks/ # Custom React hooks- │ └── utils/ # Utility functions- └── public/ # Static assets-```--### API Architecture--**Dual Protocol Serving:**-The server uses `cmux` (connection multiplexer) to serve both gRPC and HTTP on the same port:-- **HTTP/2 + `application/grpc`** → Native gRPC server-- **HTTP/1.1** → Echo server (REST API via gRPC-Gateway, static files, RSS)--**API Services** (defined in `proto/api/v1/*.proto`):-- `InstanceService` - Instance settings and profiles-- `AuthService` - Authentication and session management-- `UserService` - User management-- `MemoService` - Core memo CRUD operations-- `AttachmentService` - File uploads and storage-- `InboxService` - Inbox items-- `ActivityService` - Activity logging-- `MarkdownService` - Markdown utilities (link metadata, etc.)-- `IdentityProviderService` - OAuth/SSO providers-- `ShortcutService` - User shortcuts--**API Access Methods:**-1. **Native gRPC** - Direct gRPC calls to `memos.api.v1.*` services-2. **REST API** - HTTP REST at `/api/v1/*` (via gRPC-Gateway)-3. **gRPC-Web** - Browser gRPC calls to `/memos.api.v1.*` (via grpc-web proxy)--### Database Layer--**Store Interface:**-The `store.Driver` interface (`store/driver.go`) defines all data access methods. Three implementations exist:-- `store/db/sqlite/` - SQLite driver (default, embedded database)-- `store/db/mysql/` - MySQL driver-- `store/db/postgres/` - PostgreSQL driver--**Migrations:**-Each driver contains its own migration files in subdirectories. Schema version tracking is stored in `instance_setting` (key: `bb.general.version`). The `store/migrator.go` orchestrates migrations across all drivers.--**Key Models:**-- `Memo` - Core note/memo entity-- `User` - User accounts-- `Attachment` - Uploaded files and images-- `MemoRelation` - Graph relationships between memos-- `Activity` - Activity log entries-- `Inbox` - Inbox items-- `Reaction` - Emoji reactions-- `InstanceSetting` - Instance-level configuration-- `UserSetting` - User preferences-- `IdentityProvider` - OAuth/SSO provider configs--### Frontend Architecture--**Tech Stack:**-- **Framework:** React 18 with TypeScript-- **Build Tool:** Vite 7-- **Routing:** React Router 7-- **State Management:** MobX-- **Styling:** Tailwind CSS 4 + Emotion-- **UI Components:** Radix UI primitives-- **i18n:** react-i18next with language files in `web/src/locales/`--**State Management:**-MobX stores in `web/src/store/` handle global state:-- `userStore` - Current user session-- `memoStore` - Memo collection and filters-- `editorStore` - Memo editor state-- `dialogStore` - Modal dialogs-- etc.--**gRPC-Web Client:**-The frontend uses `nice-grpc-web` to call backend services. Client setup is in `web/src/grpcweb.ts`.--### Authentication--**Dual Auth Support:**-1. **Session-based (Cookie):** `user_session` cookie with format `{userID}-{sessionID}`-2. **Token-based (JWT):** `Authorization: Bearer <token>` header--**Flow:**-- Authentication interceptor (`server/router/api/v1/acl.go`) runs on all gRPC methods-- Public endpoints bypass auth (see `acl_config.go` for allowlist)-- Context values set: `userIDContextKey`, `sessionIDContextKey`, `accessTokenContextKey`-- Sessions have sliding expiration (14 days from last access)--## Code Style and Conventions--### Go--- **Formatting:** All code must be `gofmt`-compliant (tabs for indentation)-- **Imports:** Group stdlib, external, and local imports (enforced by `goimports`)-- **Error Handling:** Wrap errors with `%w` when propagating: `errors.Wrap(err, "context")`-- **Naming:** Package names lowercase, no underscores-- **Linting:** Enforced via `.golangci.yaml` (revive, staticcheck, gocritic, etc.)--### TypeScript/React--- **Components:** PascalCase filenames (e.g., `MemoEditor.tsx`)-- **Hooks:** camelCase filenames (e.g., `useMemoList.ts`)-- **Formatting:** Biome enforced (see `web/biome.json`)-- **Import Ordering:** Automatic via Biome's organize imports-- **Styling:** Tailwind utility classes preferred over custom CSS-- **Linting:** Biome replaces ESLint and Prettier for faster, unified tooling--### Commit Messages--Follow Conventional Commits format:-- `feat(scope): description` - New features-- `fix(scope): description` - Bug fixes-- `chore(scope): description` - Maintenance tasks-- `refactor(scope): description` - Code restructuring-- `test(scope): description` - Test additions/fixes-- `docs(scope): description` - Documentation updates--Scopes: `server`, `api`, `store`, `web`, `proto`, etc.--## Testing--**Go Tests:**-- Test files: `*_test.go` alongside source files-- Run specific package: `go test ./store/cache/...`-- API integration tests: `server/router/api/v1/test/*_test.go`-- Prefer table-driven tests for multiple test cases--**Frontend:**-Currently relies on linting and manual testing. For UI changes, validate with local dev server.--## Protocol Buffer Workflow--**Prerequisites:** Install [buf](https://docs.buf.build/installation)+## Key Workflows**Modifying APIs:**1. Edit `.proto` files in `proto/api/v1/`-2. Run `cd proto && buf generate` to regenerate Go and TypeScript code-3. Update service implementations in `server/router/api/v1/`-4. Update frontend gRPC-Web clients in `web/src/`--**Generated Code Locations:**-- Go: `proto/gen/api/v1/`-- TypeScript: `web/src/types/proto/api/v1/`--## Database Migrations--When adding database schema changes:--1. Create migration file in driver-specific directory:- - SQLite: `store/db/sqlite/migration/`- - MySQL: `store/db/mysql/migration/`- - PostgreSQL: `store/db/postgres/migration/`--2. Follow naming: `prod_YYYYMMDD_description.sql`--3. Update schema version constant in `store/migrator.go`--4. Test migration locally with all three database drivers--## Common Patterns--### Adding a New API Endpoint--1. Define service method in `proto/api/v1/{service}_service.proto`2. Run `buf generate` to regenerate code-3. Implement method in `server/router/api/v1/{service}_service.go`-4. Add to public allowlist in `acl_config.go` if unauthenticated-5. Update frontend client in `web/src/`--### Adding a New Data Model+3. Implement in `server/router/api/v1/`+4. Frontend types auto-update in `web/src/types/proto/`-1. Define struct in `store/{model}.go`-2. Add CRUD methods to `store.Driver` interface in `store/driver.go`-3. Implement methods in each driver:- - `store/db/sqlite/{model}.go`- - `store/db/mysql/{model}.go`- - `store/db/postgres/{model}.go`-4. Create migration files for schema changes-5. Add tests in `store/test/{model}_test.go`+**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-### Frontend Data Fetching+**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-Use gRPC-Web client from `web/src/grpcweb.ts`:+## Critical Path Components-```typescript-import { memoServiceClient } from "@/grpcweb";+**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-const response = await memoServiceClient.listMemos({- filter: "creator == 'users/1'",-});-```--State is typically managed in MobX stores (`web/src/store/`).--## Production Deployment+## Testing Expectations-**Docker (Recommended):**-```bash-docker run -d \- --name memos \- -p 5230:5230 \- -v ~/.memos:/var/opt/memos \- neosmemo/memos:stable-```+Go tests are required for store and API changes. Frontend relies on TypeScript checking and manual validation.-**From Source:**-1. Build frontend: `cd web && pnpm install && pnpm release`-2. Build backend: `go build -o memos ./cmd/memos`-3. Run: `./memos --mode prod --port 5230`+Run `go test ./store/...` and `go test ./server/router/api/v1/test/...` before committing backend changes.-**Data Directory:**-For SQLite (default), all data is stored in the directory specified by `--data` flag. This includes:-- `memos_prod.db` - SQLite database-- `assets/` - Uploaded files (unless using S3-compatible storage)+## Configuration-## Key Dependencies--**Backend:**-- `github.com/spf13/cobra` - CLI framework-- `github.com/spf13/viper` - Configuration management-- `google.golang.org/grpc` - gRPC server-- `github.com/grpc-ecosystem/grpc-gateway/v2` - REST gateway-- `github.com/labstack/echo/v4` - HTTP server-- `github.com/soheilhy/cmux` - Connection multiplexing-- `modernc.org/sqlite` - Pure Go SQLite driver-- `github.com/golang-jwt/jwt/v5` - JWT authentication--**Frontend:**-- `react` / `react-dom` - UI framework-- `react-router-dom` - Routing-- `mobx` / `mobx-react-lite` - State management-- `tailwindcss` - Styling-- `@biomejs/biome` - Fast linter and formatter (replaces ESLint + Prettier)-- `nice-grpc-web` - gRPC-Web client-- `@radix-ui/*` - Headless UI components-- `react-i18next` - Internationalization+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`