feat: Add comprehensive documentation for UI Design System, GitHub Integration, MCP Catalog, and user roles

- Introduced a new UI Design System guide detailing design principles, component patterns, and accessibility guidelines.
- Created a GitHub Application Integration document explaining the process of integrating GitHub with DeployStack for MCP server creation.
- Added a GitHub Integration guide outlining synchronization, OAuth configuration, and repository management features.
- Developed an MCP Server Catalog documentation to facilitate server discovery, management, and deployment processes.
- Updated roles documentation to include specific permissions related to the MCP Catalog and server management capabilities.
- Enhanced team documentation to clarify MCP server settings and GitHub integration for team-specific deployments.

Author: Lasim

docs/deploystack/development/backend/api-pagination.mdx

@@ -15,6 +15,17 @@ The DeployStack Backend uses Fastify with Swagger plugins to automatically gener
 - **Postman Integration**: JSON/YAML specs that can be imported into Postman
 - **Automated Generation**: Specifications are generated from actual route code
 
+## 🔒 Security First
+
+**IMPORTANT**: Before developing any protected API endpoints, read the [API Security Best Practices](./api-security.mdx) documentation. It covers critical security patterns including:
+
+- **Authorization Before Validation**: Why `preValidation` must be used instead of `preHandler` for authorization
+- **Proper Error Responses**: Ensuring unauthorized users get 403 Forbidden, not validation errors
+- **Security Testing**: How to test authorization properly
+- **Common Pitfalls**: Security anti-patterns to avoid
+
+**Key Rule**: Always use `preValidation` for authorization checks to prevent information disclosure to unauthorized users.
+
 ## Available Commands
 
 ### 1. Generate Complete API Specification
@@ -99,6 +110,8 @@ When the server is running (`npm run dev`), you can access:
 2. **Directory Organization**: Group related routes in directories (e.g., `/auth/`, `/users/`, `/health/`)
 3. **Import Pattern**: Routes are imported and registered in `src/routes/index.ts`
 4. **Consistent Naming**: Use descriptive names that match the route purpose
+5. **Modular Approach**: **Keep route files small and focused** - aim for 1-3 related methods per file maximum
+6. **Maintainability**: Avoid large monolithic route files that become difficult to maintain
 
 ### Correct File Structure
 
@@ -120,6 +133,37 @@ services/backend/src/routes/
     └── index.ts          # Team management endpoints
 ```
 
+### Modular Route Organization (Recommended)
+
+For complex feature areas, break down routes into smaller, focused files:
+
+```
+services/backend/src/routes/mcp/
+├── index.ts              # Route registration only
+├── categories/
+│   ├── create.ts        # POST /api/mcp/categories (1 method)
+│   ├── update.ts        # PUT /api/mcp/categories/{id} (1 method)
+│   └── delete.ts        # DELETE /api/mcp/categories/{id} (1 method)
+├── servers/
+│   ├── list.ts          # GET /api/mcp/servers (1 method)
+│   ├── get.ts           # GET /api/mcp/servers/{id} (1 method)
+│   ├── search.ts        # GET /api/mcp/servers/search (1 method)
+│   ├── create-global.ts # POST /api/mcp/servers/global (1 method)
+│   ├── update-global.ts # PUT /api/mcp/servers/global/{id} (1 method)
+│   └── delete-global.ts # DELETE /api/mcp/servers/global/{id} (1 method)
+└── versions/
+    ├── list.ts          # GET /api/mcp/servers/{id}/versions (1 method)
+    ├── create.ts        # POST /api/mcp/servers/{id}/versions (1 method)
+    └── update.ts        # PUT /api/mcp/servers/{id}/versions/{versionId} (1 method)
+```
+
+**Benefits of Modular Approach:**
+- **Easier Maintenance**: Small files are easier to understand and modify
+- **Better Testing**: Individual route files can be tested in isolation
+- **Team Collaboration**: Multiple developers can work on different routes without conflicts
+- **Clear Responsibility**: Each file has a single, clear purpose
+- **Reduced Complexity**: Avoid hundreds of lines in single files
+
 ### Route File Template
 
 Each route file should follow this pattern:
@@ -210,6 +254,71 @@ export const registerRoutes = (server: FastifyInstance): void => {
 4. **Code Organization**: Related functionality is grouped together
 5. **Team Collaboration**: Multiple developers can work on different routes without conflicts
 
+## Content-Type Header Requirements
+
+### When to Include Content-Type Headers
+
+**IMPORTANT**: The `Content-Type: application/json` header is required for specific HTTP methods when sending request body data.
+
+#### ✅ ALWAYS Include Content-Type for:
+- **POST** requests with request body data
+- **PUT** requests with request body data  
+- **PATCH** requests with request body data
+
+#### ❌ NEVER Include Content-Type for:
+- **GET** requests (no request body)
+- **DELETE** requests (typically no request body)
+- **HEAD** requests (no request body)
+
+#### Correct Client Implementation Pattern
+
+```javascript
+function makeRequest(method, path, data = null, cookies = null) {
+  const options = {
+    method,
+    headers: { 'Accept': 'application/json' }
+  };
+
+  // Set Content-Type for methods that send request body data
+  if (['POST', 'PUT', 'PATCH'].includes(method.toUpperCase()) && data !== null) {
+    options.headers['Content-Type'] = 'application/json';
+  }
+
+  // Rest of implementation...
+}
+```
+
+#### ❌ Problematic Pattern (Avoid This)
+
+```javascript
+// UNCLEAR: This doesn't indicate WHICH methods need Content-Type
+if (data) {
+  options.headers['Content-Type'] = 'application/json';
+}
+```
+
+### API Specification Content-Type Documentation
+
+When defining route schemas, explicitly document Content-Type requirements for POST/PUT/PATCH endpoints:
+
+```typescript
+// For endpoints that require Content-Type
+const routeSchema = {
+  tags: ['Category'],
+  summary: 'Create new item',
+  description: 'Creates a new item. Requires Content-Type: application/json header when sending request body.',
+  requestBody: {
+    required: true,
+    content: {
+      'application/json': {
+        schema: zodToJsonSchema(requestSchema, { $refStrategy: 'none', target: 'openApi3' })
+      }
+    }
+  },
+  // ... rest of schema
+};
+```
+
 ## Adding Documentation to Routes
 
 To add OpenAPI documentation to your routes, define your request body and response schemas using Zod. Then, use the `zodToJsonSchema` utility to convert these Zod schemas into the JSON Schema format expected by Fastify.
@@ -246,12 +355,23 @@ const myErrorResponseSchema = z.object({
 const routeSchema = {
   tags: ['Category'], // Your API category
   summary: 'Brief description of your endpoint',
-  description: 'Detailed description of what this endpoint does, its parameters, and expected outcomes.',
+  description: 'Detailed description of what this endpoint does, its parameters, and expected outcomes. Requires Content-Type: application/json header when sending request body.',
   security: [{ cookieAuth: [] }], // Include if authentication is required
   body: zodToJsonSchema(myRequestBodySchema, { 
     $refStrategy: 'none', // Keeps definitions inline, often simpler for Fastify
     target: 'openApi3'   // Ensures compatibility with OpenAPI 3.0
   }),
+  requestBody: {
+    required: true,
+    content: {
+      'application/json': {
+        schema: zodToJsonSchema(myRequestBodySchema, { 
+          $refStrategy: 'none', 
+          target: 'openApi3' 
+        })
+      }
+    }
+  },
   response: {
     200: zodToJsonSchema(mySuccessResponseSchema.describe("Successful operation"), { 
       $refStrategy: 'none', 
@@ -301,6 +421,15 @@ fastify.post<{ Body: RequestBody }>(
 5. **Type Safety**: Handlers receive properly typed, validated data
 6. **Cleaner Code**: No redundant validation logic in handlers
 
+### Why Both `body` and `requestBody` Properties?
+
+**Important**: You need BOTH properties for complete functionality:
+
+- **`body`**: Enables Fastify's automatic request validation using the Zod schema
+- **`requestBody`**: Ensures proper OpenAPI specification generation with Content-Type documentation
+
+Without `body`, validation won't work. Without `requestBody`, your API specification won't properly document the `application/json` Content-Type requirement.
+
 ### What NOT to Do (Anti-patterns)
 
 ❌ **Don't do manual validation in handlers:**