re-uploading work
This commit is contained in:
312
web/README.md
Normal file
312
web/README.md
Normal file
@@ -0,0 +1,312 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user