Skip to content

C
canifa_note
Commit a8631542 authored by Johnny's avatar Johnny
Browse files
Options

docs: update Memos Codebase Guide for clarity and structure

parent 06102575
Hide whitespace changes
Inline Side-by-side
Showing with 52 additions and 316 deletions
CLAUDE.md
View file @ a8631542
# 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`
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment