Project Structure and Build System

Relevant source files

• .github/workflows/backend-tests.yml
• .github/workflows/build-canary-image.yml
• .github/workflows/build-stable-image.yml
• .github/workflows/demo-deploy.yml
• .github/workflows/frontend-tests.yml
• .github/workflows/proto-linter.yml
• .github/workflows/stale.yml
• go.mod
• go.sum
• scripts/Dockerfile
• scripts/entrypoint.sh
• scripts/entrypoint_test.sh
• server/server.go
• web/package.json
• web/pnpm-lock.yaml

This document describes the repository's directory layout, build tooling, and development workflows. It covers the frontend build system (pnpm + Vite), backend build system (Go), Docker containerization, and the CI/CD pipeline that produces multi-architecture images.

For deployment-specific configuration and running the application, see Docker and Container Deployment. For contributing and setting up a local development environment, see Setting Up Development Environment.

---

Repository Layout

The repository follows a monorepo structure with clear separation between frontend, backend, and infrastructure concerns:

Sources: web/package.json server/server.go scripts/Dockerfile

Key Directories

Directory	Purpose	Key Files
web/	Frontend application (React + TypeScript)	package.json, vite.config.ts, tsconfig.json
server/	Backend application (Go)	server.go, router/, service/
proto/	Protocol buffer definitions shared between frontend/backend	api/, store/
store/	Database abstraction layer and driver implementations	db.go, driver/
cmd/memos/	Main executable entry point	main.go
internal/	Internal-only packages (profile, log, util)	profile/, log/, util/
plugin/	Plugin system (webhooks, storage, etc.)	webhook/, storage/
scripts/	Build and deployment scripts	Dockerfile, entrypoint.sh
.github/workflows/	CI/CD pipeline definitions	*.yml

Sources: Repository structure from all provided files

---

Frontend Build System

The frontend uses pnpm as the package manager and Vite as the build tool. The build system is configured for both development and production builds.

Package Manager: pnpm

The project requires pnpm version 10 and Node.js 22 as specified in .github/workflows/frontend-tests.yml16-17

Key configuration in web/package.json94-97:

This ensures that only esbuild is built from source during installation, which is necessary for platform compatibility.

Build Scripts

The web/package.json4-10 defines the following npm scripts:

Script	Command	Purpose
dev	vite	Start development server with HMR
build	vite build	Production build to web/dist/
release	vite build --mode release --outDir=../server/router/frontend/dist --emptyOutDir	Production build for embedding in Go binary
lint	tsc --noEmit --skipLibCheck && biome check src	Type-check and lint
lint:fix	biome check --write src	Auto-fix linting issues
format	biome format --write src	Format code

The release script is the critical build command used in CI/CD. It:

1. Runs Vite in release mode
2. Outputs to ../server/router/frontend/dist/ (outside the web/ directory)
3. Uses --emptyOutDir to clear the output directory first

Sources: web/package.json4-10

Build Tool: Vite

Vite configuration includes:

• React plugin with Fast Refresh for development
• Tailwind CSS via @tailwindcss/vite plugin
• Code splitting for optimal loading
• Minification with Terser in production
• Source maps for debugging

The build output consists of:

• index.html - Entry point
• assets/ - JavaScript bundles, CSS, and static assets
• All files are hashed for cache-busting

Sources: web/package.json87 web/package.json29

TypeScript Configuration

The frontend uses TypeScript 5.9.3 (web/package.json91) with:

• Strict type checking enabled
• React JSX transform
• Path aliases for cleaner imports
• skipLibCheck for faster compilation

Sources: web/package.json91 web/package.json8

Linting and Formatting

Biome (web/package.json72) is used for both linting and formatting, replacing ESLint and Prettier:

• Faster than traditional tools
• Single configuration file
• Consistent formatting rules

The CI pipeline runs pnpm lint to enforce code quality (.github/workflows/frontend-tests.yml44-45).

Sources: web/package.json72 web/package.json9-10 .github/workflows/frontend-tests.yml44-45

---

Backend Build System

The backend is built using standard Go 1.25.7 tooling with no external build systems required.

Dependency Management

Dependencies are managed via Go modules:

• go.mod3 specifies go 1.25.7
• go.sum contains cryptographic checksums for all dependencies
• go mod download caches dependencies
• go mod tidy ensures consistency

The CI pipeline verifies that go.mod is tidy (.github/workflows/backend-tests.yml35-38):

Sources: go.mod3 .github/workflows/backend-tests.yml35-38

Key Dependencies

Dependency	Version	Purpose
github.com/labstack/echo/v5	v5.0.3	HTTP server framework
connectrpc.com/connect	v1.19.1	gRPC implementation
github.com/grpc-ecosystem/grpc-gateway/v2	v2.27.2	HTTP/JSON to gRPC gateway
modernc.org/sqlite	v1.38.2	Pure-Go SQLite driver
github.com/go-sql-driver/mysql	v1.9.3	MySQL driver
github.com/lib/pq	v1.10.9	PostgreSQL driver
github.com/aws/aws-sdk-go-v2	v1.39.2	S3 storage integration
golang.org/x/crypto	v0.47.0	Password hashing
google.golang.org/protobuf	v1.36.9	Protocol buffer runtime

Sources: go.mod5-38

Build Command

The standard Go build command is used in scripts/Dockerfile21-26:

Build flags explained:

• CGO_ENABLED=0 - Pure Go binary (no C dependencies)
• -trimpath - Remove file system paths for reproducible builds
• -ldflags="-s -w" - Strip debug symbols for smaller binary
• -ldflags="-extldflags '-static'" - Statically link C libraries
• -tags netgo,osusergo - Use pure Go implementations of network and user functions
• ./cmd/memos - Entry point package

The resulting binary is self-contained and portable across systems.

Sources: scripts/Dockerfile21-26

Testing

Tests are run with:

The CI pipeline splits tests into 4 groups for parallel execution (.github/workflows/backend-tests.yml52):

1. store - Database layer tests (all 3 drivers)
2. server - HTTP server and service tests
3. plugin - Plugin system tests
4. other - cmd, internal, proto packages

Sources: .github/workflows/backend-tests.yml64-84

Linting

golangci-lint v2.4.0 is used for static analysis (.github/workflows/backend-tests.yml40-44):

• Multiple linters enabled (gofmt, govet, golint, etc.)
• 3-minute timeout
• Runs on every PR

Sources: .github/workflows/backend-tests.yml40-44

---

Full Application Build Process

The complete build process combines frontend and backend builds into a single executable binary with embedded assets.

Sources: web/package.json7 scripts/Dockerfile15-26

Step 1: Frontend Build

The frontend must be built before the backend build:

This produces optimized static files in server/router/frontend/dist/:

• index.html - HTML entry point
• assets/*.js - JavaScript bundles (code-split)
• assets/*.css - Stylesheet bundles
• Static assets (images, fonts, etc.)

Sources: web/package.json7 .github/workflows/build-canary-image.yml35-39

Step 2: Go Embed

The server/router/frontend package uses Go's embed directive to include the frontend files in the binary at compile time. The exact implementation would look similar to:

This embeds all files from server/router/frontend/dist/ into the compiled Go binary.

Sources: server/server.go64 (references frontend service)

Step 3: Backend Build

After the frontend is embedded, build the Go binary:

The resulting memos binary is fully self-contained and can be deployed without any external files.

Sources: scripts/Dockerfile21-26

Single Binary Deployment

The architecture enables single-binary deployment:

• No separate web server (nginx, Apache) needed
• No need to deploy frontend files separately
• Simplified deployment and distribution
• Smaller container images

The Echo HTTP server serves both:

• Static frontend files from embedded FS
• Backend API endpoints
• File uploads/downloads
• RSS feeds

Sources: server/server.go64 server/server.go72-73

---

Development Workflows

Local Development Setup

Frontend development:

This starts Vite dev server with hot module replacement at http://localhost:5173.

Backend development:

This starts the server at http://localhost:5230 (default port).

Sources: web/package.json5 scripts/Dockerfile52

Hot Reload

• Frontend: Vite provides instant HMR (Hot Module Replacement)
• Backend: Use tools like air or reflex for automatic restart on code changes (not included in repository)

Protocol Buffer Generation

When modifying .proto files:

This regenerates:

• Go code in proto/gen/
• TypeScript code for frontend gRPC clients

The CI pipeline validates proto files with .github/workflows/proto-linter.yml30-33:

Sources: .github/workflows/proto-linter.yml30-40

Pre-commit Checks

Before committing, run:

Frontend:

Backend:

Sources: web/package.json8 .github/workflows/backend-tests.yml35-38

---

CI/CD Pipeline Architecture

The CI/CD system uses GitHub Actions with separate workflows for testing and image building.

Sources: .github/workflows/backend-tests.yml .github/workflows/frontend-tests.yml .github/workflows/build-canary-image.yml .github/workflows/build-stable-image.yml

Testing Workflows

Backend Tests (.github/workflows/backend-tests.yml)

Triggers: Push to main, PR affecting *.go, go.mod, go.sum

Jobs:

1. static-checks - Verifies go.mod tidiness and runs golangci-lint
2. tests - Runs tests in parallel across 4 groups:
   • store - Database layer tests (SQLite, MySQL, PostgreSQL)
   • server - HTTP server tests with race detector
   • plugin - Plugin system tests
   • other - Remaining packages

Coverage reports are uploaded to Codecov for main branch builds.

Sources: .github/workflows/backend-tests.yml21-92

Frontend Tests (.github/workflows/frontend-tests.yml)

Triggers: Push to main, PR affecting web/**

Jobs:

1. lint - TypeScript type-checking and Biome linting
2. build - Verifies production build completes successfully

Sources: .github/workflows/frontend-tests.yml20-73

Proto Linter (.github/workflows/proto-linter.yml)

Triggers: Push to main, PR affecting proto/**

Jobs:

1. lint - Runs buf lint and buf format -d to ensure proto files are properly formatted

Sources: .github/workflows/proto-linter.yml16-41

Image Building Workflows

Canary Builds (.github/workflows/build-canary-image.yml)

Trigger: Every push to main branch

Process:

1. Build frontend with pnpm release
2. Upload frontend artifact
3. Build Docker images for 2 platforms in parallel:
   • linux/amd64
   • linux/arm64
4. Push each platform image by digest
5. Create manifest list and tag as canary
6. Push to both Docker Hub (neosmemo/memos:canary) and GHCR (ghcr.io/usememos/memos:canary)

Sources: .github/workflows/build-canary-image.yml11-167

Stable Builds (.github/workflows/build-stable-image.yml)

Trigger: Push to release/** branches or v*.*.* tags

Process:

1. Extract version from branch/tag name
2. Build frontend with pnpm release
3. Upload frontend artifact
4. Build Docker images for 3 platforms in parallel:
   • linux/amd64
   • linux/arm64
   • linux/arm/v7 (32-bit ARM)
5. Push each platform image by digest
6. Create manifest list and tag with:
   • stable
   • vX.Y.Z (full version)
   • X.Y (minor version)
7. Push to both Docker Hub and GHCR

Sources: .github/workflows/build-stable-image.yml10-185

Multi-Architecture Strategy

The build pipeline uses Docker Buildx with QEMU for cross-platform builds:

Key implementation details:

1. Frontend built once - Platform-independent artifact shared across all builds (.github/workflows/build-canary-image.yml41-46)
2. Parallel backend builds - Each platform builds in parallel using matrix strategy (.github/workflows/build-canary-image.yml56-59)
3. Push by digest - Each platform image pushed with unique digest (.github/workflows/build-canary-image.yml88-97)
4. Manifest creation - Final step combines all digests into a single multi-arch tag (.github/workflows/build-canary-image.yml155-161)

Users automatically pull the correct image for their platform when running docker pull neosmemo/memos:stable.

Sources: .github/workflows/build-canary-image.yml56-111 .github/workflows/build-stable-image.yml68-125

---

Docker Build Process

The Docker build uses a multi-stage Dockerfile to optimize image size and build caching.

Build Stages

Stage 1: Backend Build (scripts/Dockerfile1-26)

Optimizations:

• --mount=type=cache - Caches Go modules and build cache across builds
• --platform=$BUILDPLATFORM - Builds on native platform (faster)
• Cross-compilation via GOOS/GOARCH for target platform

Sources: scripts/Dockerfile1-26

Stage 2: Runtime Image (scripts/Dockerfile29-56)

Key features:

• Minimal Alpine Linux base (small image size)
• Non-root user with UID/GID 10001
• Timezone and CA certificates for HTTPS
• Data directory at /var/opt/memos
• Entrypoint script for permission handling

Sources: scripts/Dockerfile29-56

Entrypoint Script

The scripts/entrypoint.sh1-46 handles:

1. Permission fixing - Ensures data directory is owned by nonroot user
2. User downgrade - Drops from root to nonroot (UID 10001)
3. Secret file support - Reads secrets from *_FILE environment variables:

This enables secure secret management in Docker Swarm and Kubernetes.

Sources: scripts/entrypoint.sh1-46

Build Context and .dockerignore

The build context includes:

• Root directory (entire repository)
• Frontend files must exist at server/router/frontend/dist/ before Docker build
• .dockerignore excludes unnecessary files (not shown in provided files)

Best practice: Build frontend locally or in CI before Docker build:

Sources: scripts/Dockerfile15

---

Build Performance Optimizations

Frontend Build Cache

pnpm store caching in CI (.github/workflows/build-canary-image.yml25-34):

This caches downloaded npm packages, reducing build time from minutes to seconds.

Sources: .github/workflows/build-canary-image.yml25-34

Backend Build Cache

Go module caching (scripts/Dockerfile9-10):

Go build cache (scripts/Dockerfile18-19):

These BuildKit cache mounts persist across builds, significantly speeding up compilation.

Sources: scripts/Dockerfile9-19

Docker Layer Caching

GitHub Actions uses Docker layer caching (.github/workflows/build-canary-image.yml95-96):

This caches Docker layers in GitHub Actions cache storage, reusing unchanged layers across builds.

Sources: .github/workflows/build-canary-image.yml95-96

Artifact Upload/Download

Frontend artifacts are built once and shared across platform builds (.github/workflows/build-canary-image.yml41-46):

This eliminates redundant frontend builds (5-10 minutes saved per platform).

Sources: .github/workflows/build-canary-image.yml41-46 .github/workflows/build-canary-image.yml63-67

---

Summary Table: Build Commands

Task	Command	Location
Install frontend deps	pnpm install --frozen-lockfile	web/
Dev frontend	pnpm dev	web/
Build frontend (dev)	pnpm build	web/
Build frontend (prod)	pnpm release	web/
Lint frontend	pnpm lint	web/
Download Go deps	go mod download	Root
Build backend	go build -o memos ./cmd/memos	Root
Run tests	go test ./...	Root
Lint backend	golangci-lint run	Root
Generate protos	buf generate	proto/
Build Docker image	docker build -f scripts/Dockerfile .	Root
Run Docker container	docker run -v /data:/var/opt/memos -p 5230:5230 neosmemo/memos	-

Sources: web/package.json go.mod scripts/Dockerfile