312 lines
8.6 KiB
Markdown
312 lines
8.6 KiB
Markdown
# Attune Web UI
|
|
|
|
Modern React-based web interface for the Attune automation platform.
|
|
|
|
## Overview
|
|
|
|
The Attune Web UI is a single-page application (SPA) built with React 18, TypeScript, and Vite that provides a comprehensive interface for managing and monitoring the Attune automation platform.
|
|
|
|
## Tech Stack
|
|
|
|
- **React 18** - UI framework
|
|
- **TypeScript 5** - Type safety
|
|
- **Vite** - Build tool and dev server
|
|
- **React Router v6** - Client-side routing
|
|
- **TanStack Query (React Query v5)** - Server state management
|
|
- **Axios** - HTTP client
|
|
- **Tailwind CSS v3** - Styling
|
|
- **Zustand** - Client state management (minimal usage)
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 18+ and npm
|
|
- Attune API service running on `http://localhost:8080` (or configured URL)
|
|
|
|
## Getting Started
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
cd web
|
|
npm install
|
|
```
|
|
|
|
### Development
|
|
|
|
```bash
|
|
# Start development server (runs on http://localhost:3000)
|
|
npm run dev
|
|
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Preview production build
|
|
npm run preview
|
|
|
|
# Lint code
|
|
npm run lint
|
|
```
|
|
|
|
### Environment Configuration
|
|
|
|
Create a `.env.development` file (already provided) or customize:
|
|
|
|
```env
|
|
VITE_API_BASE_URL=http://localhost:8080
|
|
VITE_WS_URL=ws://localhost:8081
|
|
VITE_APP_NAME=Attune
|
|
VITE_APP_VERSION=0.1.0
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
web/
|
|
├── src/
|
|
│ ├── api/ # OpenAPI generated code (run generate:api)
|
|
│ ├── components/
|
|
│ │ ├── common/ # Shared components
|
|
│ │ ├── layout/ # Layout components (MainLayout, etc.)
|
|
│ │ └── ui/ # UI primitives
|
|
│ ├── contexts/ # React contexts (Auth, etc.)
|
|
│ ├── hooks/ # Custom React hooks
|
|
│ ├── lib/ # Library setup (API client, query client)
|
|
│ ├── pages/ # Page components
|
|
│ │ ├── auth/ # Login page
|
|
│ │ ├── dashboard/ # Dashboard
|
|
│ │ ├── packs/ # Pack management (TODO)
|
|
│ │ ├── actions/ # Action management (TODO)
|
|
│ │ ├── rules/ # Rule management (TODO)
|
|
│ │ └── executions/ # Execution monitoring (TODO)
|
|
│ ├── types/ # TypeScript type definitions
|
|
│ ├── utils/ # Utility functions
|
|
│ ├── App.tsx # Root component with routing
|
|
│ ├── main.tsx # Application entry point
|
|
│ └── index.css # Global styles
|
|
├── public/ # Static assets
|
|
├── .env.development # Development environment variables
|
|
├── .env.example # Environment variables template
|
|
├── package.json
|
|
├── tsconfig.json # TypeScript configuration
|
|
├── vite.config.ts # Vite configuration
|
|
└── tailwind.config.js # Tailwind CSS configuration
|
|
```
|
|
|
|
## Features
|
|
|
|
### ✅ Implemented
|
|
|
|
- **Authentication**: JWT-based login with token refresh
|
|
- **Protected Routes**: Automatic redirect to login for unauthenticated users
|
|
- **Main Layout**: Sidebar navigation with user profile
|
|
- **Dashboard**: Basic dashboard with placeholder stats
|
|
- **API Client**: Axios instance with request/response interceptors
|
|
- **Type Safety**: Full TypeScript coverage with shared types
|
|
|
|
### 🚧 In Progress
|
|
|
|
- API client code generation from OpenAPI spec
|
|
- Real-time updates via WebSocket
|
|
- TanStack Query hooks for data fetching
|
|
|
|
### 📋 TODO
|
|
|
|
- Pack browser and management
|
|
- Action list and editor
|
|
- Rule list and editor
|
|
- Execution history and monitoring
|
|
- Event stream viewer
|
|
- Workflow visual editor
|
|
- User management
|
|
- Settings page
|
|
|
|
## API Client Generation ⭐
|
|
|
|
**The web UI uses an auto-generated TypeScript client from the backend's OpenAPI specification.**
|
|
|
|
This ensures type safety, schema validation, and automatic synchronization with the backend API.
|
|
|
|
### Generate/Update Client
|
|
|
|
```bash
|
|
# Ensure API service is running first
|
|
npm run generate:api
|
|
```
|
|
|
|
This will:
|
|
1. Download the OpenAPI spec from `http://localhost:8080/api-spec/openapi.json`
|
|
2. Generate TypeScript types in `src/api/models/` (~90 files)
|
|
3. Generate API service classes in `src/api/services/` (13 services)
|
|
4. Generate Axios client configuration in `src/api/core/`
|
|
|
|
### Usage
|
|
|
|
**✅ Use generated services (type-safe):**
|
|
```typescript
|
|
import { PacksService, AuthService } from '@/api';
|
|
import type { CreatePackRequest } from '@/api';
|
|
|
|
// Login
|
|
const response = await AuthService.login({
|
|
requestBody: { login: 'admin', password: 'secret' }
|
|
});
|
|
|
|
// List packs with full type safety
|
|
const packs = await PacksService.listPacks({ page: 1, pageSize: 50 });
|
|
|
|
// Create pack - TypeScript validates schema!
|
|
const pack = await PacksService.createPack({
|
|
requestBody: {
|
|
ref: 'my-pack',
|
|
label: 'My Pack',
|
|
description: 'Custom pack'
|
|
}
|
|
});
|
|
```
|
|
|
|
**❌ Don't use manual axios calls:**
|
|
```typescript
|
|
// NO - this has no type safety and can easily break
|
|
await apiClient.post('/api/v1/packs', { name: 'wrong-field' });
|
|
```
|
|
|
|
### Benefits
|
|
|
|
- ✅ **Full TypeScript types** - All requests/responses typed
|
|
- ✅ **Compile-time validation** - Catch schema mismatches before runtime
|
|
- ✅ **Auto-completion** - IDE support for all API methods
|
|
- ✅ **Always in sync** - Regenerate when backend changes
|
|
- ✅ **Less code** - No manual type definitions needed
|
|
|
|
### Available Services
|
|
|
|
- `AuthService` - Login, register, token refresh
|
|
- `PacksService` - Pack CRUD operations
|
|
- `ActionsService` - Action management
|
|
- `RulesService` - Rule configuration
|
|
- `ExecutionsService` - Execution tracking
|
|
- `HealthService` - Health checks
|
|
- And 7 more...
|
|
|
|
### Documentation
|
|
|
|
- **Generated API Docs:** `src/api/README.md`
|
|
- **Migration Guide:** `MIGRATION-TO-GENERATED-CLIENT.md`
|
|
- **Backend Docs:** `../docs/openapi-client-generation.md`
|
|
- **Interactive Swagger UI:** http://localhost:8080/docs
|
|
|
|
## Authentication Flow
|
|
|
|
1. User enters credentials on `/login`
|
|
2. App sends POST to `/auth/login`
|
|
3. Server returns `access_token` and `refresh_token`
|
|
4. Tokens stored in localStorage
|
|
5. API client automatically adds `Authorization: Bearer <token>` to requests
|
|
6. On 401 response, client attempts token refresh
|
|
7. If refresh fails, user redirected to login
|
|
|
|
## Development Guidelines
|
|
|
|
### Component Structure
|
|
|
|
- Use functional components with hooks
|
|
- Keep components small and focused
|
|
- Use TypeScript for all components
|
|
- Prefer composition over prop drilling
|
|
|
|
### State Management
|
|
|
|
- **Server State**: Use TanStack Query (React Query)
|
|
- **Client State**: Use React Context or Zustand
|
|
- **URL State**: Use React Router params/search
|
|
|
|
### Styling
|
|
|
|
- Use Tailwind CSS utility classes
|
|
- Follow mobile-first responsive design
|
|
- Use consistent spacing (4, 8, 16, 24, 32px)
|
|
- Prefer semantic color names from Tailwind
|
|
|
|
### API Integration
|
|
|
|
**Use generated services with React Query:**
|
|
|
|
```typescript
|
|
import { useQuery, useMutation } from '@tanstack/react-query';
|
|
import { ActionsService } from '@/api';
|
|
import type { CreateActionRequest } from '@/api';
|
|
|
|
// Fetch data with full type safety
|
|
const { data, isLoading } = useQuery({
|
|
queryKey: ['actions'],
|
|
queryFn: () => ActionsService.listActions({ page: 1, pageSize: 50 }),
|
|
});
|
|
|
|
// Mutate data with schema validation
|
|
const mutation = useMutation({
|
|
mutationFn: (data: CreateActionRequest) =>
|
|
ActionsService.createAction({ requestBody: data }),
|
|
onSuccess: () => {
|
|
queryClient.invalidateQueries({ queryKey: ['actions'] });
|
|
},
|
|
});
|
|
```
|
|
|
|
## Building for Production
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
Output is in `dist/` directory. Serve with any static file server:
|
|
|
|
```bash
|
|
# Preview locally
|
|
npm run preview
|
|
|
|
# Or use any static server
|
|
npx serve -s dist
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### API Client Out of Sync
|
|
|
|
**If the backend API changes, regenerate the client:**
|
|
|
|
```bash
|
|
# Start API server first
|
|
cd ../crates/api && cargo run --bin attune-api
|
|
|
|
# In another terminal, regenerate client
|
|
cd web
|
|
npm run generate:api
|
|
```
|
|
|
|
**Fix any TypeScript errors** that appear after regeneration - these indicate breaking API changes.
|
|
|
|
### CORS Issues
|
|
|
|
Ensure the API service has CORS enabled for `http://localhost:3000` in development.
|
|
|
|
### Build Errors
|
|
|
|
Clear the TypeScript build cache:
|
|
|
|
```bash
|
|
rm -rf node_modules/.tmp
|
|
npm run build
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Keep the architecture document up to date: `../docs/web-ui-architecture.md`
|
|
2. Add new pages to the router in `src/App.tsx`
|
|
3. Create reusable components in `src/components/common/`
|
|
4. Use existing hooks and utilities before creating new ones
|
|
|
|
## Related Documentation
|
|
|
|
- [Web UI Architecture](../docs/web-ui-architecture.md) - Detailed architecture decisions
|
|
- [API Documentation](../docs/api-overview.md) - Backend API reference
|
|
- [Main README](../README.md) - Attune platform overview |