Team: Web Team (UI)
Repo:AI-Background-Remover-frontend
Parent repo:AI-Background-Remover(this is a submodule)
Tech: React 18 · TypeScript · Tailwind CSS · Vite
The React frontend for the AI Background Remover application.
It handles everything the user sees and interacts with — uploading an image, watching it process, comparing the before/after, downloading the result, and browsing past jobs.
It talks to the backend repo via REST API calls through Axios.
It does not contain any AI or Python code.
frontend/
│
├── index.html ← app shell, loads Google Fonts
├── vite.config.ts ← Vite config, /api proxy to backend :8000, Vitest config
├── tailwind.config.ts ← maps CSS tokens to Tailwind utility classes
├── eslint.config.js ← ESLint flat config
├── postcss.config.js
├── tsconfig.json
├── package.json
│
└── src/
├── main.tsx ← entry point, imports theme tokens
├── index.css ← Tailwind base layers
├── App.tsx ← BrowserRouter, providers, route declarations
├── types.ts ← shared TypeScript types (chat, image analysis)
│
├── theme/
│ └── tokens.css ← ALL design tokens (colors, fonts, radius)
│ light mode + dark mode variables
│ .bg-checker utility class
│
├── components/ ← reusable UI building blocks (tests in __tests__/)
├── contexts/ ← React contexts and providers (auth, toast, theme,
│ workspace, brand kit, active image)
├── hooks/ ← data-fetching and state logic
├── pages/ ← one file per route
├── services/ ← API clients and helpers (apiClient, chatService, ...)
├── utils/ ← pure helpers such as validation and apiError
└── test/ ← Vitest setup and shared mock data
All routes are declared in src/App.tsx. Pages are lazy-loaded.
| Route | Page | Access |
|---|---|---|
/login |
LoginPage |
Public |
/register |
RegisterPage |
Public |
/auth/callback |
AuthCallbackPage |
Public (Google/GitHub sign-in landing) |
/forgot-password |
ForgotPasswordPage |
Public |
/reset-password |
ResetPasswordPage |
Public |
/ |
HomePage |
Login required |
/enhance |
EnhancePage |
Login required |
/replace-bg |
ReplaceBgPage |
Login required |
/recolor-and-eraser |
RecolorAndEraserPage |
Login required |
/smart-crop |
SmartCropPage |
Login required |
/batch |
BatchPage |
Login required |
/shadow |
ShadowPage |
Login required |
/history |
HistoryPage |
Login required |
/settings |
SettingsPage |
Login required |
/ai-analysis |
AIAnalysisPage |
Login required |
/similarity-search |
SimilaritySearchPage |
Login required |
* |
NotFoundPage |
Public |
Each page renders its own <main> element. Do not wrap pages in another <main>.
- Shows
UploadZone— user drags or picks an image. - Calls
useUpload— sends the image to the backend. - While processing, shows a spinner.
- On success, shows
ImageCanvas(result/original/compare) andDownloadButton. - "Remove another" button resets to step 1.
- Calls
useHistoryon mount. - Renders a responsive grid of
HistoryCardcomponents. - Each card shows the processed image thumbnail, filename, date, download link, and a delete button.
- Handles loading, error, and empty states.
All colors, fonts, and spacing come from src/theme/tokens.css as CSS custom properties.
Never hardcode hex values in components. Always use the Tailwind utilities mapped in tailwind.config.ts.
| Token | Tailwind class | When to use |
|---|---|---|
--bg-page |
bg-page |
Page background |
--bg-surface |
bg-surface |
Cards, panels |
--accent-magenta |
bg-magenta, text-magenta |
Primary CTAs, active states |
--accent-teal |
bg-teal, text-teal |
Success, download actions |
--text-primary |
text-primary |
Headings, labels |
--text-muted |
text-muted |
Hints, secondary info |
.bg-checker |
bg-checker class |
Any area showing transparency |
Dark mode is toggled by setting data-theme="dark" on <html>.
ThemeToggle.tsx handles this. No Tailwind dark: prefix needed — tokens handle it.
# Make sure you are inside the frontend/ folder
# Copy environment config (optional — only needed for production API URL or allowed email domains)
cp .env.example .env
npm install
npm run devApp runs at http://localhost:5173.
All /api/* requests are proxied to http://localhost:8000 (the backend must be running).
Other commands:
npm run build # type-check + production build → dist/
npm run preview # preview the production build locally
npm run typecheck # TypeScript check only, no build output
npm run lint # run ESLint (warnings count as failures)
npm test # run all tests once
npm run test:watch # re-run tests on file changesBefore opening a pull request, make sure npm run typecheck, npm run lint, npm test and npm run build all pass.
Tests use Vitest with React Testing Library and jsdom.
- Test files live in
__tests__/folders next to the code they test, for examplesrc/components/__tests__/andsrc/utils/__tests__/. The pattern invite.config.tsissrc/**/__tests__/**/*.{test,spec}.{ts,tsx}. - Global setup is in
src/test/setup.ts; shared mock data is insrc/test/mocks/. - Test files are excluded from
tsc, so they are not type-checked duringnpm run build.
- Create the file in
src/components/YourComponent.tsx. - Use only Tailwind classes that map to design tokens (see table above).
- Add
aria-label/roleattributes for accessibility. - Export as default.
- Import it in the page or component that needs it.
- Add a test in
src/components/__tests__/YourComponent.test.tsx.
- Create
src/pages/YourPage.tsx(render your own<main>as the page root). - Add a
<Route>for it insrc/App.tsx. - Add a
<NavLink>insrc/components/Navbar.tsx.
- Create
src/hooks/useYourHook.ts. - Keep all API calls inside hooks — never call
axiosdirectly from a component. - Return
{ data, loading, error }shape so components stay consistent.
| Action | Hook | Endpoint |
|---|---|---|
| Upload image | useUpload |
POST /api/remove-background |
| Download result | DownloadButton |
GET /api/download/{filename} |
| Get history | useHistory |
GET /api/history |
| Delete image | useHistory.deleteItem |
DELETE /api/image/{id} |
The backend must be running on port 8000 for the proxy to work in development.
Versions below are the ranges declared in package.json.
| Package | Version | Purpose |
|---|---|---|
| react | ^18.3.1 | UI framework |
| react-dom | ^18.3.1 | DOM rendering |
| react-router-dom | ^6.26.2 | Client-side routing |
| axios | ^1.7.7 | HTTP requests |
| react-dropzone | ^14.2.9 | Drag-and-drop file upload |
| jszip | ^3.10.1 | ZIP export |
| dompurify | ^3.2.6 | HTML sanitising |
| tailwindcss | ^3.4.13 | Utility CSS |
| vite | ^5.4.7 | Dev server + build tool |
| typescript | ^5.5.4 | Type safety |
| vitest | ^4.1.11 | Test runner |
| @testing-library/react | ^16.3.2 | Component testing |
- Full project scaffold (Vite + React + TypeScript + Tailwind)
- Design token system (light + dark mode)
- Navbar with routing and theme toggle
- UploadZone with validation
- useUpload hook with state machine
- ImageCanvas with result / original / compare slider
- DownloadButton
- HistoryCard
- useHistory hook
- HomePage full flow
- HistoryPage with all states
- User authentication UI (login / register / password reset pages)
- Email verification on sign-up (
VerifyEmailForm) - Background replacement panel (color picker, custom image upload)
- Toast notification system for errors/success
- Vitest setup with component and utility tests
- Batch upload — via the AI Chatbot Widget (Analyze/Suggest/Caption modes)
- Loading skeleton components (replace spinners)
- Mobile layout polish
A floating AI assistant (src/components/ChatbotWidget.tsx) available on every page, with four modes: Chat, Analyze, Suggest, and Caption.
- Multi-line auto-expanding textarea (36px → 140px)
- Live character counter (0/2000) with warning color near the limit
- Image attachment with preview strip before sending
- Per-message quick actions on hover: Edit & resend, Resend, Copy, Delete
- Drag-to-resize panel from the corner grip
- Four floating positions (bottom-right, bottom-left, top-right, top-left) via the position switcher
- Size presets: compact / standard / large
- Minimize to a small pill in the tray
- Fullscreen mode for complex tasks
- Panel position/size is clamped to the viewport so it can never render off-screen;
Escalways closes the widget as a safety fallback
- Template library — save, reuse, and delete prompt templates (backend:
GET/POST /api/prompts,POST /api/prompts/{id}/use,DELETE /api/prompts/{id}) - Favorite responses — star useful AI replies to save them (backend:
GET/POST /api/favorites,DELETE /api/favorites/{id}) - Batch operations — run Analyze/Suggest/Caption on up to 10 images sequentially from one panel
- Context memory — the last few conversation turns are included in each new request
- Topic detection — messages are auto-tagged (background, lighting, crop, quality, caption, general) with a badge on assistant replies
- Intent recognition — messages are classified as greeting / question / request / feedback / other
- Follow-up suggestions — topic-relevant follow-up chips appear after each assistant reply
| File | Purpose |
|---|---|
src/services/chatService.ts |
POST /api/chat |
src/services/imageService.ts |
POST /api/image/analyze, /captions, /suggestions |
src/services/favoriteService.ts |
Favorites CRUD |
See CONTRIBUTING.md in the parent repo for branch naming, commit format, and PR rules.
Your branch always goes into this submodule repo (AI-Background-Remover-frontend), not the parent.