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:

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:

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

  type MyComponentProps = {
    title: string;
    count?: number;
  };
  
  const MyComponent: React.FC<MyComponentProps> = ({ title, count = 0 }) => {
    // ...
  };
  

• API Responses: Type your API responses

  type User = {
    id: number;
    name: string;
  };
  
  const users = await api.get<User[]>('/api/users');
  

• Hooks: Type hook return values and parameters

  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.