mirror of https://github.com/usememos/memos
chore: add CLAUDE.md
Steven
4 months ago
parent
8e8e246ab2
commit
4a20b529df
@ -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._
|
||||
Loading…
Reference in New Issue