--- 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 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.