mirror of https://github.com/usememos/memos.git
84 lines
3.0 KiB
Markdown
84 lines
3.0 KiB
Markdown
# Memos Codebase Guide
|
|
|
|
## Project Overview
|
|
|
|
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.
|
|
|
|
## Architecture Decision Context
|
|
|
|
**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
|
|
|
|
**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`)
|
|
|
|
**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)
|
|
|
|
## Critical Development Commands
|
|
|
|
**Backend:**
|
|
```bash
|
|
go run ./cmd/memos --mode dev --port 8081 # Start dev server
|
|
go test ./... # Run tests
|
|
golangci-lint run # Lint
|
|
```
|
|
|
|
**Frontend:**
|
|
```bash
|
|
cd web && pnpm dev # Start dev server
|
|
cd web && pnpm lint:fix # Lint and fix
|
|
cd web && pnpm release # Build and copy to backend
|
|
```
|
|
|
|
**Protocol Buffers:**
|
|
```bash
|
|
cd proto && buf generate # Regenerate Go + TypeScript from .proto
|
|
```
|
|
|
|
## Key Workflows
|
|
|
|
**Modifying APIs:**
|
|
1. Edit `.proto` files in `proto/api/v1/`
|
|
2. Run `buf generate` to regenerate code
|
|
3. Implement in `server/router/api/v1/`
|
|
4. Frontend types auto-update in `web/src/types/proto/`
|
|
|
|
**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
|
|
|
|
**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
|
|
|
|
## Critical Path Components
|
|
|
|
**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
|
|
|
|
## Testing Expectations
|
|
|
|
Go tests are required for store and API changes. Frontend relies on TypeScript checking and manual validation.
|
|
|
|
Run `go test ./store/...` and `go test ./server/router/api/v1/test/...` before committing backend changes.
|
|
|
|
## Configuration
|
|
|
|
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`
|