Tzelem Development Assistant

Expert assistant for developing the Tzelem multi-agent orchestration platform - a dynamic AI team builder that assembles specialized agents to deliver real work with enterprise-grade control, real-time observability, and spend guardrails.

Project Context

Tzelem is a monorepo-based platform where users define objectives with budgets, and the system assembles specialized AI agents that coordinate workflows and deliver results. The platform provides real-time monitoring, auditability, and budget controls.

Repository Structure

Tech Stack

**Frontend:**

**Design System:**

Development Workflow

Step 1: Navigate to Frontend Directory

Always start by navigating to the frontend application directory:

```bash

cd frontend/app

```

Step 2: Understand the Task

Before making changes:

Step 3: Development Commands

**Essential commands to use:**

Step 4: Code Organization

**Feature-based structure:**

```

src/

├── components/

│ ├── ui/ # ShadCN base components (Button, Input, etc.)

│ ├── layout/ # Header, Navigation, Layout wrappers

│ └── common/ # Shared components (LoadingSpinner, ErrorBoundary, etc.)

├── features/

│ ├── flow/ # Flow Builder (React Flow nodes, edges, canvas)

│ ├── run/ # Run Console & Execution monitoring (SSE integration)

│ ├── voice/ # Voice Interface (PipeCat WebRTC)

│ └── secrets/ # Secrets Management (server-side handling)

├── lib/

│ ├── api.ts # API client & endpoints

│ ├── utils.ts # Utility functions

│ └── types/ # Global TypeScript types

├── hooks/ # Custom React hooks

└── contexts/ # React Context providers

```

**When creating new features:**

1. Add feature directory under `src/features/[feature-name]/`

2. Create feature-specific components, hooks, and types within that directory

3. Export public API from `index.ts`

4. Add shared components to `src/components/common/` if reusable

5. Update type definitions in `src/lib/types/` for global types

Step 5: API Integration

**Configuration:**

**API client usage:**

```typescript

import { api } from '@/lib/api';

// Example API call

const response = await api.get('/runs');

```

Step 6: Flow Export Schema

Flows are exported as JSON with version 0.1.0 schema:

Step 7: Testing Requirements

**Before committing code:**

1. Run `npm run type-check` - Must pass with zero errors

2. Run `npm run lint` - Must pass or auto-fix with `npm run lint:fix`

3. Run `npm run test` - All tests must pass

4. Run `npm run format:check` - Code must be properly formatted

**Writing tests:**

Step 8: Security & Best Practices

**Critical rules:**

Step 9: Git Workflow

**Branches:**

**Commit checklist:**

1. Type checking passes (`npm run type-check`)

2. Linting passes (`npm run lint`)

3. Tests pass (`npm run test`)

4. Code is formatted (`npm run format`)

5. Commit message follows conventional commits format

Step 10: Voice Integration

**PipeCat Integration:**

Key Features Implementation Guide

Flow Builder

Run Console

Voice Interface

Secrets Manager

Common Tasks

**Add a new UI component:**

1. Check if ShadCN/UI component exists (`npx shadcn-ui add [component]`)

2. If custom, create in `src/components/common/`

3. Use Tailwind CSS for styling

4. Ensure TypeScript types are defined

5. Add tests in adjacent `.test.tsx` file

**Add a new feature:**

1. Create directory in `src/features/[feature-name]/`

2. Add components, hooks, types, and tests

3. Export public API from `index.ts`

4. Update routing if needed

5. Add API endpoints to `src/lib/api.ts`

**Debug SSE connection:**

1. Check `VITE_API_BASE_URL` in `.env`

2. Verify endpoint format: `/api/runs/:id/events`

3. Inspect Network tab for EventSource connections

4. Check backend logs for SSE errors

**Style with design system:**

Important Notes

Troubleshooting

**Type errors:**

**Build failures:**

**Test failures:**

**SSE connection issues:**