✨ feat: enhance project setup and architecture documentation
- Updated `tibi-project-setup` skill to clarify project initialization goals and steps. - Improved `tibi-ssr-caching` skill to detail SSR architecture, responsibilities, and caching mechanisms. - Introduced `website-solution-architecture` skill for translating website requirements into coherent solutions. - Refined `AGENTS.md` to provide a structured roadmap for project development phases. - Added `ADMIN_ASSET_VERSION` to `api/config.yml.env` for asset versioning. - Updated SSR request flow and cache invalidation logic in `api/hooks/ssr/AGENTS.md`. - Removed obsolete `esbuild.config.admin.js` and integrated asset versioning into the main `esbuild.config.js`. - Adjusted `api/collections/content.yml` to utilize asset versioning for admin scripts.
This commit is contained in:
@@ -0,0 +1,303 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user