From 4a20b529df6a992e4ae05e14def35485143dd179 Mon Sep 17 00:00:00 2001 From: Steven Date: Tue, 17 Jun 2025 08:51:43 +0800 Subject: [PATCH] chore: add CLAUDE.md --- CLAUDE.md | 237 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..231f8401e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,237 @@ +# CLAUDE.md - Memos Project Documentation + +## 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. + +### Key Technologies + +- **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 + +## Architecture Overview + +### Backend Structure + +```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 +``` + +### 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 + └── ... +``` + +### Data Layer + +```text +store/ +├── db/ # Database drivers +│ ├── sqlite/ +│ ├── mysql/ +│ └── postgres/ +├── migration/ # Database migrations +├── cache/ # Caching layer +└── test/ # Test utilities +``` + +## 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 + +#### 3. Frontend TypeScript Migration + +- **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 + +## Development Workflow + +### Code Quality Standards + +- **golangci-lint**: Comprehensive linting with 15+ linters enabled +- **Protocol Buffer Generation**: `buf generate` for type-safe API generation +- **Frontend Linting**: ESLint + TypeScript strict mode + +### Build Process + +```bash +# Backend build +sh ./scripts/build.sh + +# Frontend build +cd web && pnpm build + +# Protocol buffer generation +buf generate + +# Linting +golangci-lint run --timeout=3m +cd web && pnpm lint +``` + +### Testing Commands + +```bash +# Run all tests +go test ./... + +# Specific service tests +go test ./server/router/api/v1/... -v + +# Test with coverage +go test -cover ./... +``` + +## 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 +``` + +## 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 +``` + +### 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 standards + +## Future Considerations + +### Planned Improvements + +- **Additional Service Tests**: Expand test coverage to all services +- **API Versioning**: Support for multiple API versions +- **Enhanced Metrics**: Better observability and monitoring +- **Plugin System**: Extensible architecture for custom features + +### Technical Debt + +- **Legacy API Cleanup**: Remove deprecated endpoints +- **Performance Optimization**: Database query optimization +- **Security Hardening**: Enhanced security measures + +--- + +_This documentation reflects the current state of the Memos project as of June 2025, including recent AIP compliance refactoring and comprehensive testing infrastructure._