# 🚀 Enterprise Next.js Boilerplate (Antigravity Edition)

[![Next.js](https://img.shields.io/badge/Next.js%2016-000000?style=for-the-badge&logo=next.js&logoColor=white)](https://nextjs.org/)
[![React](https://img.shields.io/badge/React%2019-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://react.dev/)
[![Chakra UI](https://img.shields.io/badge/Chakra%20UI%20v3-319795?style=for-the-badge&logo=chakraui&logoColor=white)](https://chakra-ui.com/)
[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![next-intl](https://img.shields.io/badge/next--intl-0070F3?style=for-the-badge&logo=next.js&logoColor=white)](https://next-intl-docs.vercel.app/)

> **FOR AI AGENTS & DEVELOPERS:** This documentation is structured to provide deep context, architectural decisions, and operational details to ensure seamless handover to any AI coding assistant (like Antigravity) or human developer.

---

## 🧠 Project Context & Architecture (Read Me First)

This is an **opinionated, production-ready** frontend boilerplate built with Next.js 16 App Router. It is designed to work seamlessly with the companion **typescript-boilerplate-be** NestJS backend.

### 🏗️ Core Philosophy

- **Type Safety First:** Strict TypeScript configuration. DTOs and typed API responses connect frontend to backend.
- **App Router Native:** Built entirely on Next.js App Router with Server Components and React Server Actions support.
- **i18n Native:** Localization is baked into routing, API calls, and UI components via `next-intl`.
- **Theme-First Design:** Chakra UI v3 with custom theme system for consistent, accessible UI.
- **Auth by Default:** NextAuth.js integration with JWT token management and automatic session handling.

### 📐 Architectural Decision Records (ADR)

_To understand WHY things are the way they are:_

1.  **Locale-Based Routing:**
    - **Mechanism:** All routes are prefixed with locale (e.g., `/tr/dashboard`, `/en/login`).
    - **Implementation:** `next-intl` plugin with `[locale]` dynamic segment in `app/` directory.
    - **Config:** `localePrefix: 'always'` ensures consistent URL structure.

2.  **API Client with Auto-Auth & Locale:**
    - **Location:** `src/lib/api/create-api-client.ts`
    - **Feature:** Automatically injects JWT `Authorization` header from NextAuth session.
    - **Feature:** Automatically sets `Accept-Language` header based on current locale (cookie or URL path).
    - **Auto-Logout:** 401 responses trigger automatic signOut and redirect.

3.  **Backend Proxy (CORS Solution):**
    - **Problem:** Local development CORS issues when frontend (port 3001) calls backend (port 3000).
    - **Solution:** Next.js `rewrites` in `next.config.ts` proxies `/api/backend/*` → `http://localhost:3000/api/*`.
    - **Usage:** API clients use `/api/backend/...` paths in development.

4.  **Provider Composition:**
    - **Location:** `src/components/ui/provider.tsx`
    - **Stack:** `SessionProvider` (NextAuth) → `ChakraProvider` (UI) → `ColorModeProvider` (Dark/Light) → `Toaster` (Notifications)
    - **Why:** Single import in layout provides all necessary contexts.

---

## 🚀 Quick Start for AI & Humans

### 1. Prerequisites

- **Node.js:** v20.19+ (LTS)
- **Package Manager:** `npm` (Lockfile: `package-lock.json`)
- **Backend:** Companion NestJS backend running on port 3000 (see `typescript-boilerplate-be`)

### 2. Environment Setup

```bash
cp .env.example .env.local
# Edit .env.local with your configuration
```

**Required Environment Variables:**

| Variable                    | Description                                                     | Example                     |
| --------------------------- | --------------------------------------------------------------- | --------------------------- |
| `NEXTAUTH_URL`              | NextAuth callback URL                                           | `http://localhost:3001`     |
| `NEXTAUTH_SECRET`           | Authentication secret (generate with `openssl rand -base64 32`) | `abc123...`                 |
| `NEXT_PUBLIC_API_URL`       | Backend API base URL                                            | `http://localhost:3001/api` |
| `NEXT_PUBLIC_AUTH_REQUIRED` | Require login for all pages                                     | `true` or `false`           |

### 3. Installation & Running

```bash
# Install dependencies
npm ci

# Development Mode (HTTPS enabled, port 3001)
npm run dev

# Production Build
npm run build
npm run start
```

> **Note:** Dev server runs on port 3001 with experimental HTTPS for secure cookie handling.

---

## 🌍 Internationalization (i18n) Guide

Deep integration with `next-intl` provides locale-aware routing and translations.

### Configuration

- **Supported Locales:** `['en', 'tr']`
- **Default Locale:** `tr`
- **Locale Detection:** Cookie (`NEXT_LOCALE`) → URL path → Default

### File Structure

```
messages/
├── en.json       # English translations
└── tr.json       # Turkish translations

src/i18n/
├── routing.ts    # Locale routing configuration
├── navigation.ts # Typed navigation helpers (Link, useRouter)
└── request.ts    # Server-side i18n setup
```

### Usage in Components

```tsx
// Client Component
"use client";
import { useTranslations } from "next-intl";

export function MyComponent() {
  const t = useTranslations("common");
  return <h1>{t("welcome")}</h1>;
}

// Navigation with Locale
import { Link } from "@/i18n/navigation";

<Link href="/dashboard">Dashboard</Link>; // Auto-prefixes with current locale
```

### Adding a New Locale

1. Add locale code to `src/i18n/routing.ts`:
   ```ts
   export const locales = ["en", "tr", "de"]; // Add 'de'
   ```
2. Create `messages/de.json` with translations.
3. Update `getLocale()` in `create-api-client.ts` if needed.

---

## 🔐 Authentication System

Built on NextAuth.js with JWT strategy for seamless backend integration.

### How It Works

1. **Login:** User submits credentials → `/api/auth/[...nextauth]` → Backend validates → JWT returned.
2. **Session:** JWT stored in encrypted cookie, accessible via `useSession()` hook.
3. **API Calls:** `createApiClient()` automatically adds `Authorization: Bearer {token}` header.
4. **Auto-Refresh:** Token refreshed before expiry (managed by NextAuth).

### Protected Routes

```tsx
// Use middleware.ts or check session in layout
import { getServerSession } from "next-auth";

export default async function ProtectedLayout({ children }) {
  const session = await getServerSession();
  if (!session) redirect("/login");
  return <>{children}</>;
}
```

### Auth Mode Toggle

Set `NEXT_PUBLIC_AUTH_REQUIRED=true` for mandatory authentication across all pages.

---

## 🎨 UI System (Chakra UI v3)

### Theme Configuration

- **Location:** `src/theme/theme.ts`
- **Font:** Bricolage Grotesque (Google Fonts, variable font)
- **Color Mode:** Light/Dark with system preference detection

### Component Organization

```
src/components/
├── ui/                 # Chakra UI wrapper components
│   ├── provider.tsx    # Root provider (Session + Chakra + Theme)
│   ├── color-mode.tsx  # Dark/Light mode toggle
│   ├── feedback/       # Toaster, alerts, etc.
│   └── ...
├── layout/             # Page layout components (Header, Sidebar, Footer)
├── auth/               # Authentication forms and guards
└── site/               # Site-specific feature components
```

### Toast Notifications

```tsx
import { toaster } from "@/components/ui/feedback/toaster";

// Success toast
toaster.success({
  title: "Saved!",
  description: "Changes saved successfully.",
});

// Error toast
toaster.error({ title: "Error", description: "Something went wrong." });
```

---

## 📡 API Integration (Standard Architecture)

The project follows a strict **Service + Hook** pattern for API integration to ensure separation of concerns, type safety, and efficient caching.

**🏆 Golden Standard Reference:** [`src/lib/api/example`](src/lib/api/example)

### 🏗️ Architecture Pattern

For every domain (e.g., `auth`, `users`), we strictly follow this 4-layer structure:

| Layer | File | Purpose |
|-------|------|---------|
| **1. Types** | `types.ts` | **Contract:** pure TypeScript interfaces/DTOs matching Backend. |
| **2. Service** | `service.ts` | **Logic:** Pure functions calling `apiRequest`. Independent of React. |
| **3. Hooks** | `use-hooks.ts` | **State:** React Query wrappers (`useQuery`, `useMutation`) for caching & state. |
| **4. Barrel** | `index.ts` | **Public API:** Central export point for the module. |

### 📝 Implementation Guide

#### 1. Define Service (`service.ts`)
Uses `apiRequest` wrapper which handles client selection (`auth`, `core`, etc.), base URLs, and error normalization.

```ts
// src/lib/api/example/auth/service.ts
import { apiRequest } from "@/lib/api/api-service";
import { LoginDto, AuthResponse } from "./types";

const login = (data: LoginDto) => {
  return apiRequest<ApiResponse<AuthResponse>>({
    url: "/auth/login",
    client: "auth", // Selects the correct axios instance from clientMap
    method: "post",
    data,
  });
};

export const authService = { login };
```

#### 2. Create Hook (`use-hooks.ts`)
Wraps service in TanStack Query for loading states, caching, and invalidation.

```ts
// src/lib/api/example/auth/use-hooks.ts
import { useMutation } from "@tanstack/react-query";
import { authService } from "./service";

export const AuthQueryKeys = {
  all: ["auth"] as const,
};

export function useLogin() {
  return useMutation({
    mutationFn: (data: LoginDto) => authService.login(data),
  });
}
```

#### 3. Use in Components
Components only interact with the Hooks, never the Service or Axios directly.

```tsx
import { useLogin } from "@/lib/api/example"; // Import from barrel

export function LoginForm() {
  const { mutate, isPending } = useLogin();

  const handleSubmit = (data) => {
    mutate(data, {
      onSuccess: () => console.log("Logged in!"),
    });
  };
}
```

---

## 📂 System Map (Directory Structure)

```
src/
├── app/                    # Next.js App Router
│   ├── [locale]/           # Locale-prefixed routes
│   │   ├── (auth)/         # Auth pages (login, register)
│   │   ├── (site)/         # Main site pages
│   │   ├── (error)/        # Error pages
│   │   ├── layout.tsx      # Root layout with providers
│   │   └── page.tsx        # Home page
│   └── api/                # Next.js API routes
│       └── auth/           # NextAuth endpoints
├── components/             # React components
│   ├── ui/                 # Chakra UI wrappers & base components
│   ├── layout/             # Layout components (Header, Sidebar)
│   ├── auth/               # Auth-related components
│   └── site/               # Feature-specific components
├── config/                 # App configuration
├── hooks/                  # Custom React hooks
├── i18n/                   # Internationalization setup
├── lib/                    # Utilities & services
│   ├── api/                # API clients (organized by module)
│   │   ├── auth/           # Auth API (login, register)
│   │   ├── admin/          # Admin API (roles, users)
│   │   └── create-api-client.ts  # Axios factory with interceptors
│   ├── services/           # Business logic services
│   └── utils/              # Helper functions
├── theme/                  # Chakra UI theme configuration
├── types/                  # TypeScript type definitions
└── proxy.ts                # API proxy utilities

messages/                   # Translation JSON files
public/                     # Static assets
```

---

## 🧪 Testing & Development

### Available Scripts

```bash
npm run dev      # Start dev server (HTTPS, port 3001)
npm run build    # Production build
npm run start    # Start production server
npm run lint     # Run ESLint
```

### Development Tools

- **React Compiler:** Enabled for automatic optimization.
- **Top Loader:** Visual loading indicator for route transitions.
- **ESLint + Prettier:** Consistent code formatting.

---

## 🛠️ Troubleshooting (Known Issues)

**1. HTTPS Certificate Warnings in Development**

- **Context:** Dev server uses `--experimental-https` for secure cookies.
- **Fix:** Accept the self-signed certificate warning in your browser.

**2. Backend Connection Refused**

- **Fix:** Ensure NestJS backend is running on port 3000.
- **Check:** Run `curl http://localhost:3000/api/health` to verify.

**3. Session Not Persisting**

- **Fix:** Ensure `NEXTAUTH_SECRET` is set and consistent between restarts.
- **Fix:** Check that cookies are not blocked by browser settings.

**4. Locale Not Detected**

- **Context:** Default falls back to `tr` if cookie/URL detection fails.
- **Fix:** Clear `NEXT_LOCALE` cookie and refresh.

---

## 🔗 Related Projects

- **Backend:** [typescript-boilerplate-be](../typescript-boilerplate-be) - NestJS backend with Prisma, JWT auth, and i18n.

---

## 📃 License

This project is proprietary and confidential.
