init

.cursor/rules/rules.mdc

@@ -0,0 +1,124 @@
+---
+alwaysApply: true
+---
+
+# NLP IBM Debater - Cursor Rules
+
+This is a React + TypeScript project using Create React App, Tailwind CSS, and a modular feature-first architecture.
+
+## File Extensions & TypeScript
+
+- **`.tsx`** - Use for React components (components, pages, layouts)
+- **`.ts`** - Use for non-JSX files (hooks, utils, types, services)
+- **`.js`** - Only for config files (index.js, config files)
+- **Always type everything**: props, functions, API responses, hook returns
+
+## Project Structure
+
+```
+src/app/
+├── App.tsx              # Entry composition
+├── layouts/             # Layout components (.tsx)
+├── pages/               # Page components (.tsx)
+├── components/          # Reusable UI (.tsx)
+│   └── common/          # Common components (Loading, ErrorBoundary)
+├── hooks/               # Custom hooks (.ts)
+├── services/            # API services (.ts)
+├── types/               # TypeScript types (.ts)
+├── utils/               # Utility functions (.ts)
+└── constants/           # App constants (.ts)
+```
+
+## Code Patterns
+
+### Components
+- Use functional components with `React.FC<PropsType>`
+- Always type props with interfaces or types
+- Use Tailwind CSS for styling (avoid custom CSS files)
+- Keep components presentational - pass data via props
+
+```typescript
+type MyComponentProps = {
+  title: string;
+  count?: number;
+};
+
+const MyComponent: React.FC<MyComponentProps> = ({ title, count = 0 }) => {
+  return <div>{title}: {count}</div>;
+};
+```
+
+### API Calls
+- Use `api-wrapper.ts` for direct API calls
+- Use `useApi` hook for components needing loading/error states
+- Always type API responses
+
+```typescript
+// Direct API call
+import api from '../services/api-wrapper';
+const data = await api.get<User[]>('/api/users');
+
+// With hook
+import { useApi } from '../hooks/useApi';
+const { data, loading, error } = useApi<User[]>('/api/users');
+```
+
+### Types
+- Add types to `src/app/types/` and export from `index.ts`
+- Use descriptive type names
+- Export types for reuse
+
+```typescript
+// src/app/types/debater.types.ts
+export type Debate = {
+  id: number;
+  topic: string;
+  arguments: Argument[];
+};
+```
+
+### Constants
+- Add constants to `src/app/constants/index.ts`
+- Use `API_ENDPOINTS` for API paths
+- Use `APP_CONFIG` for app configuration
+- Use `UI` for UI-related constants
+
+### Utils
+- Add utility functions to `src/app/utils/index.ts`
+- Keep functions pure and typed
+- Export for reuse
+
+## Conventions
+
+1. **Imports**: Use relative paths from `src/`
+2. **Styling**: Tailwind-first, avoid custom CSS
+3. **Error Handling**: Use ErrorBoundary for React errors, try/catch for API errors
+4. **Loading States**: Use `Loading` component from `components/common/Loading`
+5. **Environment Variables**: All must start with `REACT_APP_` prefix
+6. **Testing**: Use React Testing Library, co-locate tests
+
+## What NOT to Do
+
+- ❌ Don't use class components (except ErrorBoundary)
+- ❌ Don't use `.jsx` - use `.tsx` for components
+- ❌ Don't use raw `fetch` - use `api-wrapper.ts`
+- ❌ Don't create custom CSS files - use Tailwind
+- ❌ Don't commit `.env*` files (except `.env.example`)
+- ❌ Don't skip TypeScript types
+
+## When Adding New Features
+
+1. **New Page**: Create in `src/app/pages/` (`.tsx`), wire via `App.tsx`
+2. **New Component**: Create in `src/app/components/` (`.tsx`), type props
+3. **New API Endpoint**: Add to `API_ENDPOINTS` in constants, use `api-wrapper.ts`
+4. **New Type**: Add to `src/app/types/`, export from `index.ts`
+5. **New Hook**: Create in `src/app/hooks/` (`.ts`), type return values
+6. **New Utility**: Add to `src/app/utils/index.ts`, keep pure and typed
+
+## Quality Checks
+
+- Run `npm run build` to verify TypeScript compilation
+- Run `npm test` before committing
+- Ensure all props are typed
+- Ensure all API calls use typed responses
+- Follow existing code patterns and structure

.env.example

@@ -0,0 +1,15 @@
+# Environment Variables Template
+# 
+# Copy this file to create your local environment files:
+# - For development: cp .env.example .env.development.local
+# - For production: cp .env.example .env.production.local
+# 
+# All .env files are gitignored for security.
+# Update this template when adding new required environment variables.
+
+# API Configuration
+REACT_APP_API_BASE_URL=http://localhost:4000
+
+# Add other environment variables below (must start with REACT_APP_)
+# REACT_APP_ANOTHER_VAR=value
+

.gitignore

@@ -11,13 +11,79 @@
 # production
 /build
 
-# misc
-.DS_Store
+# environment variables (all .env files ignored - use .env.example as template)
+.env
 .env.local
+.env.development
 .env.development.local
+.env.test
 .env.test.local
+.env.production
 .env.production.local
 
+# misc
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.classpath
+.settings/
+*.sublime-project
+*.sublime-workspace
+
+# Logs
+logs
+*.log
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# parcel-bundler cache
+.cache
+.parcel-cache
+
+# Next.js (if ever migrated)
+.next
+out
+
+# Nuxt.js (if ever migrated)
+.nuxt
+dist
+
+# Temporary folders
+tmp/
+temp/

LLM_GUIDE.md

@@ -0,0 +1,172 @@
+# 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.
+

README.md

@@ -1,82 +1,32 @@
----
-title: NLP IBM Debater
-emoji: 🐠
-colorFrom: indigo
-colorTo: red
-sdk: static
-pinned: false
-app_build_command: npm run build
-app_file: build/index.html
-license: mit
----
+# NLP IBM Debater — React + Tailwind Workspace
 
-# Getting Started with Create React App
+An opinionated Create React App setup designed for fast iteration on NLP experiences. Tailwind CSS is wired in, and the app structure is organized for feature-first development.
 
-This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+## Project structure
 
-## Available Scripts
+- `src/app/App.jsx` — root composition.
+- `src/app/layouts/MainLayout.jsx` — shared shell with navigation and footer.
+- `src/app/pages/HomePage.jsx` — starter page showing layout and cards.
+- `src/app/components/` — reusable UI (navigation/common).
+- `src/app/data/` — UI copy and data stubs.
+- `LLM_GUIDE.md` — instructions for AI collaborators.
+- `tailwind.config.js` and `postcss.config.js` — Tailwind setup.
 
-In the project directory, you can run:
+## Scripts
 
-### `npm start`
+- `npm start` — run the dev server.
+- `npm test` — run tests in watch mode.
+- `npm run build` — production build.
 
-Runs the app in the development mode.\
-Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
+## Tailwind usage
 
-The page will reload when you make changes.\
-You may also see any lint errors in the console.
+Tailwind is configured via `tailwind.config.js`. Global styles live in `src/index.css` with Tailwind directives. Use utility classes for new UI and extend the config when adding design tokens.
 
-### `npm test`
+## Adding features
 
-Launches the test runner in the interactive watch mode.\
-See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+1. Create a page in `src/app/pages` and wire it through `App.jsx`.
+2. Add shared UI to `src/app/components`.
+3. Store static copy or mock data in `src/app/data`.
+4. Write behavioral tests with React Testing Library.
 
-### `npm run build`
-
-Builds the app for production to the `build` folder.\
-It correctly bundles React in production mode and optimizes the build for the best performance.
-
-The build is minified and the filenames include the hashes.\
-Your app is ready to be deployed!
-
-See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
-
-### `npm run eject`
-
-**Note: this is a one-way operation. Once you `eject`, you can't go back!**
-
-If you aren't satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
-
-Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you're on your own.
-
-You don't have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn't feel obligated to use this feature. However we understand that this tool wouldn't be useful if you couldn't customize it when you are ready for it.
-
-## Learn More
-
-You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
-
-To learn React, check out the [React documentation](https://reactjs.org/).
-
-### Code Splitting
-
-This section has moved here: [https://facebook.github.io/create-react-app/docs/code-splitting](https://facebook.github.io/create-react-app/docs/code-splitting)
-
-### Analyzing the Bundle Size
-
-This section has moved here: [https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size](https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size)
-
-### Making a Progressive Web App
-
-This section has moved here: [https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app)
-
-### Advanced Configuration
-
-This section has moved here: [https://facebook.github.io/create-react-app/docs/advanced-configuration](https://facebook.github.io/create-react-app/docs/advanced-configuration)
-
-### Deployment
-
-This section has moved here: [https://facebook.github.io/create-react-app/docs/deployment](https://facebook.github.io/create-react-app/docs/deployment)
-
-### `npm run build` fails to minify
-
-This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify)
+For more collaboration guidance, see `LLM_GUIDE.md`.

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "react-template",
+  "name": "nlp-ibm-debater",
   "version": "0.1.0",
   "private": true,
   "dependencies": {
@@ -12,6 +12,11 @@
     "react-scripts": "5.0.1",
     "web-vitals": "^2.1.4"
   },
+  "devDependencies": {
+    "autoprefixer": "^10.4.22",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^3.4.18"
+  },
   "scripts": {
     "start": "react-scripts start",
     "build": "react-scripts build",

postcss.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+

src/App.css

@@ -1,38 +0,0 @@
-.App {
-  text-align: center;
-}
-
-.App-logo {
-  height: 40vmin;
-  pointer-events: none;
-}
-
-@media (prefers-reduced-motion: no-preference) {
-  .App-logo {
-    animation: App-logo-spin infinite 20s linear;
-  }
-}
-
-.App-header {
-  background-color: #282c34;
-  min-height: 100vh;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  font-size: calc(10px + 2vmin);
-  color: white;
-}
-
-.App-link {
-  color: #61dafb;
-}
-
-@keyframes App-logo-spin {
-  from {
-    transform: rotate(0deg);
-  }
-  to {
-    transform: rotate(360deg);
-  }
-}

src/App.js

@@ -1,25 +0,0 @@
-import logo from './logo.svg';
-import './App.css';
-
-function App() {
-  return (
-    <div className="App">
-      <header className="App-header">
-        <img src={logo} className="App-logo" alt="logo" />
-        <p>
-          Edit <code>src/App.js</code> and save to reload.
-        </p>
-        <a
-          className="App-link"
-          href="https://reactjs.org"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          Learn React
-        </a>
-      </header>
-    </div>
-  );
-}
-
-export default App;

src/App.test.js

@@ -1,8 +1,6 @@
-import { render, screen } from '@testing-library/react';
-import App from './App';
+import { render } from '@testing-library/react';
+import App from './app/App';
 
-test('renders learn react link', () => {
+test('renders app without crashing', () => {
   render(<App />);
-  const linkElement = screen.getByText(/learn react/i);
-  expect(linkElement).toBeInTheDocument();
 });

src/app/App.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import MainLayout from './layouts/MainLayout.tsx';
+
+const App: React.FC = () => (
+  <MainLayout>
+    <div className="container mx-auto px-4 py-8">
+      {/* Your content here */}
+    </div>
+  </MainLayout>
+);
+
+export default App;
+

src/app/components/common/ErrorBoundary.tsx

@@ -0,0 +1,60 @@
+import React, { Component, ErrorInfo, ReactNode } from 'react';
+
+type Props = {
+  children: ReactNode;
+};
+
+type State = {
+  hasError: boolean;
+  error: Error | null;
+};
+
+/**
+ * Error Boundary component - catches React errors and displays fallback UI
+ * Note: Error boundaries must be class components (React limitation)
+ */
+class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('ErrorBoundary caught an error:', error, errorInfo);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <div className="flex min-h-screen items-center justify-center bg-gray-50 px-4">
+          <div className="text-center">
+            <h1 className="mb-4 text-2xl font-bold text-gray-900">
+              Something went wrong
+            </h1>
+            <p className="mb-4 text-gray-600">
+              {this.state.error?.message || 'An unexpected error occurred'}
+            </p>
+            <button
+              onClick={() => {
+                this.setState({ hasError: false, error: null });
+                window.location.reload();
+              }}
+              className="rounded bg-blue-600 px-4 py-2 text-white hover:bg-blue-700"
+            >
+              Reload Page
+            </button>
+          </div>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+export default ErrorBoundary;
+

src/app/components/common/Loading.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+
+type LoadingProps = {
+  size?: 'sm' | 'md' | 'lg';
+  text?: string;
+};
+
+/**
+ * Loading spinner component
+ */
+const Loading: React.FC<LoadingProps> = ({ size = 'md', text }) => {
+  const sizeClasses = {
+    sm: 'h-4 w-4',
+    md: 'h-8 w-8',
+    lg: 'h-12 w-12',
+  };
+
+  return (
+    <div className="flex flex-col items-center justify-center p-4">
+      <div
+        className={`${sizeClasses[size]} animate-spin rounded-full border-4 border-gray-200 border-t-blue-600`}
+        role="status"
+        aria-label="Loading"
+      />
+      {text && <p className="mt-2 text-sm text-gray-600">{text}</p>}
+    </div>
+  );
+};
+
+export default Loading;
+

src/app/constants/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Application-wide constants
+ */
+
+// API Endpoints (add your endpoints here as you build)
+export const API_ENDPOINTS = {
+
+} as const;
+
+// App configuration
+export const APP_CONFIG = {
+  APP_NAME: 'NLP IBM Debater',
+  VERSION: '0.1.0',
+} as const;
+
+// UI Constants
+export const UI = {
+  DEBOUNCE_DELAY: 300, // ms
+  ANIMATION_DURATION: 200, // ms
+} as const;
+

src/app/hooks/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Central export point for all custom hooks
+ */
+
+export { default as useApi } from './useApi';
+export { useApi as useApiHook } from './useApi';
+

src/app/hooks/useApi.ts

@@ -0,0 +1,64 @@
+import { useState, useEffect } from 'react';
+import api from '../services/api-wrapper';
+import type { ApiError } from '../types/api.types';
+
+type UseApiState<T> = {
+  data: T | null;
+  loading: boolean;
+  error: ApiError | null;
+};
+
+type UseApiOptions = {
+  immediate?: boolean; // Whether to fetch immediately on mount
+};
+
+/**
+ * Custom hook for making API calls with loading and error states
+ * 
+ * @example
+ * const { data, loading, error, execute } = useApi<User[]>('/api/users');
+ * 
+ * // Or with manual trigger
+ * const { data, loading, error, execute } = useApi<User[]>('/api/users', { immediate: false });
+ * execute(); // Call manually
+ */
+export function useApi<T>(
+  url: string,
+  options: UseApiOptions = { immediate: true }
+): UseApiState<T> & { execute: () => Promise<void>; refetch: () => Promise<void> } {
+  const [state, setState] = useState<UseApiState<T>>({
+    data: null,
+    loading: options.immediate ?? true,
+    error: null,
+  });
+
+  const execute = async () => {
+    setState((prev) => ({ ...prev, loading: true, error: null }));
+    try {
+      const data = await api.get<T>(url);
+      setState({ data, loading: false, error: null });
+    } catch (err) {
+      setState({
+        data: null,
+        loading: false,
+        error: err as ApiError,
+      });
+    }
+  };
+
+  useEffect(() => {
+    if (options.immediate !== false) {
+      execute();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [url]);
+
+  return {
+    ...state,
+    execute,
+    refetch: execute,
+  };
+}
+
+export default useApi;
+

src/app/layouts/MainLayout.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+
+type MainLayoutProps = {
+  children: React.ReactNode;
+};
+
+const MainLayout: React.FC<MainLayoutProps> = ({ children }) => (
+  <div className="min-h-screen">
+    {children}
+  </div>
+);
+
+export default MainLayout;
+

src/app/services/api-wrapper.ts

@@ -0,0 +1,73 @@
+import type { ApiRequestOptions, ApiError } from '../types/api.types';
+
+const DEFAULT_HEADERS: HeadersInit = {
+  'Content-Type': 'application/json',
+};
+
+const BASE_URL =
+  process.env.REACT_APP_API_BASE_URL?.replace(/\/$/, '');
+
+export type { ApiRequestOptions, ApiError };
+
+export async function apiRequest<TResponse = unknown, TBody = unknown>({
+  path,
+  method = 'GET',
+  body,
+  headers,
+  signal,
+}: ApiRequestOptions<TBody>): Promise<TResponse> {
+  const url = `${BASE_URL}${path.startsWith('/') ? '' : '/'}${path}`;
+
+  const response = await fetch(url, {
+    method,
+    headers: {
+      ...DEFAULT_HEADERS,
+      ...(headers ?? {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+    signal,
+  });
+
+  const contentType = response.headers.get('content-type');
+  const isJson = contentType?.includes('application/json');
+  const payload = isJson ? await response.json().catch(() => undefined) : undefined;
+
+  if (!response.ok) {
+    const error: ApiError = {
+      status: response.status,
+      message:
+        (payload as { message?: string })?.message ||
+        response.statusText ||
+        'Request failed',
+      details: payload,
+    };
+    throw error;
+  }
+
+  return payload as TResponse;
+}
+
+export const api = {
+  get: <TResponse>(path: string, init?: Omit<ApiRequestOptions, 'path' | 'method'>) =>
+    apiRequest<TResponse>({ path, method: 'GET', ...init }),
+  post: <TResponse, TBody = unknown>(
+    path: string,
+    body?: TBody,
+    init?: Omit<ApiRequestOptions<TBody>, 'path' | 'method' | 'body'>,
+  ) => apiRequest<TResponse, TBody>({ path, method: 'POST', body, ...init }),
+  put: <TResponse, TBody = unknown>(
+    path: string,
+    body?: TBody,
+    init?: Omit<ApiRequestOptions<TBody>, 'path' | 'method' | 'body'>,
+  ) => apiRequest<TResponse, TBody>({ path, method: 'PUT', body, ...init }),
+  patch: <TResponse, TBody = unknown>(
+    path: string,
+    body?: TBody,
+    init?: Omit<ApiRequestOptions<TBody>, 'path' | 'method' | 'body'>,
+  ) => apiRequest<TResponse, TBody>({ path, method: 'PATCH', body, ...init }),
+  delete: <TResponse>(path: string, init?: Omit<ApiRequestOptions, 'path' | 'method'>) =>
+    apiRequest<TResponse>({ path, method: 'DELETE', ...init }),
+};
+
+export default api;
+

src/app/types/api.types.ts

@@ -0,0 +1,20 @@
+/**
+ * API-related TypeScript types and interfaces
+ */
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+export type ApiRequestOptions<TBody = unknown> = {
+  path: string;
+  method?: HttpMethod;
+  body?: TBody;
+  headers?: HeadersInit;
+  signal?: AbortSignal;
+};
+
+export type ApiError = {
+  status: number;
+  message: string;
+  details?: unknown;
+};
+

src/app/types/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Central export point for all types
+ * Import types from here: import { SomeType } from '../types';
+ */
+
+export * from './api.types';
+

src/app/utils/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Utility functions and helpers
+ */
+
+/**
+ * Debounce function - delays execution until after wait time
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  wait: number
+): (...args: Parameters<T>) => void {
+  let timeout: NodeJS.Timeout | null = null;
+  return function executedFunction(...args: Parameters<T>) {
+    const later = () => {
+      timeout = null;
+      func(...args);
+    };
+    if (timeout) clearTimeout(timeout);
+    timeout = setTimeout(later, wait);
+  };
+}
+
+/**
+ * Format error message from API error or string
+ */
+export function formatError(error: unknown): string {
+  if (typeof error === 'string') return error;
+  if (error && typeof error === 'object' && 'message' in error) {
+    return String(error.message);
+  }
+  return 'An unexpected error occurred';
+}
+
+/**
+ * Sleep/delay utility
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Check if value is empty (null, undefined, empty string, empty array, empty object)
+ */
+export function isEmpty(value: unknown): boolean {
+  if (value == null) return true;
+  if (typeof value === 'string') return value.trim().length === 0;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === 'object') return Object.keys(value).length === 0;
+  return false;
+}
+

src/index.css

@@ -1,13 +1,19 @@
-body {
-  margin: 0;
-  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
-    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  font-family: 'Inter', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI',
     sans-serif;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
+  color: #0f172a;
+  background-color: #f8fafc;
 }
 
-code {
-  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
-    monospace;
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
 }

src/index.js

@@ -1,13 +1,16 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import './index.css';
-import App from './App';
+import App from './app/App.tsx';
+import ErrorBoundary from './app/components/common/ErrorBoundary.tsx';
 import reportWebVitals from './reportWebVitals';
 
 const root = ReactDOM.createRoot(document.getElementById('root'));
 root.render(
   <React.StrictMode>
-    <App />
+    <ErrorBoundary>
+      <App />
+    </ErrorBoundary>
   </React.StrictMode>
 );
 

tailwind.config.js

@@ -0,0 +1,9 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ['./src/**/*.{js,jsx,ts,tsx}'],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
+