From fe751efd4449e2145bfcea9237d2802f1f3404e8 Mon Sep 17 00:00:00 2001
From: Jiayuan Zhang <forrestchang7@gmail.com>
Date: Sat, 21 Mar 2026 14:05:51 +0800
Subject: [PATCH] docs: add README with project setup and run instructions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..00fad72e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+# Multica
+
+AI-native task management platform — like Linear, but with AI agents as first-class citizens.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) (v20+)
+- [pnpm](https://pnpm.io/) (v10.28+)
+- [Go](https://go.dev/) (v1.26+)
+- [Docker](https://www.docker.com/)
+
+## Quick Start
+
+```bash
+# 1. Install dependencies
+pnpm install
+
+# 2. Copy environment variables
+cp .env.example .env
+
+# 3. Start PostgreSQL
+docker compose up -d
+
+# 4. Run database migrations
+make migrate-up
+
+# 5. Start the Go backend (port 8080)
+make dev
+
+# 6. In another terminal, start the frontend (port 3000)
+pnpm dev:web
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## Project Structure
+
+```
+├── server/             # Go backend (Chi + sqlc + gorilla/websocket)
+│   ├── cmd/            # server, daemon, migrate, seed
+│   ├── internal/       # Core business logic
+│   ├── migrations/     # SQL migrations
+│   └── sqlc.yaml       # sqlc config
+├── apps/
+│   └── web/            # Next.js 16 frontend
+├── packages/           # Shared TypeScript packages
+│   ├── ui/             # Component library (shadcn/ui + Radix)
+│   ├── types/          # Shared type definitions
+│   ├── sdk/            # API client SDK
+│   ├── store/          # State management
+│   ├── hooks/          # Shared React hooks
+│   └── utils/          # Utility functions
+├── Makefile            # Backend commands
+├── docker-compose.yml  # PostgreSQL + pgvector
+└── .env.example        # Environment variable template
+```
+
+## Commands
+
+### Frontend
+
+| Command | Description |
+|---------|-------------|
+| `pnpm dev:web` | Start Next.js dev server (port 3000) |
+| `pnpm build` | Build all TypeScript packages |
+| `pnpm typecheck` | Run TypeScript type checking |
+| `pnpm test` | Run TypeScript tests |
+
+### Backend
+
+| Command | Description |
+|---------|-------------|
+| `make dev` | Run Go server (port 8080) |
+| `make daemon` | Run local agent daemon |
+| `make test` | Run Go tests |
+| `make build` | Build server & daemon binaries |
+| `make sqlc` | Regenerate sqlc code from SQL |
+
+### Database
+
+| Command | Description |
+|---------|-------------|
+| `docker compose up -d` | Start PostgreSQL |
+| `docker compose down` | Stop PostgreSQL |
+| `make migrate-up` | Run database migrations |
+| `make migrate-down` | Rollback database migrations |
+| `make seed` | Seed test data |
+
+## Environment Variables
+
+See [`.env.example`](.env.example) for all available variables:
+
+- `DATABASE_URL` — PostgreSQL connection string
+- `PORT` — Backend server port (default: 8080)
+- `JWT_SECRET` — JWT signing secret
+- `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` — Google OAuth (optional)
+- `NEXT_PUBLIC_API_URL` — Frontend → backend API URL
+- `NEXT_PUBLIC_WS_URL` — Frontend → backend WebSocket URL