forked from cms/tibi-svelte-starter
apairon
4020ad62c5
- 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.
171 lines
5.3 KiB
Markdown
171 lines
5.3 KiB
Markdown
---
|
|
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.
|