docs: rename API server guide pages and update links

- Rename 'how-to' to 'guides' in URLs for better categorization
- Update all internal links to reflect the new URL structure
- Rename 'api-reference' to 'reference' for shorter, more concise URLs
- Update navigation menu and card grid links to match new structure

Author: fulleni

astro.config.mjs

@@ -50,11 +50,11 @@ export default defineConfig({
 							label: 'Guides',
 							collapsed: true,
 							items: [
-								{ label: 'Overview', link: '/api-server/how-to/' },
-								{ label: 'Configure Environment Variables', link: '/api-server/how-to/configure-environment-variables' },
-								{ label: 'Configure MongoDB', link: '/api-server/how-to/configure-mongodb' },
-								{ label: 'Configure CORS', link: '/api-server/how-to/configure-cors' },
-								{ label: 'Implement an Alternative Email Client', link: '/api-server/how-to/implement-alternative-email-client' },
+								{ label: 'Overview', link: '/api-server/guides/' },
+								{ label: 'Configure Environment Variables', link: '/api-server/guides/configure-environment-variables' },
+								{ label: 'Configure MongoDB', link: '/api-server/guides/configure-mongodb' },
+								{ label: 'Configure CORS', link: '/api-server/guides/configure-cors' },
+								{ label: 'Implement an Alternative Email Client', link: '/api-server/guides/implement-alternative-email-client' },
 							],
 						},
 						{

src/content/docs/api-server/deployment.mdx

@@ -16,7 +16,7 @@ The world of cloud hosting and deployment tools evolves rapidly. Instead of prov
 
     Your first step is to prepare the production configuration for the server. Unlike local development which uses a `.env` file, in production you will use your hosting provider's interface to set environment variables securely.
 
-    For a detailed explanation of each required variable, please see the [Configure Environment Variables](/docs/api-server/how-to/configure-environment-variables) guide.
+    For a detailed explanation of each required variable, please see the [Configure Environment Variables](/docs/api-server/guides/configure-environment-variables) guide.
 
 2.  **Choose a Deployment Strategy**
 
@@ -39,6 +39,6 @@ The world of cloud hosting and deployment tools evolves rapidly. Instead of prov
 
     For your web-based dashboard to communicate with the API in production, you must correctly configure Cross-Origin Resource Sharing (CORS).
 
-    For instructions, see the [Configure CORS](/docs/api-server/how-to/configure-cors) guide.
+    For instructions, see the [Configure CORS](/docs/api-server/guides/configure-cors) guide.
 
 </Steps>

src/content/docs/api-server/features/email-service.mdx

@@ -26,5 +26,5 @@ When a user requests a sign-in code, the `AuthService` calls the `EmailRepositor
 <Aside type="tip" title="Architectural Benefit">
 This decoupled design makes the system highly maintainable and flexible. If you ever want to switch from SendGrid to another email provider (like Mailgun or AWS SES), you only need to create a new class that implements the `EmailClient` interface and update a single line in the dependency injection configuration.
 
-For a practical example, see the [Implement an Alternative Email Client](/docs/api-server/how-to/implement-alternative-email-client) guide.
+For a practical example, see the [Implement an Alternative Email Client](/docs/api-server/guides/implement-alternative-email-client) guide.
 </Aside>

src/content/docs/api-server/guides/configure-environment-variables.mdx

@@ -32,7 +32,7 @@ The full connection string for your MongoDB instance. The application cannot sta
 -   **Production:** Use the connection string provided by your database hosting service (e.g., MongoDB Atlas).
 
 <Aside type="tip">
-For guidance on setting up a local MongoDB instance, see the [Configure MongoDB](/docs/api-server/how-to/configure-mongodb) guide.
+For guidance on setting up a local MongoDB instance, see the [Configure MongoDB](/docs/api-server/guides/configure-mongodb) guide.
 </Aside>
 
 #### `JWT_SECRET_KEY`
@@ -80,7 +80,7 @@ The specific origin URL of your web client (e.g., the Flutter Web Dashboard) tha
 -   **Example:** `https://dashboard.yourdomain.com`
 
 <Aside type="caution">
-For more details on CORS, see the [Configure CORS](/docs/api-server/how-to/configure-cors) guide.
+For more details on CORS, see the [Configure CORS](/docs/api-server/guides/configure-cors) guide.
 </Aside>
 
 #### `SENDGRID_API_URL`

src/content/docs/api-server/guides/configure-mongodb.mdx

@@ -48,5 +48,5 @@ DATABASE_URL="mongodb://localhost:27017/flutter_news_app_db"
 -   `flutter_news_app_db`: You can name your database anything you like. The server will create it automatically on first connection if it doesn't exist.
 
 <Aside type="tip">
-For a complete overview of all environment variables, see the [Configure Environment Variables](/docs/api-server/how-to/configure-environment-variables) guide.
+For a complete overview of all environment variables, see the [Configure Environment Variables](/docs/api-server/guides/configure-environment-variables) guide.
 </Aside>

src/content/docs/api-server/guides/index.mdx

@@ -10,22 +10,22 @@ This section provides practical, step-by-step guides for specific configuration
 <CardGrid>
   <Card title="Configure Environment Variables" icon="document">
     A detailed guide to setting up your `.env` file.
-    [Read more &rarr;](/docs/api-server/how-to/configure-environment-variables/)
+    [Read more &rarr;](/docs/api-server/guides/configure-environment-variables/)
   </Card>
   <Card title="Configure MongoDB" icon="database">
     Learn how to set up a local MongoDB instance using Docker.
-    [Read more &rarr;](/docs/api-server/how-to/configure-mongodb/)
+    [Read more &rarr;](/docs/api-server/guides/configure-mongodb/)
   </Card>
   <Card title="Configure CORS" icon="shield">
     Understand and configure Cross-Origin Resource Sharing for production.
-    [Read more &rarr;](/docs/api-server/how-to/configure-cors/)
+    [Read more &rarr;](/docs/api-server/guides/configure-cors/)
   </Card>
   <Card title="Implement an Alternative Email Client" icon="email">
     See how to swap out the default email service with your own implementation.
-    [Read more &rarr;](/docs/api-server/how-to/implement-alternative-email-client/)
+    [Read more &rarr;](/docs/api-server/guides/implement-alternative-email-client/)
   </Card>
   <Card title="Understand Database Seeding" icon="seed">
     Learn how the server automatically populates the database with initial data.
-    [Read more &rarr;](/docs/api-server/how-to/understand-database-seeding/)
+    [Read more &rarr;](/docs/api-server/guides/understand-database-seeding/)
   </Card>
 </CardGrid>

src/content/docs/api-server/index.mdx

@@ -24,10 +24,10 @@ It is designed to work seamlessly with the [Mobile Client](/docs/mobile-client/)
   </Card>
   <Card title="API Reference" icon="open-book">
     A complete reference for all API endpoints and data models.
-    [Read more &rarr;](/docs/api-server/api-reference/)
+    [Read more &rarr;](/docs/api-server/reference/)
   </Card>
   <Card title="How-To Guides" icon="document">
     Practical guides for specific configuration and setup tasks.
-    [Read more &rarr;](/docs/api-server/how-to/configure-environment-variables/)
+    [Read more &rarr;](/docs/api-server/guides/configure-environment-variables/)
   </Card>
 </CardGrid>

src/content/docs/api-server/local-setup.mdx

@@ -31,13 +31,13 @@ This guide will walk you through setting up the API server in a local developmen
 
     The API server requires a MongoDB database. For local development, the recommended approach is to use Docker.
 
-    For a complete walkthrough, follow the [Configure MongoDB for Local Development](/docs/api-server/how-to/configure-mongodb) guide.
+    For a complete walkthrough, follow the [Configure MongoDB for Local Development](/docs/api-server/guides/configure-mongodb) guide.
 
 4.  **Configure Environment Variables**
 
     The server uses a `.env` file to manage secrets and configuration. You will need to create this file and populate it with the correct values for your local environment.
 
-    For a detailed walkthrough, follow the [Configure Environment Variables](/docs/api-server/how-to/configure-environment-variables) guide.
+    For a detailed walkthrough, follow the [Configure Environment Variables](/docs/api-server/guides/configure-environment-variables) guide.
 
 5.  **Install Dependencies**
 
@@ -61,5 +61,5 @@ This guide will walk you through setting up the API server in a local developmen
 
     On its first startup, the server automatically connects to your MongoDB database and seeds it with initial data (countries, topics, users, etc.). This process is idempotent, meaning you can safely restart the server multiple times without creating duplicate data.
 
-    For more details on how this works, see the [Understand Database Seeding](/docs/api-server/how-to/understand-database-seeding) guide.
+    For more details on how this works, see the [Understand Database Seeding](/docs/api-server/guides/understand-database-seeding) guide.
 </Steps>

src/content/docs/api-server/reference/index.mdx

@@ -68,10 +68,10 @@ For a detailed list of possible error codes and their meanings, please see the [
 <CardGrid>
 	<Card title="Authentication" icon="lock">
 		Endpoints for user sign-up, sign-in, and session management.
-    [Read more &rarr;](/docs/api-server/api-reference/authentication/)
+    [Read more &rarr;](/docs/api-server/reference/authentication/)
 	</Card>
 	<Card title="Data Access" icon="document">
 		The generic endpoint for all CRUD operations on data models.
-    [Read more &rarr;](/docs/api-server/api-reference/data-access/)
+    [Read more &rarr;](/docs/api-server/reference/data-access/)
 	</Card>
 </CardGrid>