tibi-svelte-starter/.agents/skills/website-solution-architecture/SKILL.md

---
name: website-solution-architecture
description: Translate website requirements into a complete tibi-svelte-starter solution. Covers solution decomposition across collections, pagebuilder, navigation, SSR, actions, permissions, media, admin UX, and validation.
---

# website-solution-architecture

## When to use this skill

Use this skill when:

- The user wants a complete website built on this starter
- Requirements exist, but the data model and project structure do not yet
- A feature request spans frontend, admin, hooks, SSR, and content modeling together
- An LLM needs to decide what belongs in collections, blocks, actions, settings, or frontend code

## Goal

The goal is to teach an LLM how to convert requirements into a coherent website solution on this stack.

That means choosing the right shape for:

- content model
- admin authoring UX
- frontend rendering
- SSR behavior
- actions and workflows
- media handling
- permissions
- verification

This skill is about architecture decisions, not isolated file edits.

## Core principle

Do not start by adding components. Start by modeling the system.

On this starter, a complete website usually spans these layers:

1. collections and actions in `api/`
2. shared types in `types/`
3. app shell, routing, and rendering in `frontend/src/`
4. SSR validation and caching in `api/hooks/`
5. admin ergonomics in collection meta/field config
6. tests or direct validation steps

If the work starts at the UI layer without a content/admin model, the solution usually drifts.

## Canonical architecture areas

### 1. Content model

Decide early which collections exist and why.

Typical website collections:

- `content` for pages
- `navigation` for header/footer/site menus
- `medialib` for media assets
- site settings or global content singleton
- optional domain collections such as team, jobs, events, products, references

Do not create collections just because the frontend has a section. Create them when the data needs its own lifecycle, relations, searchability, or editorial ownership.

### 2. Pagebuilder model

Decide whether pages are best modeled as:

- page entries with `blocks[]`
- references to reusable sections
- a mix of page-local blocks and reusable records

Use pagebuilder structures when editors need flexible composition. Use separate collections when content is reused across multiple pages or needs its own workflows.

### 3. Navigation model

Navigation is not an afterthought. It is often page-critical runtime and SSR data.

Design:

- header navigation
- footer navigation
- utility navigation if needed
- relation to localized paths

If navigation is part of the shell, it must be loaded and rendered coherently in browser and SSR.

### 4. Route model

This starter uses content-driven routing, not file-based routing.

Architectural decisions must account for:

- language-prefixed public URLs
- DB paths stored without language prefix
- route translations
- canonical paths and alias paths
- SSR route validation in `api/hooks/config.js`

If the route model is unclear, the frontend and SSR will diverge.

### 5. Admin authoring model

Every serious website on this stack needs an editor-friendly Nova model.

Use:

- `preview`
- `sidebar`
- `containerProps.layout`
- `dependsOn`
- `drillDown`
- `pagebuilder`
- `subNavigation`
- `singleton`
- foreign previews

**I18n field config:** When modeling multilingual content, decide early whether to use:
- **Field-level i18n** — object fields whose subField names match language codes (`de`, `en`, etc.) are auto-detected and rendered with language tabs in Nova. Configured via `api.meta.i18n` in `config.yml` or per-collection `meta.i18n`.
- **Entry-level i18n** — each entry represents one language, linked by a shared `translationGroup` UUID. The `I18nEntryConfig` type (from `tibi-admin-nova/types/admin.d.ts`) defines `languageField`, `groupField`, and `copyFields`/`clearFields` for translation cloning behavior.

See `tibi-admin-nova/types/admin.d.ts` interfaces `I18nFieldConfig` and `I18nEntryConfig` for the full API.

Do not treat admin config as optional polish. It is part of the solution architecture.

### 6. Actions and workflows

Decide whether non-page features belong in collections, actions, or both.

Typical action-based website workflows:

- contact form
- newsletter signup
- booking or quote request
- webhook receiver
- AI helper endpoint

Do not force endpoint logic into fake CRUD collections.

### 7. SSR and caching

If the project uses SSR, the architecture must define:

- which routes are SSR-valid
- which collections influence rendered HTML
- how invalidation happens
- which page-critical data must be loaded during SSR

On this starter, SSR is architecture, not a plugin. It must be considered while modeling routing, navigation, page content, and mutation hooks.

### 8. Media and SEO

Most website projects need explicit decisions for:

- media library usage
- image fields and filters
- alt texts and captions
- SEO metadata per page
- social/share metadata where required
- publication windows

These decisions often belong partly in content collections and partly in admin ergonomics.

### 9. Permissions and editorial safety

Before implementing, decide:

- who may edit which collection
- which fields are readonly or hidden
- which collections are public or internal
- whether actions are public, authenticated, or internal only

Permissions are part of the architecture, not only a final hardening step.

## Recommended planning flow

### Step 1: Extract the website capabilities

Turn the brief into concrete capability buckets:

- page types
- reusable sections
- navigation
- forms/workflows
- media/SEO
- localization
- editor roles
- SSR/publication needs

### Step 2: Map capabilities to runtime surfaces

For each capability, decide whether it belongs in:

- collection schema
- action endpoint
- pagebuilder block
- site settings singleton
- frontend-only presentation
- hook-based server logic

### Step 3: Shape the editor workflows

Before building components, decide how editors will:

- create pages
- compose blocks
- edit navigation
- manage reusable entities
- preview references
- find the right entries in Nova

If this step is skipped, the content model often becomes technically correct but operationally poor.

### Step 4: Define the frontend boundaries

Clarify:

- app shell responsibilities
- which parts are pure presentation blocks
- where data loading lives
- how route parameters map to content queries
- which features must be SSR-safe

### Step 5: Define server responsibilities

Clarify:

- route validation
- public read filtering
- cache invalidation
- action validation and side effects
- publication behavior

### Step 6: Define verification before implementation expands

At minimum, define how to verify:

- pages load in the browser
- pages render in SSR when applicable
- admin authoring is usable
- actions/forms behave correctly
- build and validate stay clean

## Typical solution patterns

### Marketing website

Typical shape:

- `content` collection with pagebuilder blocks
- `navigation` collection
- global site settings singleton
- SSR enabled for public pages
- one or more public actions for forms

### Content-heavy editorial website

Typical shape:

- `content` plus additional domain collections
- stronger use of relations and reusable entities
- richer preview/search ergonomics in Nova
- publication-aware SSR invalidation

### Product or service website with lead generation

Typical shape:

- structured domain collections for offers/services
- pagebuilder pages for marketing presentation
- public actions for inquiry flows
- staff-facing inquiry persistence when follow-up is needed

## Anti-patterns

- Starting from Svelte components before defining collections and flows
- Treating admin ergonomics as a later cleanup step
- Mixing page data, workflow data, and settings without clear boundaries
- Creating one-off block types for every page variation
- Using collections where actions are the better model
- Forgetting SSR implications while changing route or content shape
- Leaving types, renderer, and collection schema out of sync

## Architecture checklist

Before calling a website solution on this starter coherent, verify that all of these are answered:

1. Which collections exist and why?
2. Which content is page-local versus reusable?
3. How are routes, language prefixes, and canonical paths modeled?
4. Which authoring workflows exist in Nova?
5. Which non-CRUD workflows require actions?
6. Which data is page-critical for SSR?
7. Which permissions protect content and workflows?
8. How will success be validated technically and functionally?

## What an LLM should inspect first

When asked to build a complete website on this starter, inspect in this order:

1. `api/collections/content.yml`
2. `api/collections/navigation.yml`
3. `frontend/src/App.svelte`
4. `frontend/src/blocks/BlockRenderer.svelte`
5. `types/global.d.ts`
6. `api/hooks/config.js`
7. existing actions/hooks if the project already has workflows

This order exposes the actual project architecture before the LLM starts generating new code.