);
};
```
### Code Splitting with React Router
Routes are automatically code-split:
```typescript
// Lazy load screen components
const HomeScreen = lazy(() => import('./HomeScreen'));
const SettingsScreen = lazy(() => import('./SettingsScreen'));
}>
} />
} />
```
### React Query Caching
Automatic caching and background updates:
```typescript
// Data is cached per queryKey
const { data: plans } = useQuery({
queryKey: ['plans'], // Cached
queryFn: fetchPlans,
staleTime: 1000 * 60 * 5, // 5 minutes
gcTime: 1000 * 60 * 10, // 10 minutes (was cacheTime)
});
// Background refetch when window regains focus
useQuery({
queryKey: ['plans'],
queryFn: fetchPlans,
refetchOnWindowFocus: true,
});
```
---
## Development Workflow
### Development Server
```bash
# Start Bun dev server with hot reload
bun dev
# Runs on http://localhost:5000/
# Frontend and backend both reload on file changes
```
### Environment Variables
```bash
# .env (client-side, public)
VITE_API_URL=http://localhost:5000/api
```
### TypeScript Type Checking
```bash
# Run TypeScript compiler
tsc --noEmit
# Included in build process
bun run build
```
### Code Formatting
```bash
# Format all files
bun format
# Format specific files
bun format:check
# Prettier config in .prettierrc
{
"semi": true,
"singleQuote": true,
"trailingComma": "all",
"printWidth": 120
}
```
### Component Development
When creating new features:
1. **Create component structure**
```
src/apps/officer-web/Screens/MyFeature/
├── index.tsx # Exports
├── MyFeatureScreen.tsx # Component
├── hooks/
│ └── useMyFeature.ts
├── types.ts
└── utils.ts
```
2. **Define types**
```typescript
// types.ts
export type MyFeatureProps = {
onSubmit: (data: FormData) => void;
disabled?: boolean;
};
```
3. **Implement component**
```typescript
// MyFeatureScreen.tsx
import { useMyFeature } from './hooks/useMyFeature';
import type { MyFeatureProps } from './types';
export const MyFeatureScreen = ({ onSubmit, disabled }: MyFeatureProps) => {
const { state, actions } = useMyFeature();
return (/* JSX */);
};
```
4. **Export**
```typescript
// index.tsx
export { MyFeatureScreen } from './MyFeatureScreen';
export type { MyFeatureProps } from './types';
```
---
## Integration Points
### API Endpoints Used
- **Auth**: `/api/auth/*` (signin, signup, verify, etc.)
- **Plans**: `/api/plans` (GET, POST, PUT, DELETE)
- **Skills**: `/api/skills` (GET, POST)
- **Tasks**: `/api/tasks` (CRUD operations)
- **Files**: `/api/file-browser` (navigation, upload)
- **Settings**: `/api/user` (preferences)
- **Terminal WS**: `/api/terminal/ws` (real-time shell)
- **Pi Chat WS**: `/api/pi/chat/ws` (real-time AI assistant)
### State Flow from Server to UI
```
Database
↓
API Response
↓
React Query Cache
↓
Component State
↓
Rendered UI
```
---
## Debugging
### Browser DevTools
```javascript
// Log component props
console.log('Props:', props);
// Log state updates
console.log('State changed:', newState);
// React DevTools browser extension
// Inspect component tree and props
```
### React Query Devtools
```typescript
// Installed: @tanstack/react-query-devtools
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
export function App() {
return (
<>
{/* App content */}
);
}
```
---
## Common Patterns
### Loading States
```typescript
export const DataComponent = () => {
const { data, isLoading, error } = useQuery({
queryKey: ['data'],
queryFn: fetchData,
});
if (isLoading) return ;
if (error) return ;
if (!data) return ;
return ;
};
```
### Form Handling with React Hook Form
```typescript
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
const schema = z.object({
email: z.string().email('Invalid email'),
password: z.string().min(8, 'Min 8 chars'),
});
type FormData = z.infer;
export const LoginForm = () => {
const { register, handleSubmit, formState: { errors } } = useForm({
resolver: zodResolver(schema),
});
const onSubmit = async (data: FormData) => {
await apiClient.post('/auth/signin', data);
};
return (
);
};
```
### Toast Notifications
```typescript
import { toast } from 'sonner';
// Success
toast.success('Operation completed!');
// Error
toast.error('Something went wrong', {
description: 'Please try again later',
});
// Custom
toast.custom((t) => (
Custom notification
));
```
---
## Related Documentation
- **Backend Architecture**: See `OFFICERDEV_BACKEND.md`
- **CONVENTIONS.md**: Detailed code patterns and style
- **CLAUDE.md**: Project overview
- **apps/officer-web/CLAUDE.md**: Frontend-specific patterns
---
## Summary
Officer's frontend is a modern React 19 SPA featuring:
- Type-safe component architecture
- Real-time WebSocket communication
- Server state management with React Query
- Beautiful UI with Tailwind CSS and shadcn/ui
- Strong React patterns without useCallback/useMemo
- Comprehensive authentication and authorization
- Responsive design for all devices
- AI-powered development assistance via Pi
- Interactive terminal emulation
The architecture prioritizes developer experience, type safety, and performance while providing a rich, interactive user experience for life management and AI-assisted development.