LLM_GUIDE.md

# LLM Guide: NLP-IBM-Debater Workspace

This repository is a React + TypeScript (Create React App) workspace prepared with Tailwind CSS and a modular app layout. Use this guide as the single source of truth when making automated or AI-assisted changes.

## Project map

- `src/app/App.tsx` — entry composition (TypeScript).
- `src/app/layouts/MainLayout.tsx` — basic layout wrapper (TypeScript).
- `src/app/pages/` — page components (use `.tsx` extension).
- `src/app/components/` — reusable UI pieces (common/navigation, use `.tsx` extension).
  - `common/ErrorBoundary.tsx` — error boundary component (class component, required by React).
  - `common/Loading.tsx` — loading spinner component.
- `src/app/services/api-wrapper.ts` — centralized API client with fetch wrapper (GET/POST/PUT/PATCH/DELETE).
- `src/app/hooks/` — custom React hooks (use `.ts` extension).
  - `useApi.ts` — hook for API calls with loading/error states.
- `src/app/types/` — TypeScript type definitions (use `.ts` extension).
  - `api.types.ts` — API-related types.
  - `index.ts` — central export point for all types.
- `src/app/utils/` — utility functions (use `.ts` extension, debounce, formatError, etc.).
- `src/app/constants/` — app-wide constants (use `.ts` extension, API endpoints, config).
- `src/index.js` — CRA entry point mounting `App` with ErrorBoundary.
- `tailwind.config.js` & `postcss.config.js` — Tailwind setup.
- `.env.example` — environment variables template (all `.env*` files are gitignored).

## Conventions

- **File Extensions**: 
  - Use `.tsx` for React components (components, pages, layouts)
  - Use `.ts` for non-JSX TypeScript files (hooks, utils, types, services)
  - Use `.js` only for config files (index.js, config files)
- **TypeScript**: This project uses TypeScript for type safety. Always type your props, functions, and API responses.
- Prefer feature-first folders under `src/app` (`components`, `pages`, `layouts`, `data`, `hooks`, `services` as needed).
- Styling is Tailwind-first; avoid ad-hoc CSS files unless adding global tokens.
- Keep components presentational and pass data via props; co-locate tests next to features or under `__tests__`.
- Use functional components and hooks; avoid class components (except ErrorBoundary which requires a class).
- Keep imports relative to `src/` (CRA default) and prefer absolute paths only if `NODE_PATH`/aliases are introduced.

## Commands

- Install deps: `npm install`
- Start dev server: `npm start` (loads `.env.development`)
- Build for prod: `npm run build` (loads `.env.production`)
- Run tests: `npm test`

## Environment Variables

- **`.env.example`** — Template showing required variables (committed to git)
- **All `.env*` files** — Gitignored for security (create from `.env.example`)

**Important**: All environment variables exposed to the browser must start with `REACT_APP_` prefix.

**Setup**:
1. Copy `.env.example` to create your local env files:
   - Development: `cp .env.example .env.development.local`
   - Production: `cp .env.example .env.production.local`
2. Update the values in your local `.env.*.local` files

Current variables:
- `REACT_APP_API_BASE_URL` — API base URL (defaults to `http://localhost:4000` if not set)

To add new variables:
1. Add to `.env.example` as documentation
2. Update your local `.env.*.local` files
3. Access via `process.env.REACT_APP_YOUR_VAR`

## Patterns to follow

- Add new UI to `src/app/pages` (use `.tsx` extension) and wire via `App.tsx`.
- Reuse `MainLayout` for consistent shell elements.
- Keep static strings in `src/app/data` for reuse/testing.
- **API calls**: 
  - Use `src/app/services/api-wrapper.ts` for direct API calls: `api.get()`, `api.post()`, etc.
  - Use `useApi` hook from `src/app/hooks/useApi.ts` for components that need loading/error states.
- **Types**: Add new TypeScript types to `src/app/types/` (use `.ts` extension) and export from `index.ts`.
- **Constants**: Add app-wide constants to `src/app/constants/index.ts`.
- **Utils**: Add reusable utility functions to `src/app/utils/index.ts`.
- **Component Props**: Always type your component props using TypeScript interfaces or types.
- When adding new services, create `src/app/services/*` (use `.ts` extension) and keep fetchers pure; inject into components via hooks or props.

## Quality and safety

- Use React Testing Library for behavior-first tests.
- Avoid editing generated configs unless necessary; prefer small, reviewable diffs.
- Document non-obvious decisions inline with concise comments.

## API Service Usage

### Direct API calls

The `api-wrapper.ts` service provides a typed, centralized way to make HTTP requests:

```typescript
import api from '../services/api-wrapper';

// GET request
const data = await api.get<User[]>('/users');

// POST request
const newUser = await api.post<User, CreateUserDto>('/users', { name: 'John' });

// With error handling
try {
  const result = await api.get('/endpoint');
} catch (error) {
  // error is typed as ApiError with status, message, details
  console.error(error.status, error.message);
}
```

### Using the useApi hook

For components that need loading and error states:

```typescript
import { useApi } from '../hooks/useApi';
import Loading from '../components/common/Loading';
import type { User } from '../types';

const MyComponent: React.FC = () => {
  const { data, loading, error, refetch } = useApi<User[]>('/api/users');
  
  if (loading) return <Loading />;
  if (error) return <div>Error: {error.message}</div>;
  
  return <div>{/* render data */}</div>;
};
```

The service automatically:
- Uses `REACT_APP_API_BASE_URL` from environment variables
- Sets JSON content-type headers
- Handles JSON parsing
- Throws typed errors for non-OK responses
- Supports AbortSignal for request cancellation

## TypeScript Guidelines

- **Components**: Always type props using interfaces or types
  ```typescript
  type MyComponentProps = {
    title: string;
    count?: number;
  };
  
  const MyComponent: React.FC<MyComponentProps> = ({ title, count = 0 }) => {
    // ...
  };
  ```

- **API Responses**: Type your API responses
  ```typescript
  type User = {
    id: number;
    name: string;
  };
  
  const users = await api.get<User[]>('/api/users');
  ```

- **Hooks**: Type hook return values and parameters
  ```typescript
  const { data, loading } = useApi<Debate[]>('/api/debates');
  ```

## How to help

- Before large refactors, note intent and file targets in the PR description.
- After code edits, run tests or `npm run build` to verify TypeScript compilation.
- When adding API endpoints, use the `api-wrapper.ts` service instead of raw `fetch`.
- Always use TypeScript types for props, API responses, and function parameters.
- Keep this guide updated when changing structure, commands, or adding new services.