Skip to content

armgit / memos

Public Imported from GitHub
0

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.

chore: update claude.md

Stevene8862e3ca981
diff --git a/CLAUDE.md b/CLAUDE.md
index bd32a86f4..3b7e9a2a8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,218 +1,236 @@
-# CLAUDE.md - Memos Project Documentation
+# CLAUDE.md
-## Project Overview
-
-**Memos** is a modern, open-source, self-hosted knowledge management and note-taking platform designed for privacy-conscious users and organizations. It provides a lightweight yet powerful solution for capturing, organizing, and sharing thoughts with comprehensive Markdown support and cross-platform accessibility.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-### Key Technologies
+## Project Overview
-- **Backend**: Go 1.24 with gRPC and Protocol Buffers
-- **Frontend**: React 18 with TypeScript, Vite, and Tailwind CSS
-- **Database**: SQLite (default), MySQL, PostgreSQL support
-- **API**: RESTful HTTP/gRPC with grpc-gateway
-- **Authentication**: JWT-based with OAuth2 providers
+Memos is a self-hosted note-taking and knowledge management platform with a Go backend and React/TypeScript frontend. The architecture follows clean separation of concerns with gRPC APIs, REST gateway, and database abstraction.
-## Architecture Overview
+## Development Commands
-### Backend Structure
+### Backend (Go)
+```bash
+# Run in development mode
+go run ./bin/memos/main.go --mode dev --port 8081
-```text
-server/
-├── router/
-│ ├── api/v1/ # API v1 services and handlers
-│ ├── frontend/ # Static frontend assets
-│ └── rss/ # RSS feed generation
-├── runner/ # Background job runners
-└── profiler/ # Performance profiling
-```
+# Build binary
+go build -o ./build/memos ./bin/memos/main.go
+# OR use build script
+./scripts/build.sh
-### Protocol Buffers & API
-
-```text
-proto/
-├── api/v1/ # Public API definitions
-│ ├── user_service.proto
-│ ├── workspace_service.proto
-│ ├── shortcut_service.proto
-│ ├── idp_service.proto
-│ └── webhook_service.proto
-└── store/ # Internal data structures
- ├── workspace_setting.proto
- ├── user_setting.proto
- └── ...
-```
+# Run tests
+go test -v ./...
+go test -cover ./...
-### Data Layer
-
-```text
-store/
-├── db/ # Database drivers
-│ ├── sqlite/
-│ ├── mysql/
-│ └── postgres/
-├── migration/ # Database migrations
-├── cache/ # Caching layer
-└── test/ # Test utilities
+# Run specific test packages
+go test -v ./store/test/
+go test -v ./server/router/api/v1/test/
```
-## Recent Major Refactoring: Google AIP Compliance
-
-### Overview
-
-We recently completed a comprehensive refactoring to align the API with Google API Improvement Proposals (AIP) for resource-oriented API design. This involved updating protocol buffers, backend services, and frontend TypeScript code.
-
-### Key Changes Made
-
-#### 1. Protocol Buffer Refactoring
-
-- **Resource Patterns**: Implemented standard resource naming (e.g., `users/{user}`, `workspace/settings/{setting}`)
-- **Field Behaviors**: Added proper field annotations (`REQUIRED`, `OUTPUT_ONLY`, `IMMUTABLE`)
-- **HTTP Annotations**: Updated REST mappings to follow RESTful conventions
-- **Service Consolidation**: Merged `workspace_setting_service.proto` into `workspace_service.proto`
-
-#### 2. Backend Service Updates
-
-- **Resource Name Handling**: Added robust parsing for resource names
-- **Method Signatures**: Updated to use resource names instead of raw IDs
-- **Error Handling**: Improved error responses with proper gRPC status codes
-- **Permission Checks**: Enhanced authorization based on user roles
+### Frontend (React/TypeScript)
+```bash
+cd web/
-#### 3. Frontend TypeScript Migration
+# Development server (http://localhost:3001)
+pnpm dev
-- **Resource Name Utilities**: Helper functions for extracting IDs from resource names
-- **State Management**: Updated MobX stores to use new resource formats
-- **Component Updates**: React components now handle new API structures
-- **Type Safety**: Enhanced TypeScript definitions for better type checking
+# Build for production
+pnpm build
-## Development Workflow
+# Build for release (outputs to server/router/frontend/dist)
+pnpm release
-### Code Quality Standards
+# Lint and type check
+pnpm lint
+```
-- **golangci-lint**: Comprehensive linting with 15+ linters enabled
-- **Protocol Buffer Generation**: `buf generate` for type-safe API generation
-- **Frontend Linting**: ESLint + TypeScript strict mode
+### Full Development Setup
+1. **Backend**: `go run ./bin/memos/main.go --mode dev --port 8081`
+2. **Frontend**: `cd web && pnpm dev`
+3. **Access**: Backend API at `http://localhost:8081`, Frontend at `http://localhost:3001`
-### Build Process
+## Architecture Overview
+### Backend Structure
+- **`/bin/memos/main.go`** - Application entrypoint with CLI and server initialization
+- **`/server/`** - HTTP/gRPC server with Echo framework and cmux for protocol multiplexing
+- **`/server/router/api/v1/`** - gRPC services with REST gateway via grpc-gateway
+- **`/store/`** - Data access layer with multi-database support (SQLite/PostgreSQL/MySQL)
+- **`/store/db/`** - Database-specific implementations with shared interface
+- **`/proto/`** - Protocol buffer definitions for APIs and data models
+- **`/internal/`** - Shared utilities, profile management, and version handling
+- **`/plugin/`** - Modular plugins (S3 storage, OAuth, webhooks, etc.)
+
+### Frontend Structure
+- **`/web/src/`** - React/TypeScript application
+- **`/web/src/components/`** - Reusable UI components with shadcn/ui
+- **`/web/src/pages/`** - Page-level components
+- **`/web/src/store/`** - MobX state management
+- **`/web/src/types/`** - TypeScript type definitions generated from protobuf
+
+### Key Architecture Patterns
+
+#### Server Architecture
+- **Protocol Multiplexing**: Single port serves both HTTP and gRPC via cmux
+- **gRPC-first**: Core APIs defined in protobuf, REST via grpc-gateway
+- **Layered**: Router → Service → Store → Database
+- **Middleware**: Authentication, logging, CORS handled via interceptors
+
+#### Database Layer
+- **Multi-database**: Unified interface for SQLite, PostgreSQL, MySQL
+- **Migration System**: Version-based schema migrations in `/store/migration/`
+- **Driver Pattern**: `/store/db/{sqlite,postgres,mysql}/` with common interface
+- **Caching**: Built-in cache layer for workspace settings, users, user settings
+
+#### Authentication & Security
+- **JWT-based**: Secret key generated per workspace
+- **gRPC Interceptors**: Authentication middleware for all API calls
+- **Context Propagation**: User context flows through request lifecycle
+- **Development vs Production**: Different secret handling based on mode
+
+## Database Operations
+
+### Supported Databases
+- **SQLite** (default): `--driver sqlite --data ./data`
+- **PostgreSQL**: `--driver postgres --dsn "postgres://..."`
+- **MySQL**: `--driver mysql --dsn "user:pass@tcp(host:port)/db"`
+
+### Migration System
+- Database schema managed via `/store/migration/{sqlite,postgres,mysql}/`
+- Automatic migration on startup via `store.Migrate(ctx)`
+- Version-based migration files (e.g., `0.22/00__memo_tags.sql`)
+
+## Testing Approach
+
+### Backend Testing
+- **Store Tests**: `/store/test/*_test.go` with in-memory SQLite
+- **API Tests**: `/server/router/api/v1/test/*_test.go` with full service setup
+- **Test Helpers**:
+ - `NewTestingStore()` for isolated database testing
+ - `NewTestService()` for API integration testing
+- **Test Patterns**: Context-based authentication, proper cleanup, realistic data
+
+### Frontend Testing
+- Currently relies on TypeScript compilation and ESLint
+- No dedicated test framework configured
+
+### Running Tests
```bash
-# Backend build
-sh ./scripts/build.sh
-
-# Frontend build
-cd web && pnpm build
+# All tests
+go test -v ./...
-# Protocol buffer generation
-cd proto && buf generate
+# Specific packages
+go test -v ./store/test/
+go test -v ./server/router/api/v1/test/
-# Linting
-golangci-lint run --timeout=3m
-cd web && pnpm lint
+# With coverage
+go test -cover ./...
```
-### Testing Commands
+## Development Modes
+### Production Mode
```bash
-# Run all tests
-go test ./...
-
-# Specific service tests
-go test ./server/router/api/v1/... -v
-
-# Test with coverage
-go test -cover ./...
+go run ./bin/memos/main.go --mode prod --port 5230
```
+- Uses workspace-generated secret key
+- Serves built frontend from `/server/router/frontend/dist/`
+- Optimized for deployment
-## Frontend Architecture
-
-### Technology Stack
-
-- **React 18**: Modern React with hooks and functional components
-- **TypeScript**: Strict type checking for better development experience
-- **Vite**: Fast build tool and development server
-- **Tailwind CSS**: Utility-first CSS framework
-- **MobX**: State management for reactive data flows
-
-### Key Components
-
-```text
-web/src/
-├── components/ # Reusable UI components
-├── pages/ # Route-based page components
-├── store/ # MobX state management
-│ └── v2/ # Updated stores for AIP compliance
-├── types/ # TypeScript type definitions
-│ └── proto/ # Generated from Protocol Buffers
-└── utils/ # Utility functions and helpers
+### Development Mode
+```bash
+go run ./bin/memos/main.go --mode dev --port 8081
```
+- Fixed secret key "usememos"
+- Enables debugging features
+- Separate frontend development server recommended
-## API Design Principles
-
-### Resource-Oriented Design
-
-Following Google AIP standards:
-
-- **Resource Names**: Hierarchical, human-readable identifiers
-- **Standard Methods**: List, Get, Create, Update, Delete patterns
-- **Field Behaviors**: Clear annotations for API contracts
-- **HTTP Mapping**: RESTful URL structures
-
-### Error Handling
-
-- **gRPC Status Codes**: Proper error classification
-- **Detailed Messages**: Helpful error descriptions
-- **Field Validation**: Input validation with clear feedback
-
-### Authentication & Authorization
-
-- **JWT Tokens**: Stateless authentication
-- **Role-Based Access**: Host, User role differentiation
-- **Context Propagation**: User context through request pipeline
-
-## Database Schema
-
-### Core Entities
-
-- **Users**: User accounts with roles and permissions
-- **Workspaces**: Workspace configuration and settings
-- **Identity Providers**: OAuth2 and other auth providers
-- **Webhooks**: External integration endpoints
-- **Shortcuts**: User-defined quick actions
-
-### Migration Strategy
-
-- **Version-Controlled**: Database schema changes tracked
-- **Multi-Database**: Support for SQLite, MySQL, PostgreSQL
-- **Backward Compatibility**: Careful migration planning
-
-## Deployment Options
-
-### Docker
-
-```dockerfile
-# Multi-stage build for optimized images
-FROM golang:1.24-alpine AS backend
-FROM node:18-alpine AS frontend
-FROM alpine:latest AS production
+### Demo Mode
+```bash
+go run ./bin/memos/main.go --mode demo
```
-
-### Configuration
-
-- **Environment Variables**: Runtime configuration
-- **Profile-Based**: Development, staging, production profiles
-- **Database URLs**: Flexible database connection strings
-
-## Contributing Guidelines
-
-### Code Standards
-
-1. **Protocol Buffers**: Follow AIP guidelines for new services
-2. **Go Code**: Use `golangci-lint` configuration
-3. **TypeScript**: Strict mode with comprehensive type checking
-4. **Testing**: Write tests for new features using TestService helpers
-
-### Pull Request Process
-
-1. **Lint Checking**: All linters must pass
-2. **Test Coverage**: New code should include tests
-3. **Documentation**: Update relevant documentation
-4. **AIP Compliance**: New APIs should follow [AIP](https://google.aip.dev/) standards
+- Specialized configuration for demonstration purposes
+
+## Key Configuration
+
+### Environment Variables
+All CLI flags can be set via environment variables with `MEMOS_` prefix:
+- `MEMOS_MODE` - Server mode (dev/prod/demo)
+- `MEMOS_PORT` - Server port
+- `MEMOS_DATA` - Data directory
+- `MEMOS_DRIVER` - Database driver
+- `MEMOS_DSN` - Database connection string
+- `MEMOS_INSTANCE_URL` - Public instance URL
+
+### Runtime Configuration
+- **Profile**: `/internal/profile/` handles configuration validation
+- **Secrets**: Auto-generated workspace secret in production
+- **Data Directory**: Configurable storage location for SQLite and assets
+
+## Frontend Technology Stack
+
+### Core Framework
+- **React 18** with TypeScript
+- **Vite** for build tooling and development server
+- **React Router** for navigation
+- **MobX** for state management
+
+### UI Components
+- **Radix UI** primitives for accessibility
+- **Tailwind CSS** for styling with custom themes
+- **Lucide React** for icons
+- **shadcn/ui** component patterns
+
+### Key Libraries
+- **dayjs** for date manipulation
+- **highlight.js** for code syntax highlighting
+- **katex** for math rendering
+- **mermaid** for diagram rendering
+- **react-leaflet** for maps
+- **i18next** for internationalization
+
+## Protocol Buffer Workflow
+
+### Code Generation
+- **Source**: `/proto/api/v1/*.proto` and `/proto/store/*.proto`
+- **Generated**: `/proto/gen/` for Go, `/web/src/types/proto/` for TypeScript
+- **Build Tool**: Buf for protobuf compilation
+- **API Docs**: Generated swagger at `/proto/gen/apidocs.swagger.yaml`
+
+### API Design
+- gRPC services in `/proto/api/v1/`
+- Resource-oriented design (User, Memo, Attachment, etc.)
+- REST gateway auto-generated from protobuf annotations
+
+## File Organization Principles
+
+### Backend
+- **Domain-driven**: Each entity (user, memo, attachment) has dedicated files
+- **Layered**: Clear separation between API, business logic, and data layers
+- **Database-agnostic**: Common interfaces with driver-specific implementations
+
+### Frontend
+- **Component-based**: Reusable components in `/components/`
+- **Feature-based**: Related functionality grouped together
+- **Type-safe**: Strong TypeScript integration with generated protobuf types
+
+## Common Development Workflows
+
+### Adding New API Endpoint
+1. Define service method in `/proto/api/v1/{service}.proto`
+2. Generate code: `buf generate`
+3. Implement service method in `/server/router/api/v1/{service}_service.go`
+4. Add any required store methods in `/store/{entity}.go`
+5. Update database layer if needed in `/store/db/{driver}/{entity}.go`
+
+### Database Schema Changes
+1. Create migration file in `/store/migration/{driver}/{version}/`
+2. Update store interface in `/store/{entity}.go`
+3. Implement in each database driver
+4. Update protobuf if external API changes needed
+
+### Frontend Component Development
+1. Create component in `/web/src/components/`
+2. Follow existing patterns for styling and state management
+3. Use TypeScript for type safety
+4. Import and use in pages or other components
\ No newline at end of file