docs(api-server): clarify database initialization and seeding process

- Rename "Data Seeding & Fixtures" to "Data Seeding & System Initialization"
- Refocus description on database preparation for running, not content population
- Update architectural goal to emphasize consistency and predictability
- Detail specific initialization tasks: database indexes and admin user setup
- Adjust explanation to match idempotent initialization rather than seeding
- Highlight reliability, security, and maintainability benefits

Author: fulleni

src/content/docs/api-server/architecture/data-seeding-and-fixtures.mdx

@@ -1,34 +1,34 @@
 ---
-title: Data Seeding & Fixtures
-description: Learn about the architectural decision behind the API server's automatic database seeding process.
+title: Data Seeding & System Initialization
+description: Learn about the API server's automatic database initialization and seeding process.
 ---
 
 import { Aside } from '@astrojs/starlight/components';
 
-A key architectural feature of the API server is its automatic and idempotent database seeding process. This ensures that a developer can get a fully functional environment running with a consistent set of baseline data, simply by starting the server.
+A key architectural feature of the API server is its automatic and idempotent database initialization process. This ensures that on first startup, the server correctly prepares the database with the essential indexes and configurations needed to run.
 
-### The Architectural Goal
+### The Architectural Goal: A Clean, Predictable Start
 
-The primary goal of this system is to **guarantee a consistent and predictable state** for development and testing environments. Without it, developers would need to manually populate the database, leading to inconsistencies and a slower setup process.
+The primary goal of this system is to **guarantee a consistent and predictable state** for the database, especially for new development and production environments.
 
-This is achieved through two core components:
+This process is designed to be **lean and focused on system setup, not content population**. It handles two critical, one-time tasks:
 
-1.  **Shared Fixtures:** A centralized set of predefined data is located in the `core` package. This data includes essential items like countries, news topics, sources, and default user accounts. Placing it in `core` makes this baseline data accessible to the entire ecosystem, ensuring all components (API, mobile client, tests) can be built against the same foundational dataset.
+1.  **Ensuring Database Indexes:** It creates all necessary MongoDB indexes, including TTL (Time-To-Live) indexes for temporary data like verification codes and text indexes for search functionality.
+2.  **Initializing the Admin User:** It securely sets up the single administrator account based on the `OVERRIDE_ADMIN_EMAIL` environment variable.
 
-2.  **Idempotent Seeding Service:** The `DatabaseSeedingService` on the API server is designed to be **idempotent**.
+### Idempotent and Safe to Run
+
+The initialization service is **idempotent**.
 
 <Aside type="tip" title="What is Idempotency?">
-An idempotent operation is one that can be applied multiple times without changing the result beyond the initial application. In this context, it means you can restart the server as many times as you want, and the database will always end up in the same correct state, without creating duplicate entries.
+An idempotent operation is one that can be applied multiple times without changing the result beyond the initial application. In this context, it means you can restart the server as many times as you want, and the database indexes and admin user will always end up in the same correct state, without errors or duplicate entries.
 </Aside>
 
-### Implementation Details
-
-The service achieves idempotency by using MongoDB's `upsert` functionality. For each item in the fixture data, it attempts to find a document with a matching, deterministic `_id`.
-
--   If the document exists, it is **updated** with the values from the fixture.
--   If it does not exist, it is **inserted**.
+This is achieved by:
+-   Using MongoDB's `createIndex` commands, which only create indexes if they don't already exist.
+-   Intelligently checking for the admin user's existence before attempting to create it.
 
 This architectural choice provides significant benefits:
--   **Reliability:** Eliminates "it works on my machine" problems caused by database inconsistencies.
--   **Efficiency:** Drastically speeds up the onboarding process for new developers.
--   **Maintainability:** Fixture data is managed in one central, version-controlled location.
+-   **Reliability:** Ensures the database is always correctly configured for the application to run.
+-   **Security:** Centralizes and secures the process of setting up the initial administrator.
+-   **Maintainability:** Keeps the server's core setup logic separate from dynamic application content.