---
description: Development workflow and best practices for Archestra Platform
alwaysApply: true
---

# Development Workflow

## Documentation Location

**Documentation files are located at `../../website/app/app/docs/content/`** (relative to the `platform/` directory). When asked to update or create documentation, edit or create files in that directory.

**Important**: When using tools that require absolute paths (like Read, Write, Edit), you must convert the relative path to an absolute path. Use `realpath ../../website/app/app/docs/content/` to get the absolute path, then use that with file operation tools.

## Starting Development

**Recommended**: Use Tilt for orchestrated development with hot reload
```bash
tilt up              # Start full development environment
```

**Alternative**: Manual workspace development
```bash
pnpm dev             # Start all workspaces in dev mode
```

## Before Committing

Always run these checks before committing code:

```bash
pnpm type-check      # Check TypeScript types across all workspaces
pnpm lint            # Lint and auto-fix with Biome
pnpm test            # Run tests (backend)
```

## Development Best Practices

1. **Use existing patterns** - Check neighboring files for examples before creating new patterns
2. **Follow project structure** - Keep test files colocated with source files
3. **Write tests** - Add `.test.ts` files alongside new models or utilities
4. **Use Tilt** - Prefer `tilt up` for the best development experience with hot reload
5. **Check Tilt UI** - Monitor logs at http://localhost:10350/ when using Tilt
6. **Database changes** - Always generate migrations with `pnpm db:migrate:dev`

## Common Commands Reference

### Backend
```bash
cd backend
pnpm dev             # Start backend in watch mode
pnpm build           # Compile TypeScript to dist/
pnpm test            # Run tests with Vitest
pnpm db:migrate      # Run database migrations
pnpm db:studio       # Open Drizzle Studio
```

### Frontend
```bash
cd frontend
pnpm dev             # Start Next.js dev server with Turbopack
pnpm build           # Build for production
```

### Code Quality (from root)
```bash
pnpm type-check      # Check all TypeScript types
pnpm lint            # Run Biome linter
pnpm format          # Format code with Biome
```

## E2E Testing

### Running Tests
```bash
pnpm test:e2e                        # Run all Playwright tests
pnpm test:e2e tests/ui/my-test.ts    # Run specific test file
```

### Playwright Locator Best Practices

Prefer Playwright's recommended locators over raw `locator()` calls. In priority order:
1. `page.getByRole()` - Accessible elements by ARIA role (buttons, links, headings, etc.)
2. `page.getByText()` - Find by text content
3. `page.getByLabel()` - Form controls by label
4. `page.getByPlaceholder()` - Input elements by placeholder
5. `page.getByTestId()` - Custom test IDs (use `E2eTestId` constants from `@archestra/shared`)

**Avoid:**
- Raw CSS selectors: `page.locator('.my-class')` or `page.locator('#my-id')`
- XPath selectors
- Arbitrary timeouts - use Playwright's auto-waiting instead

**Example:**
```typescript
// Good
await page.getByRole("button", { name: /Submit/i }).click();
await page.getByLabel(/Email/i).fill("test@example.com");
await page.getByTestId(E2eTestId.CreateAgentButton).click();

// Avoid
await page.locator('.submit-btn').click();
await page.locator('#email-input').fill("test@example.com");
await page.waitForTimeout(1000); // Use auto-waiting instead
```

Reference: https://playwright.dev/docs/locators#quick-guide

## Debugging

- **Tilt Web UI**: http://localhost:10350/ - View logs and resource status
- **Frontend**: http://localhost:3000/ - Main application
- **Tools Inspector**: http://localhost:3000/tools - Inspect proxy requests
- **Drizzle Studio**: https://local.drizzle.studio/ - Database inspection
