frontend/
├── app/[locale]/          # Next.js App Router pages
│   ├── (auth)/           # Auth pages (login, register, etc.)
│   ├── dashboard/        # Dashboard pages
│   ├── tools/            # Tool pages
│   ├── pricing/          # Pricing page
│   └── layout.tsx        # Root layout
├── components/           # React components
│   ├── ads/             # Ad components (feature-flagged)
│   ├── auth/            # Auth components
│   ├── dashboard/       # Dashboard components
│   ├── home/            # Homepage sections
│   ├── layout/          # Header, Footer, Nav
│   ├── pricing/         # Pricing components
│   ├── shared/          # Shared components
│   ├── tools/           # Tool components
│   └── ui/              # shadcn/ui components
├── config/              # Configuration files
│   ├── constants.ts     # App constants
│   ├── routes.config.ts # Route definitions
│   └── tools.config.ts  # 62 tools metadata
├── contexts/            # React contexts
│   ├── AuthContext.tsx  # Authentication state
│   └── JobContext.tsx   # Job processing state
├── hooks/               # Custom React hooks
├── i18n/                # Internationalization
├── lib/                 # Core utilities
│   ├── api.ts          # Axios client
│   ├── auth.ts         # Auth utilities
│   ├── queryClient.ts  # React Query config
│   ├── storage.ts      # Token storage
│   └── utils.ts        # General utilities
├── messages/            # Translation files
│   ├── en.json         # English (162+ keys)
│   └── fr.json         # French (162+ keys)
├── services/            # API service layer
│   ├── auth.service.ts # Authentication
│   ├── tool.service.ts # Tool processing
│   ├── upload.service.ts # File uploads
│   └── user.service.ts # User management
├── types/               # TypeScript types
├── utils/               # Utility functions
└── .env.local          # Environment variables

## Getting Started

### Prerequisites

- Node.js 18+ 
- npm or yarn
- Backend API running on port 4000

### Installation

1. Install dependencies:
```bash
npm install

Configure environment:

# .env.local is already configured
# Update NEXT_PUBLIC_API_BASE_URL if needed

Run development server:

npm run dev

Open http://localhost:3000

Key Features

🌍 Internationalization (i18n)

Supported Languages: English (EN), French (FR)
Hybrid Strategy: Frontend translates UI, backend translates errors
Auto-detection: Locale from URL path (/en/*, /fr/*)
Locale Sync: Accept-Language header sent to backend

🔐 Authentication

Backend-driven: JWT tokens (access + refresh)
Auto-refresh: Axios interceptor handles token renewal
Protected Routes: AuthGuard component
Session Management: Multi-device session tracking

📁 File Processing

Tier-based Limits: FREE (15MB), PREMIUM (200MB)
Real-time Status: Job polling every 2 seconds
Batch Processing: Premium users can process 10 files
Progress Tracking: Upload and processing progress

📢 Ads Infrastructure

Feature-flagged: NEXT_PUBLIC_SHOW_ADS=false (disabled by default)
Tier-aware: Hidden for premium users
Layout-safe: Reserved space prevents shifts
Ready for AdSense: Placeholder components ready

Architecture

State Management

Server State: React Query (API data, jobs, users)
Auth State: AuthContext (user, tokens, tier)
Job State: JobContext (active jobs tracking)
Local State: React hooks (forms, UI)

API Integration

Base URL: Configured via NEXT_PUBLIC_API_BASE_URL
Auto-retry: 3 retries with exponential backoff
Token Refresh: Automatic on 401 responses
Locale Headers: Accept-Language automatically injected

Routing

App Router: Next.js 16 file-based routing
Localized: All routes prefixed with locale (/en/*, /fr/*)
Protected: Dashboard routes require authentication
Dynamic: Tool pages generated dynamically

Environment Variables

Key variables in .env.local:

# API
NEXT_PUBLIC_API_BASE_URL=http://localhost:4000

# i18n
NEXT_PUBLIC_DEFAULT_LOCALE=en
NEXT_PUBLIC_SUPPORTED_LOCALES=en,fr

# File Limits
NEXT_PUBLIC_MAX_FILE_SIZE_FREE_MB=15
NEXT_PUBLIC_MAX_FILE_SIZE_PREMIUM_MB=200

# Feature Flags
NEXT_PUBLIC_SHOW_ADS=false
NEXT_PUBLIC_ENABLE_BATCH_UPLOAD=true

See .env.local for the full list of variables.

Development

Run Locally

npm run dev

Build for Production

npm run build
npm run start

Linting

npm run lint

Deployment

Optimized for Vercel:

Connect GitHub repo to Vercel
Set environment variables in Vercel dashboard
Deploy automatically on push to main

Environment Variables for Production

NEXT_PUBLIC_API_BASE_URL=https://api.filezzy.com
NEXT_PUBLIC_SITE_URL=https://filezzy.com
NEXT_PUBLIC_ENV=production

Testing

The application is designed to work with the backend API. Ensure the backend is running before testing.

Test Flows

Guest User: Visit homepage → Click tool → Upload file → Process → Download
Registration: Click Sign Up → Fill form → Verify email → Login
Dashboard: Login → View stats → Check job history
Language: Click globe icon → Select French → Verify UI updates

Performance

Code Splitting: Dynamic imports for heavy components
Image Optimization: Next.js Image component
Caching: React Query with 5-minute stale time
SSR/SSG: Server-side rendering for SEO

Accessibility

WCAG 2.1 AA: Compliant via shadcn/ui
Keyboard Navigation: Full keyboard support
Screen Readers: ARIA labels and semantic HTML
Color Contrast: 4.5:1 minimum ratio

Support

For issues or questions:

Email: support@filezzy.com
Docs: See /specs/010-frontend-integration/

Built with ❤️ for Filezzy