From 23b18c75bdb1b1c2273102f84670177c66eaac6b Mon Sep 17 00:00:00 2001
From: Tero Halla-aho <thallaa@gmail.com>
Date: Wed, 4 Feb 2026 10:17:54 +0200
Subject: [PATCH] docs: expand Next.js App Router notes

---
 PROGRESS.md            |  3 +++
 docs/architecture.html | 10 ++++++++++
 2 files changed, 13 insertions(+)

diff --git a/PROGRESS.md b/PROGRESS.md
index 70404df..243417a 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -104,3 +104,6 @@
 - Reconciled test DB migration history: aligned checksum for `20251212_agent_billing` and marked `20260310_site_settings` and `20260311_billing_preferences` as applied to stop Prisma errors and surface listings again.
 - Applied the same agent billing schema to staging/prod DB (`lomavuokraus`) and marked the migration as applied; Prisma status now clean there too.
 - Deploy script now runs a Prisma migration status preflight using DATABASE_URL from env or in-cluster secret and fails fast on drift before applying manifests.
+
+## 2026-02-04 — Documentation
+- Expanded Logical Architecture doc with a Next.js App Router walkthrough: routing layout, server/client component split, data fetching patterns, mutations, auth middleware, and asset handling.
diff --git a/docs/architecture.html b/docs/architecture.html
index ac403f4..c01fe8e 100644
--- a/docs/architecture.html
+++ b/docs/architecture.html
@@ -92,6 +92,16 @@ flowchart LR
           <li><strong>Mail</strong>: SMTP (smtp.lomavuokraus.fi CNAME to smtp.sohva.org) + DKIM signing for verification emails.</li>
           <li><strong>Auth</strong>: Email/password, verified+approved requirement, JWT session cookie (<code>session_token</code>), roles.</li>
         </ul>
+
+        <h3>How the Next.js App Router is wired here</h3>
+        <ul>
+          <li><strong>Rendering model</strong>: Server Components by default for pages under <code>app/</code>; Client Components opt in with <code>"use client"</code> (forms, maps, language toggle). This keeps most data fetching server-side and ships minimal JS.</li>
+          <li><strong>Routes</strong>: File-system routing in <code>app/</code>; notable paths: <code>app/page.tsx</code> (home), <code>app/browse/page.tsx</code> (search + map), <code>app/listings/[slug]/page.tsx</code> (detail), and admin routes under <code>app/admin</code>. API handlers live in <code>app/api/*/route.ts</code> (REST-like endpoints used by forms and fetch calls).</li>
+          <li><strong>Data fetching</strong>: Server Components call Prisma directly; where client state is needed, pages expose lightweight fetchers that hit the API routes. Revalidation uses <code>fetch(..., { cache: 'no-store' })</code> for sensitive pages (profile/admin) and ISR for mostly-read content (listing details + home feed).</li>
+          <li><strong>Mutations</strong>: Forms post to API route handlers (e.g., auth, listing create/edit, approvals). Responses trigger router refresh on the client via <code>useRouter().refresh()</code> so the server-rendered data is re-fetched without a full page reload.</li>
+          <li><strong>Auth enforcement</strong>: <code>middleware.ts</code> checks the session cookie early and guards admin/listing edit areas; protected pages also re-validate the session on the server before rendering. The same session util is shared by API handlers to avoid drift.</li>
+          <li><strong>Assets & images</strong>: Static assets are served from <code>/public</code> and cached by Varnish and Next.js. Listing images are streamed through <code>/api/images/:id</code>; the handler sets cache headers while respecting auth where required.</li>
+        </ul>
       </section>
     </main>
     <script type="module">