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

name, description

name	description
website-solution-architecture	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

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.