✨ feat: enhance medialib image handling and add asset URL resolution
- Implemented `resolveApiAssetUrl` function to normalize asset URLs based on API base. - Updated `MedialibImage` component to utilize new asset URL resolution and added support for alt text and class properties. - Enhanced image loading behavior with improved width measurement and focal point handling. - Added placeholder image handling and improved accessibility with alt text. - Introduced new test script for auditing broken links in skill documentation. - Expanded seeded test content to include medialib entries and updated related tests for pagebuilder previews. - Improved global setup and teardown logging for clarity on seeded content management.
This commit is contained in:
@@ -0,0 +1,170 @@
|
||||
---
|
||||
name: mongodb-and-indexes
|
||||
description: Design MongoDB prerequisites and index strategy for tibi website projects. Covers replica-set requirements, collection index modeling, text/search index implications, index auto-management on reload, and operator checks for persistence, backups, and regeneration-sensitive features.
|
||||
---
|
||||
|
||||
# mongodb-and-indexes
|
||||
|
||||
## When to use this skill
|
||||
|
||||
Use this skill when:
|
||||
|
||||
- a project moves beyond simple demo data and needs deliberate MongoDB design
|
||||
- collections need unique, text, sparse, or compound indexes
|
||||
- search, audit, or larger datasets introduce operational database requirements
|
||||
- operators need clarity about replica-set, persistence, or backup assumptions
|
||||
|
||||
## Goal
|
||||
|
||||
Give later agents one place for MongoDB prerequisites and index strategy.
|
||||
|
||||
This skill exists because tibi projects do not just “use MongoDB”. They rely on config-driven indexes, reload-time index reconciliation, and environment choices that can help or break production behavior.
|
||||
|
||||
## Source of truth
|
||||
|
||||
Use these sources when implementing or reviewing MongoDB/index decisions:
|
||||
|
||||
- `tibi-server/docs/02-configuration.md`
|
||||
- `tibi-server/docs/04-collections.md`
|
||||
- `tibi-server/docs/12-deployment.md`
|
||||
- active project/server config
|
||||
|
||||
## MongoDB prerequisites
|
||||
|
||||
Current upstream deployment requirements include:
|
||||
|
||||
- MongoDB 4.4+
|
||||
- replica set for transactions
|
||||
|
||||
That means later agents should not promise production-like behavior while ignoring the actual database topology.
|
||||
|
||||
For this starter family, check explicitly:
|
||||
|
||||
- which MongoDB version is targeted
|
||||
- whether the environment runs as a replica set
|
||||
- where persistent data lives
|
||||
- how backup and restore are expected to work
|
||||
|
||||
## Index ownership model
|
||||
|
||||
Indexes can be defined in two places.
|
||||
|
||||
### Field-level indexes
|
||||
|
||||
Use for simple per-field indexes:
|
||||
|
||||
```yaml
|
||||
fields:
|
||||
- name: email
|
||||
type: string
|
||||
index:
|
||||
- single
|
||||
- unique
|
||||
```
|
||||
|
||||
Available field-level flags include:
|
||||
|
||||
- `single`
|
||||
- `unique`
|
||||
- `text`
|
||||
- `sparse`
|
||||
|
||||
### Collection-level indexes
|
||||
|
||||
Use for compound or more explicit index definitions:
|
||||
|
||||
```yaml
|
||||
indexes:
|
||||
- name: category_publish_date
|
||||
key:
|
||||
- category
|
||||
- -publishDate
|
||||
background: true
|
||||
- name: title_text
|
||||
key:
|
||||
- $text:title
|
||||
defaultLanguage: german
|
||||
```
|
||||
|
||||
Use collection-level indexes when:
|
||||
|
||||
- sort patterns span multiple fields
|
||||
- uniqueness depends on more than one field
|
||||
- you need text-index language control
|
||||
- the index needs a stable explicit name
|
||||
|
||||
## Important auto-management behavior
|
||||
|
||||
On project setup or reload:
|
||||
|
||||
1. configured indexes are created
|
||||
2. indexes present in MongoDB but no longer in config are dropped
|
||||
3. `_id_` is never dropped
|
||||
|
||||
This is a critical workflow fact.
|
||||
|
||||
Do not treat indexes as one-off manual DBA work while also expecting config reload to stay authoritative. In this stack, the YAML config owns the intended index state.
|
||||
|
||||
## Search and index interplay
|
||||
|
||||
Some search modes depend directly on index strategy:
|
||||
|
||||
- `mode: text` requires a text index
|
||||
- explicit text search can use field-level `index: [text]` or collection-level `$text:` indexes
|
||||
- regex fallback can become expensive without deliberate field/index choices
|
||||
- enrichment-based modes such as `ngram` and `vector` add `_search` data and may require regeneration workflows rather than classic MongoDB indexes alone
|
||||
|
||||
Keep classic indexes and search config aligned. Search should not be modeled in isolation from database cost and reload behavior.
|
||||
|
||||
## Query shape matters
|
||||
|
||||
Before adding indexes, inspect the real access patterns:
|
||||
|
||||
- which fields appear in permission filters
|
||||
- which fields appear in list sorting
|
||||
- which fields appear in frequent admin or public lookups
|
||||
- whether uniqueness is a real business rule or only a nice-to-have
|
||||
|
||||
Index design should follow concrete read and write patterns, not schema aesthetics.
|
||||
|
||||
## Operational decisions
|
||||
|
||||
At project-delivery level, document these choices explicitly:
|
||||
|
||||
- MongoDB version and topology
|
||||
- replica-set availability
|
||||
- persistence location for database and uploads
|
||||
- backup/restore responsibility
|
||||
- whether audit/search features introduce extra operational expectations
|
||||
|
||||
If these decisions are absent, later agents tend to over-focus on schema YAML while missing the operator-critical data layer.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- adding indexes without checking actual query or sort behavior
|
||||
- relying on manual indexes that the config will later drop
|
||||
- enabling text search without provisioning the needed text index
|
||||
- treating replica-set requirements as optional trivia
|
||||
- shipping production projects without a backup and restore story
|
||||
|
||||
## Verification checklist
|
||||
|
||||
After MongoDB/index-related changes, verify all of these:
|
||||
|
||||
1. the target environment satisfies MongoDB version and replica-set needs
|
||||
2. configured indexes match real query, sort, and uniqueness requirements
|
||||
3. project reload succeeds after index changes
|
||||
4. text/search features have the required index support
|
||||
5. persistence and backup assumptions are documented
|
||||
|
||||
## What an LLM should inspect first
|
||||
|
||||
When asked to design or review the data layer on this starter, inspect in this order:
|
||||
|
||||
1. `tibi-server/docs/12-deployment.md`
|
||||
2. `tibi-server/docs/02-configuration.md`
|
||||
3. `tibi-server/docs/04-collections.md`
|
||||
4. current collection YAML for indexes/search
|
||||
5. actual query, sort, audit, and search requirements
|
||||
|
||||
This keeps index design tied to real runtime behavior and not just to field definitions.
|
||||
Reference in New Issue
Block a user