# AI Agent Spec: Legacy App → Next.js 16 (excerpt)

## Project Structure

~~~
src/
├── app/
│   ├── (main)/          # public routes, own layout.jsx
│   │   └── api/v1/[resource]/route.js
│   ├── (admin)/         # protected routes, own layout.jsx
│   ├── global-error.jsx
│   └── global-not-found.jsx
├── lib/
│   ├── store.js, features/*Slice.js   # Redux
│   ├── actions/         # Server Actions
│   └── models/          # DB access
├── ui/main/components/ComponentName/
│   ├── ComponentName.jsx
│   ├── ComponentName.scss
│   └── ComponentName.test.jsx
└── utils/session, api, security, ...
~~~

One component per folder. Never put components directly under `src/app/`.

## Server vs Client Components

Default to Server Components. Add `"use client"` only for hooks, browser APIs, event handlers, or DOM-dependent libraries. Push the directive to the smallest leaf component, never to a whole page or layout.

~~~jsx
// page.jsx — Server Component
export default async function ExamplePage() {
  const data = await fetchData();
  return <InteractiveWidget initialData={ data } />;
}
~~~

## API Routes

- Live under `(main)/api/v1/[resource]/route.js`, export `GET`/`POST`/etc.
- Validate the session first, return `401` if missing.
- Delegate logic to `src/lib/models/`; keep handlers thin.
- Consistent shape: `{ ok: true, data }` / `{ ok: false, error }`.

## Auth

- Session token in an HttpOnly cookie, read via `next/headers` `cookies()`. Never expose it to JS.
- Client only holds derived state (Redux `auth` slice), never the raw token.
- Auth mutations are Server Actions (`"use server"`).

## Code Style

- Double quotes, curly braces always required, `{ foo }` spacing in JSX.
- No `console.log` (warn/error/info are fine).
- No TypeScript — JS + PropTypes.
- SCSS: `@use`, not `@import`; BEM-like naming (`.card__title`, `.card_featured`).

## Anti-Patterns

- No `getInitialProps`/`getServerSideProps`.
- No client-side calls to external APIs — proxy through `/api/v1/`.
- No session tokens in `localStorage` or React state.
- No unnecessary abstractions or explanatory comments.

# AI Agent Spec: Admin UI CRUD Interface (excerpt)

Internal framework: Next.js App Router + Ant Design + Redux Toolkit + a custom REST client/model layer.

## File Structure (per entity)

~~~
src/
├── app/(admin)/admin/[section]/[entity]/
│   ├── layout.jsx     # fetches table data server-side, renders Table
│   ├── page.jsx       # returns null
│   └── [id]/page.jsx  # fetches one record, renders EditModal
├── lib/
│   ├── api/admin/[Entity].js      # REST connector (client-side)
│   └── models/admin/[Entity].js   # DB model (server-side)
└── ui/admin/components/Main/[Section]/[Entity]/
    ├── [Entity]Table.jsx
    └── [Entity]EditModal.jsx
~~~

## Model

~~~js
import AbstractModel from "./AbstractModel";

export default class TagModel extends AbstractModel {
  table = "tag";
}
~~~

Extend `AbstractModel`, set `table`, add custom query methods only if needed. Base class already provides `findAll`, `find`, `add`, `update`, `remove`, `removeSelected`.

## API Connector

~~~js
import AbstractAdminRestClient from "./AbstractAdminRestClient";

class TagApi extends AbstractAdminRestClient {
  collection = "tags";
}

export const entityApi = new TagApi();
~~~

Always export the instance as `entityApi` — `UiTable` and `UiModalForm` consume it directly. Override `add`/`update` only when the payload needs shaping (e.g. `cleanDeep()`, `JSON.stringify()` on arrays).

## Table Component

~~~jsx
"use client";
import UiAdvancedTable from "@/ui/admin/components/UiTable/UiAdvancedTable";
import { entityApi as api } from "@/lib/api/admin/Tag";

export default function TagTable(props) {
  const columns = [
    { title: "Name", dataIndex: "name", sorter: true, getColumnSearchProps: "name" },
    { title: "Actions", key: "action", width: "120px", actions: "EditDelete" }
  ];

  return (
    <UiAdvancedTable
      columns={ columns }
      api={ api }
      enableSelection={ true }
      prefetchedData={ props.initialTableData }
      { ...props }
    />
  );
}
~~~

Use `UiTable` for simple lists, `UiAdvancedTable` when a column needs search.

## Modal Form Component

~~~jsx
"use client";
import UiModalForm from "@/ui/admin/components/UiModalForm/UiModalForm";
import { Form, Input } from "antd";
import { entityApi as api } from "@/lib/api/admin/Tag";

export default function TagEditModal({ pk, initialFormData }) {
  return (
    <UiModalForm pk={ pk } api={ api } initialValues={ initialFormData ?? { name: "" } }>
      { ({ onKeyDown }) => (
        <Form.Item label="Name" name="name" rules={ [{ required: true }, { min: 3 }] }>
          <Input onKeyDown={ onKeyDown } />
        </Form.Item>
      ) }
    </UiModalForm>
  );
}
~~~

`pk` falsy = create, truthy = edit. Use `transformInitialValues` / `transformFormData` to parse/serialize complex fields (arrays, JSON columns).

## Route Files

~~~jsx
// page.jsx — always returns null, layout renders everything
export default function EntityPage() { return null; }
~~~

~~~jsx
// layout.jsx — fetches list server-side, always force-dynamic
export const dynamic = "force-dynamic";

export default async function EntityLayout({ children }) {
  const initialTableData = await model.findAll();
  return (
    <>
      { children }
      <EntityTable initialTableData={ initialTableData } />
    </>
  );
}
~~~

~~~jsx
// [id]/page.jsx — fetches one record, renders the modal
export const dynamic = "force-dynamic";

export default async function EntityModalPage({ params }) {
  const { id } = await params ?? {};
  const initialFormData = id ? await model.find(id) : null;
  return <EntityEditModal pk={ id } initialFormData={ initialFormData } />;
}
~~~

## CRUD Flow

1. `layout.jsx` fetches `model.findAll()`, passes it to the Table as `prefetchedData`.
2. Add/Edit navigates to the `[id]` route.
3. `[id]/page.jsx` fetches `model.find(pk)`, passes it to the modal.
4. Modal opens pre-populated; submit runs `transformFormData` then `api.add()`/`api.update()`.
5. On success, the table refetches; the layout persists underneath the modal the whole time.

## Anti-Patterns

- No `"use client"` on layout/page files — they're Server Components.
- No calling `model.*` from client components — models are server-only.
- No fetching inside `UiTable`/`UiModalForm` via `useEffect` — always pass `prefetchedData`.
- Don't omit `export const dynamic = "force-dynamic"` on admin layouts and pages.
- Don't override base API/model methods unless the payload shape actually differs.

# Project Goal (excerpt)

Migrate the legacy Hugo site at `/home/sheiko/projects/legacy` to Next.js 16 (App Router) + JavaScript (no TypeScript) + SCSS + MariaDB. Build the new app in the current directory, incrementally, staying runnable throughout.

## Source of Truth

The legacy Hugo project is read-only and authoritative.

- Reproduce existing functionality, content, URLs, and visual design as closely as possible.
- Modernize the implementation, not the design.
- Reuse existing assets (fonts, images, icons); preserve HTML structure and class names where practical.

## Frontend

- Extract reusable React components, follow App Router conventions.
- Prefer Server Components unless interactivity is required.
- Preserve URLs and SEO/Open Graph metadata.

## Content

Import all blog posts into MariaDB (design the schema), render pages dynamically, preserve all metadata (title, slug, date, tags, categories, excerpt, body, SEO fields).

## Administration

Build a CMS under `/admin` using Ant Design v5 (header + collapsible sidebar + content area), following `admin-ui-agent-spec.md`.

Auth flow: unauthenticated users see only the header and login page (no sidebar, no protected pages); after login, show the sidebar and go to the dashboard; after logout, return to login.

Seed an `admin_user` table with a default `admin`/`admin` account, password hashed with bcrypt.

## Database

Use dbmate for all schema changes, no exceptions. Never hardcode credentials — stop and ask for the MariaDB root password before any privileged operation.

## Development Rules

Follow `nextjs16-migration-agent-spec.md` for implementation details; it takes precedence over ad hoc decisions. If something can't be inferred from the legacy site or the spec, stop and ask rather than assume.

Migrate the legacy application located at /home/sheiko/projects/coreui (http://localhost:3000/) into a new Next.js application (running on port 3003) in the current directory (JavaScript only).

The project at /home/sheiko/projects/coreui is the source of truth. Keep the new implementation as close as possible to the legacy application's design, styling, layout, and functionality while adopting modern Next.js architecture and best practices.

Make sure you have Playwright access. 
Act as a visual regression engineer.
Open legacy page http://localhost:3000. Take screenshot.
Open Next.js page http://localhost:3003. Take screenshot.
List all visual differences.
Fix them one by one.
Repeat until only negligible differences remain.

import { chromium } from "playwright";
import { PNG } from "pngjs";
import pixelmatch from "pixelmatch";
import fs from "fs";

const legacy = "http://localhost:3000/";
const next   = "http://localhost:3003/";

const b = await chromium.launch();
const [p1, p2] = [ await b.newPage(), await b.newPage()];
await p1.goto( legacy, { waitUntil: "networkidle"} ); await p1.setViewportSize( { width:1440, height:900 } );
await p2.goto( next,   { waitUntil: "networkidle"} ); await p2.setViewportSize( { width:1440, height:900 } );

// dev-server-only UI that isn't part of the app itself
await p1.evaluate( () => document.getElementById( "__bs_notify__" )?.remove() );
await p2.evaluate( () => document.querySelector( "nextjs-portal" )?.remove() );

// give client-side chart rendering (Chart.js canvases) time to finish drawing on both pages
await p1.waitForTimeout( 2000 );
await p2.waitForTimeout( 2000 );

const [s1, s2] = await Promise.all( [
  p1.screenshot( { fullPage:true } ),
  p2.screenshot( { fullPage:true } )
] );

// write screenshots + diff
fs.writeFileSync( "legacy.png", s1 );
fs.writeFileSync( "next.png", s2 );

const img1 = PNG.sync.read( s1 ), img2 = PNG.sync.read( s2 );
const width = Math.min( img1.width, img2.width );
const height = Math.min( img1.height, img2.height );

function crop( img ) {
  const out = new PNG( { width, height } );
  PNG.bitblt( img, out, 0, 0, width, height, 0, 0 );
  return out;
}

const c1 = crop( img1 ), c2 = crop( img2 );
const diff = new PNG( { width, height } );
const mismatch = pixelmatch( c1.data, c2.data, diff.data, width, height, { threshold: 0.1 } );
fs.writeFileSync( "diff.png", PNG.sync.write( diff ) );
console.log( `Mismatch: ${(mismatch/(width*height)*100).toFixed( 2 )}%` );
await b.close();

npm install --save-dev playwright pngjs pixelmatch 
npx playwright install chromium 

node compare.mjs

Mismatch: 1.22%