|
| 1 | +# Polos UI |
| 2 | + |
| 3 | +The web interface for the Polos agent platform, built with React, TypeScript, and Vite. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The Polos UI provides a comprehensive interface for managing and monitoring: |
| 8 | +- **Agents** - AI agent definitions and executions |
| 9 | +- **Workflows** - Workflow definitions and runs |
| 10 | +- **Tools** - Tool definitions and executions |
| 11 | +- **Traces** - Distributed tracing and observability |
| 12 | + |
| 13 | +## Getting Started |
| 14 | + |
| 15 | +### Prerequisites |
| 16 | + |
| 17 | +- Node.js 18+ and npm |
| 18 | +- Access to the Polos orchestrator API (default: `http://localhost:8080`) |
| 19 | + |
| 20 | +### Installation |
| 21 | + |
| 22 | +```bash |
| 23 | +npm install |
| 24 | +``` |
| 25 | + |
| 26 | +### Development |
| 27 | + |
| 28 | +Start the development server: |
| 29 | + |
| 30 | +```bash |
| 31 | +npm run dev |
| 32 | +``` |
| 33 | + |
| 34 | +The UI will be available at `http://localhost:5173` (or the next available port). |
| 35 | + |
| 36 | +### Environment Variables |
| 37 | + |
| 38 | +Create a `.env` file in the `ui/` directory: |
| 39 | + |
| 40 | +```env |
| 41 | +# API Base URL (default: http://localhost:8080) |
| 42 | +VITE_API_BASE_URL=http://localhost:8080 |
| 43 | +
|
| 44 | +# Supabase configuration (for OAuth authentication) |
| 45 | +VITE_SUPABASE_URL=your_supabase_url |
| 46 | +VITE_SUPABASE_ANON_KEY=your_supabase_anon_key |
| 47 | +
|
| 48 | +# Local mode (skip authentication, for local/development mode) |
| 49 | +VITE_POLOS_LOCAL_MODE=true |
| 50 | +``` |
| 51 | + |
| 52 | +**Note:** Local mode only works when running on `localhost` and requires `VITE_POLOS_LOCAL_MODE=true`. |
| 53 | + |
| 54 | +## Project Structure |
| 55 | + |
| 56 | +``` |
| 57 | +ui/ |
| 58 | +├── src/ |
| 59 | +│ ├── components/ # Reusable UI components |
| 60 | +│ │ ├── auth/ # Authentication components |
| 61 | +│ │ ├── header/ # Header/navigation |
| 62 | +│ │ ├── traces/ # Trace visualization components |
| 63 | +│ │ └── ui/ # Shadcn UI components |
| 64 | +│ ├── pages/ # Page components |
| 65 | +│ │ ├── agents/ # Agent management pages |
| 66 | +│ │ ├── workflows/ # Workflow management pages |
| 67 | +│ │ ├── tools/ # Tool management pages |
| 68 | +│ │ ├── traces/ # Trace viewing pages |
| 69 | +│ │ ├── auth/ # Authentication pages |
| 70 | +│ │ ├── account/ # Account settings |
| 71 | +│ │ └── projects/ # Project settings |
| 72 | +│ ├── context/ # React context providers |
| 73 | +│ │ ├── AuthContext.tsx # Authentication state |
| 74 | +│ │ └── ProjectContext.tsx # Project selection state |
| 75 | +│ ├── lib/ # Utility libraries |
| 76 | +│ │ ├── api.ts # API client functions |
| 77 | +│ │ ├── supabase.ts # Supabase client |
| 78 | +│ │ └── localMode.ts # Local mode utilities |
| 79 | +│ ├── utils/ # Utility functions |
| 80 | +│ │ ├── formatter.ts # Data formatting utilities |
| 81 | +│ │ └── timeFilters.ts # Time range filtering |
| 82 | +│ ├── types/ # TypeScript type definitions |
| 83 | +│ ├── layouts/ # Layout components |
| 84 | +│ └── test/ # Test utilities and mocks |
| 85 | +├── public/ # Static assets |
| 86 | +└── dist/ # Build output (generated) |
| 87 | +``` |
| 88 | + |
| 89 | +## Key Features |
| 90 | + |
| 91 | +### Authentication |
| 92 | + |
| 93 | +- **Local Authentication** - Email/password sign in and sign up |
| 94 | +- **OAuth** - Google and GitHub authentication via Supabase |
| 95 | +- **Local Mode** - Skip authentication for local development |
| 96 | + |
| 97 | +### Project Management |
| 98 | + |
| 99 | +- Multi-project support with project switching |
| 100 | +- Project settings and API key management |
| 101 | +- Project member management |
| 102 | + |
| 103 | +### Agent/Workflow/Tool Management |
| 104 | + |
| 105 | +- List views with filtering and search |
| 106 | +- Run views showing execution history |
| 107 | +- Detail pages for individual runs |
| 108 | +- Trace visualization for debugging |
| 109 | + |
| 110 | +### Observability |
| 111 | + |
| 112 | +- Distributed tracing with timeline and graph views |
| 113 | +- Span details with attributes, events, and errors |
| 114 | +- LLM call tracking and visualization |
| 115 | +- Error tracking and debugging |
| 116 | + |
| 117 | +## Available Scripts |
| 118 | + |
| 119 | +```bash |
| 120 | +# Development |
| 121 | +npm run dev # Start development server |
| 122 | + |
| 123 | +# Building |
| 124 | +npm run build # Build for production |
| 125 | +npm run preview # Preview production build |
| 126 | + |
| 127 | +# Code Quality |
| 128 | +npm run lint # Run ESLint |
| 129 | +npm run format # Format code with Prettier |
| 130 | +npm run format:check # Check code formatting |
| 131 | + |
| 132 | +# Testing |
| 133 | +npm test # Run tests in watch mode |
| 134 | +npm run test:run # Run tests once |
| 135 | +npm run test:ui # Run tests with interactive UI |
| 136 | +npm run test:coverage # Run tests with coverage report |
| 137 | +``` |
| 138 | + |
| 139 | +## Building for Production |
| 140 | + |
| 141 | +```bash |
| 142 | +npm run build |
| 143 | +``` |
| 144 | + |
| 145 | +The production build will be output to the `dist/` directory. |
| 146 | + |
| 147 | +## Testing |
| 148 | + |
| 149 | +The project uses **Vitest** and **React Testing Library** for testing. See [`src/test/README.md`](./src/test/README.md) for detailed testing documentation. |
| 150 | + |
| 151 | +Quick start: |
| 152 | +```bash |
| 153 | +npm test # Watch mode |
| 154 | +npm run test:run # Run once |
| 155 | +npm run test:coverage # With coverage |
| 156 | +``` |
| 157 | + |
| 158 | +## Code Formatting |
| 159 | + |
| 160 | +Code is automatically formatted with **Prettier** before commits (via Husky + lint-staged). Manual formatting: |
| 161 | + |
| 162 | +```bash |
| 163 | +npm run format # Format all files |
| 164 | +npm run format:check # Check formatting without changing files |
| 165 | +``` |
| 166 | + |
| 167 | +## Technology Stack |
| 168 | + |
| 169 | +- **React 19** - UI framework |
| 170 | +- **TypeScript** - Type safety |
| 171 | +- **Vite** - Build tool and dev server |
| 172 | +- **React Router** - Client-side routing |
| 173 | +- **Tailwind CSS** - Styling |
| 174 | +- **Shadcn UI** - Component library |
| 175 | +- **Vitest** - Testing framework |
| 176 | +- **React Testing Library** - Component testing |
| 177 | +- **MSW** - API mocking for tests |
| 178 | +- **Supabase** - OAuth authentication |
| 179 | + |
| 180 | +## Development Guidelines |
| 181 | + |
| 182 | +### Code Style |
| 183 | + |
| 184 | +- Use TypeScript for all new code |
| 185 | +- Follow React best practices (hooks, functional components) |
| 186 | +- Use Tailwind CSS for styling |
| 187 | +- Use Shadcn UI components when available |
| 188 | +- Format code with Prettier (auto-formatted on commit) |
| 189 | + |
| 190 | +### Component Organization |
| 191 | + |
| 192 | +- Co-locate components with their tests (`.test.tsx` files) |
| 193 | +- Use the `@/` alias for imports from `src/` |
| 194 | +- Keep components focused and reusable |
| 195 | +- Use TypeScript interfaces for props |
| 196 | + |
| 197 | +### API Integration |
| 198 | + |
| 199 | +- All API calls go through `src/lib/api.ts` |
| 200 | +- Use the `api` object for orchestration API calls |
| 201 | +- Include `X-Project-ID` header for project-scoped requests |
| 202 | +- Handle errors gracefully with user-friendly messages |
| 203 | + |
| 204 | +### State Management |
| 205 | + |
| 206 | +- Use React Context for global state (Auth, Project) |
| 207 | +- Use local state (`useState`) for component-specific state |
| 208 | +- Use `useEffect` for side effects and data fetching |
| 209 | + |
| 210 | +## Troubleshooting |
| 211 | + |
| 212 | +### Local Mode Not Working |
| 213 | + |
| 214 | +Local mode only works when: |
| 215 | +1. `VITE_POLOS_LOCAL_MODE=true` is set |
| 216 | +2. The app is running on `localhost`, `127.0.0.1`, or `[::1]` |
| 217 | + |
| 218 | +If local mode isn't working, check the browser console for warnings. |
| 219 | + |
| 220 | +### API Connection Issues |
| 221 | + |
| 222 | +- Verify `VITE_API_BASE_URL` is correct |
| 223 | +- Check that the orchestrator is running |
| 224 | +- Check browser console for CORS errors |
| 225 | +- Verify authentication cookies are being set |
| 226 | + |
| 227 | +### Build Errors |
| 228 | + |
| 229 | +- Clear `node_modules` and reinstall: `rm -rf node_modules && npm install` |
| 230 | +- Clear Vite cache: `rm -rf node_modules/.vite` |
| 231 | +- Check TypeScript errors: `npm run build` (shows TS errors) |
| 232 | + |
| 233 | +## Contributing |
| 234 | + |
| 235 | +1. Follow the code style guidelines |
| 236 | +2. Write tests for new features |
| 237 | +3. Ensure all tests pass: `npm run test:run` |
| 238 | +4. Ensure code is formatted: `npm run format:check` |
| 239 | +5. Ensure linting passes: `npm run lint` |
| 240 | + |
| 241 | +## License |
| 242 | + |
| 243 | +See the main project LICENSE file. |
0 commit comments