# Frontend (Nuxt)

## Pages

| Route | File | Behavior |
|---|---|---|
| `/` | `app/pages/index.vue` | Static hero/intro copy plus the single latest article, fetched via `/api/articles` (page 1), shown as a featured block. |
| `/blog` | `app/pages/blog/index.vue` | Paginated archive (`PAGE_SIZE = 12`), grid of `ArticleCard`, prev/next via `?page=`. |
| `/blog/[slug]` | `app/pages/blog/[slug].vue` | Full article: fetches `/api/articles/:slug`, renders the pre-converted `article.html`, SEO meta, canonical URL, Open Graph, JSON-LD `BlogPosting`, breadcrumb to its category. |
| `/category/[slug]` | `app/pages/category/[slug].vue` | Fetches the category by slug, then a paginated, category-filtered article list; 404s if the category doesn't exist. |
| `/come-difendersi-dal-corralito` | `app/pages/come-difendersi-dal-corralito.vue` | Fully static marketing page, no Strapi data. |

All pages are SSR (`useFetch`/`useSeoMeta`); nothing blog-related is client-only-rendered.

## Server (Nitro) endpoints — the only Strapi client

`frontend/server/api/`:

| Endpoint | Purpose |
|---|---|
| `GET /api/articles` | Paginated list (`page` query, `PAGE_SIZE=12`), optional `category` slug filter. Proxies to Strapi with `ARTICLE_SUMMARY_QUERY`. Returns `Paginated<ArticleSummary>`. |
| `GET /api/articles/:slug` | One article: fetches from Strapi with `ARTICLE_DETAIL_QUERY` (includes `content` + `createdBy`), converts Markdown to HTML, builds the meta description, derives the author byline. 400 without a slug, 404 if not found. Returns `Article`. |
| `GET /api/categories` | All categories (name + slug only), sorted by name. |
| `GET /api/categories/:slug` | One category by slug. 400/404 as above. |

This is the **single point of contact** with Strapi (`CLAUDE.md` rule): pages never call
`$fetch` against Strapi directly, and `NUXT_STRAPI_URL` / any Strapi token never reach the client.
If you add a view that needs new data, add the endpoint here and type its return in
`frontend/shared/types/blog.ts` — don't scatter Strapi calls into components.

## Supporting utilities

- `frontend/server/utils/strapi.ts`
  - `strapiFetch<T>(path)` — server-only fetch against `runtimeConfig.strapiUrl`, with optional
    Bearer token; wraps failures as a 502 so internal details never leak to the client.
  - `renderMarkdown(source)` — `marked.parse()`, no sanitization (trusted, admin-only content).
  - `summarise(source, maxLength = 155)` — strips Markdown syntax to build a plain-text meta
    description, word-boundary clipped.
- `frontend/server/utils/queries.ts` — Strapi query-string builders kept intentionally minimal
  (only the fields each page actually renders): `ARTICLE_SUMMARY_QUERY`, `ARTICLE_DETAIL_QUERY`,
  `PAGE_SIZE`, `pagination()`, `pageParam()`.
- `frontend/app/composables/useMediaUrl.ts` — the only composable; turns a Strapi image object
  into an absolute browser URL by prefixing `runtimeConfig.public.strapiUrl` unless already
  absolute.
- `frontend/shared/utils/site.ts` — site constants (`SITE_NAME`, `SITE_EMAIL`, `SOCIAL_LINKS`).
- `frontend/shared/utils/format.ts` — `it-IT` date formatting (`formatDate`, `formatDateTime`,
  `isoDate`).

## Types (`frontend/shared/types/blog.ts`)

```
StrapiImage   { url, alternativeText, width, height }
Category      { name, slug }
ArticleSummary{ title, slug, publishedAt, cover: StrapiImage | null, category: Category | null }
Article       extends ArticleSummary { html, summary, author: string | null }
Paginated<T>  { items: T[], page, pageCount, total }
```

`Article` is the detail shape (adds rendered HTML, meta summary, byline); `ArticleSummary` is what
listing pages use.

## Layout & shared components

- `app/layouts/default.vue` — the only layout: header (logo, tagline, nav), `<main id="main">`
  slot, footer (contact email, nav, social links), with a skip-link for accessibility.
- `app/components/ArticleCard.vue` — listing-grid card: cover (lazy, omitted if none), category
  kicker, title link, formatted date.
- `app/components/SocialIcon.vue` — inlines SVG brand marks from `simple-icons` at build time
  (`?raw` imports) rather than bundling the whole icon set.

## SEO & accessibility

Every article page ships: unique `<title>`, meta description, canonical URL, Open Graph tags, and
JSON-LD `BlogPosting` structured data, with the article body already present in server-rendered
HTML (no client-only content). Accessibility requirements (focus visibility, labeled inputs,
meaningful alt text, descriptive links, full keyboard navigation) apply across all pages/components
— see `CLAUDE.md`.