[中文版](README.zh-CN.md)

# ai-workflow-v2

This repository is organized as a small set of independent modules instead of one mixed runtime tree.

## Modules

| Module | Path | Purpose |
| --- | --- | --- |
| Inbox host | `inbox/` | Go control plane: CLI, HTTP API, runtime storage, agent dispatch |
| Dashboard | `dashboard/` | React operations UI for the inbox host |
| Blog backend | `apps/blog/backend/` | Sample Express API |
| Blog frontend | `apps/blog/frontend/` | Sample React client |
| Blog E2E | `apps/blog/e2e/` | Playwright black-box tests for the blog app |

Module boundaries are documented in [docs/modules.md](docs/modules.md).

## Repository Rules

- Modules are developed and tested independently.
- Cross-module communication should happen through HTTP or CLI boundaries, not direct source imports.
- Runtime data, local databases, worktrees, caches, and build artifacts are generated files and are ignored by default.

## Quick Start

Use the root `Makefile` as the stable entrypoint:

```bash
make help
make build-inbox
make test-inbox
make test-dashboard
make test-blog-backend
make test-blog-frontend
make test-blog-e2e
```

## Independent Module Usage

### Inbox host

```bash
cd inbox
go build ./cmd/inbox
go test ./...
```

More detail: [inbox/README.md](inbox/README.md)

### Dashboard

```bash
cd dashboard
npm ci
npm run dev
npm test
```

More detail: [dashboard/README.md](dashboard/README.md)

### Blog app

```bash
cd apps/blog/backend && npm ci && npm test
cd apps/blog/frontend && npm ci && npm test
cd apps/blog/e2e && npm ci && npm test
```

More detail: [apps/blog/README.md](apps/blog/README.md)

## Testing Matrix

- Fast checks: `make test-all`
- Browser/E2E checks: `make test-all-e2e`
- Full dependency install for JS modules: `make deps-all`

## Goal

Keep each module independently runnable, independently testable, and clear about what it owns.