# Dolphin Japan — Engineering Guidelines
> Authoritative engineering rules for **humans and AI assistants** working on
> the Dolphin Japan frontend. Read this before writing any code. When this
> document conflicts with anything else in the repository, **this document
> wins**.
>
> Companion docs:
> - [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md) – architectural contract
> - [`docs/API.md`](../docs/API.md) – endpoint contract for the backend team
> - [`docs/DEVELOPMENT.md`](../docs/DEVELOPMENT.md) – local dev workflow
> - [`guidelines/AdminPanelPlan.md`](AdminPanelPlan.md) – admin-panel module spec
> - [`docs/MIGRATION_NOTES.md`](../docs/MIGRATION_NOTES.md) – Vite → Next migration log
---
## 1. Project at a glance
**Dolphin Japan** is a Japanese used-car export e-commerce platform. The
codebase serves **two surfaces** from a single Next.js application:
| Surface | Route group | Audience | Layout |
| --------------- | ----------------- | ------------------- | ------------------------------------------- |
| Public shop | `src/app/(shop)/` | End customers | `PublicLayout` (header / footer) |
| Admin panel | `src/app/admin/` | Internal staff | `AdminLayout` (sidebar / topbar, noindex) |
| Auth (planned) | `src/app/(auth)/` | Admin login | minimal layout (no chrome) |
The two surfaces share the same `src/features/*` and `src/shared/*` code, so
**a single set of guidelines applies to both**. Surface-specific rules are
called out in §11 (Public-shop specifics) and §12 (Admin-panel specifics).
### Tech stack (canonical)
| Concern | Pin |
| --------------- | ---------------------------------------- |
| Framework | Next.js 15 (App Router) |
| Runtime | React 19 / TypeScript strict |
| Styling | Tailwind CSS v4 + CSS variables |
| UI primitives | shadcn/ui (preferred), MUI (legacy only) |
| State | Zustand 5 (per-feature stores) |
| Forms | react-hook-form |
| Icons | lucide-react |
| Animation | motion (Framer Motion successor) |
| Charts | recharts |
| Data fetching | Custom `apiFetch` wrapper, no SWR/RQ yet |
> **Do not introduce a new dependency without a clear reason** that could not
> be solved with the libraries above. Adding `axios`, `swr`, `react-query`,
> `redux`, `formik`, `material-ui` to new code requires explicit approval.
---
## 2. Folder structure (Feature-Sliced Design)
```
src/
├── app/ # Next.js App Router – ROUTES ONLY, no business logic
│ ├── layout.tsx # Root , fonts, global metadata
│ ├── globals.css # Aggregates tailwind/theme/admin/fonts
│ ├── (shop)/ # Public route group — wraps PublicLayout
│ ├── (auth)/ # Auth route group (when login lands)
│ └── admin/ # Admin routes — wraps AdminLayout, noindex
│
├── features/ # DOMAIN MODULES — the real product code
│ └── {feature}/
│ ├── components/ # Feature UI (admin/ subfolder if needed)
│ ├── hooks/ # use{Feature}, use{Feature}Form …
│ ├── services/ # {feature}Api.ts — HTTP calls
│ ├── store/ # Zustand slice(s)
│ ├── types/ # {feature}.types.ts
│ ├── data/ # dummy.ts — fallback fixtures
│ └── utils/ # Feature-only helpers
│
└── shared/ # CROSS-FEATURE REUSABLE CODE
├── components/
│ ├── ui/ # shadcn primitives — editable in-tree
│ ├── layout/ # PublicLayout, etc.
│ └── figma/ # Figma helpers (ImageWithFallback)
├── hooks/
├── lib/ # api.ts, constants.ts, router-compat.tsx, utils.ts
└── types/ # Cross-cutting types (api.types.ts)
```
### Existing features (do not invent new top-level folders without justification)
`vehicles` · `contact` · `orders` · `inquiry` · `payments` · `gallery` ·
`faq` · `pricing` · `admin` · `auth` · `home`
---
## 3. The dependency rule (read this twice)
```
app → features → shared ✅
shared → features ❌ FORBIDDEN
features/{a} → features/{b} ❌ FORBIDDEN
```
If feature A genuinely needs something feature B owns, **lift it to
`src/shared/`**. There is no exception.
`page.tsx` files in `src/app/` are **thin adapters** — they should usually
import a feature component and add metadata. **No data fetching or business
logic in `app/`.**
---
## 4. File and naming conventions
| Concern | Rule | Example |
| ------------------- | -------------------------------------------------------- | ---------------------------------------- |
| Component file | `PascalCase.tsx` | `VehicleCard.tsx` |
| Hook file | `useThing.ts` | `useVehicles.ts` |
| Type file | `kebab-case.types.ts` | `vehicle.types.ts` |
| Service file | `{feature}Api.ts` | `vehiclesApi.ts` |
| Store file | `{feature}Store.ts` | `vehiclesStore.ts` |
| Util / data | `kebab-case.ts` | `format-mileage.ts`, `dummy.ts` |
| Test file | `{name}.test.ts(x)` | `vehicleCard.test.tsx` |
| Route folder names | `kebab-case` | `order-custom`, `body-style` |
| Dynamic segment | `[param]` | `cars/[id]` |
| Boolean variables | `is*`, `has*`, `should*` | `isLoading`, `hasNextPage` |
| Event handlers | `handleX` inside the component, `onX` as prop | `` |
Every directory must have a clear, single responsibility. If a folder accrues
unrelated files, split it.
---
## 5. Imports
```ts
// ✅ Always use the @/ alias for cross-folder imports
import { Button } from '@/shared/components/ui/button';
import { cn } from '@/shared/lib/utils';
import { api } from '@/shared/lib/api';
import type { Vehicle } from '@/features/vehicles/types/vehicle.types';
// ✅ Relative paths only inside the same feature
import { vehiclesApi } from './services/vehiclesApi';
import type { Vehicle } from '../types/vehicle.types';
// ❌ Never use deep relative paths across the tree
import { Button } from '../../../shared/components/ui/button'; // ❌
// ❌ Never import directly between features
// from src/features/orders/components/OrderForm.tsx:
import type { Vehicle } from '@/features/vehicles/types/vehicle.types'; // ❌
```
Order imports as: **(1) external packages → (2) `@/shared/...` → (3)
`@/features/...` → (4) relative**, with a blank line between groups.
---
## 6. Server vs. client components
* **Default to Server Components** in `src/app/`.
* Add `'use client'` **at the top of the file** only when you need:
hooks (`useState`, `useEffect`, `useReducer`, refs), event handlers,
browser APIs, or a third-party client library.
* Heavy interactive UIs should be a single `'use client'` boundary at the
top of the feature component, not sprinkled across many files.
* Page (`page.tsx`) and layout (`layout.tsx`) files in `src/app/` should
usually stay as Server Components.
If a component is purely presentational and accepts only serializable props,
do **not** mark it `'use client'`.
---
## 7. Data layer — the API contract
All HTTP traffic flows through:
```ts
import { api, withDummyFallback } from '@/shared/lib/api';
```
### 7.1 Service files
Every feature owns a service file at
`src/features/{feature}/services/{feature}Api.ts`. Service functions:
* **Return the unwrapped `data`** — `apiFetch` peels off the
`{ success, data, message }` envelope automatically.
* **Use `withDummyFallback`** for any read/write that should remain usable
before the backend ships. Pattern:
```ts
import { api, withDummyFallback } from '@/shared/lib/api';
import { buildQuery } from '@/shared/lib/utils';
import type { Paginated, ListQuery } from '@/shared/types/api.types';
import type { Vehicle } from '../types/vehicle.types';
import { DUMMY_VEHICLES } from '../data/dummy';
export const listVehicles = (q: ListQuery = {}) =>
withDummyFallback(
() => api.get>(`/vehicles${buildQuery(q)}`),
() => ({
items: DUMMY_VEHICLES,
total: DUMMY_VEHICLES.length,
page: 1,
pageSize: DUMMY_VEHICLES.length,
pageCount: 1,
}),
);
```
* **Never** call `fetch()` directly in a component or hook — always go
through the service.
### 7.2 Update [`docs/API.md`](../docs/API.md) on every endpoint touch
When you add, remove, or rename an endpoint:
1. Add/update the row in `docs/API.md`.
2. Mark its status — 🟡 Planned · 🟢 Live · 🔴 Deprecated.
3. Document the request and response shape.
This file is the **single source of truth** the backend team consumes.
### 7.3 Errors
* `apiFetch` throws `ApiClientError` on non-2xx (with `status` and `body`).
* Components should surface errors via the toast system (`sonner`) or a
dedicated error UI — never via `alert()` or by ignoring rejections.
* Inside a Zustand store action, catch the error and store it in
`state.error: string | null`.
---
## 8. State management (Zustand)
* One store slice per feature, at
`src/features/{feature}/store/{feature}Store.ts`.
* Export **selector hooks** so components subscribe to the smallest possible
slice:
```ts
export const useVehicleList = () => useVehiclesStore((s) => s.list);
export const useSelectedVehicle = () => useVehiclesStore((s) => s.selected);
```
* Do **not** create a global "master" store.
* Persist only what is genuinely needed across reloads (auth token, theme).
Use `zustand/middleware`'s `persist` and **partialize** carefully:
```ts
persist(creator, {
name: 'dj.auth',
partialize: (s) => ({ token: s.token }),
})
```
* Mutations: `set({ ... })` is fine for shallow updates; reach for `produce`
from `immer` only if a slice gets genuinely nested (and you must add immer
to dependencies first).
---
## 9. Components
### 9.1 Definition style
```tsx
type Props = {
vehicle: Vehicle;
onSelect?: (id: string) => void;
};
export function VehicleCard({ vehicle, onSelect }: Props) {
// …
}
```
* **Named exports** for components. Default exports only for
`app/**/{page,layout,error,not-found}.tsx`.
* Always type props inline as `type Props = { … }`.
* Destructure props in the signature; do not use `props.x` inside the body.
### 9.2 Decomposition
* Keep a component under **~150 lines**. If it grows past that:
1. Extract subcomponents that own their own slice of UI.
2. Move logic into a `useThing()` hook in the same feature.
3. Move pure helpers into the feature's `utils/`.
### 9.3 Lists & keys
* Use a stable, unique `id` field as the React `key`. Never use the array
index unless the list is genuinely static and order-independent.
### 9.4 Forms
* `react-hook-form` + shadcn `Form` primitives for any form with > 1 field.
* Validate with a single source of truth — typically a `z.object({...})`
schema in `{feature}/schemas/`. (Add `zod` only when you reach for it; do
not pre-emptively wire it up.)
* Submit handlers go through the feature's service file.
### 9.5 Accessibility
* Every interactive element must be reachable via keyboard.
* Inputs must have an associated `