Skip to content

index.mdx

Latest commit

 

History

History
160 lines (133 loc) · 5.81 KB

index.mdx

File metadata and controls

160 lines (133 loc) · 5.81 KB
title Backend Development
description Complete guide to developing and contributing to the DeployStack backend - a high-performance Node.js application built with Fastify, TypeScript, and extensible plugin architecture.
sidebar Getting Started

import { Card, Cards } from 'fumadocs-ui/components/card'; import { Database, Shield, Plug, Settings, Mail, TestTube, Wrench, BookOpen, Terminal } from 'lucide-react';

DeployStack Backend Development

The DeployStack backend is a modern, high-performance Node.js application built with Fastify, TypeScript, and Drizzle ORM. It's specifically designed for managing MCP (Model Context Protocol) server configurations with enterprise-grade features including authentication, role-based access control, and an extensible plugin system.

Technology Stack

  • Framework: Fastify for high-performance HTTP server
  • Language: TypeScript for type safety
  • Database: SQLite (default) or PostgreSQL with Drizzle ORM
  • Validation: Zod for request/response validation and OpenAPI generation
  • Plugin System: Extensible architecture with security isolation
  • Authentication: Cookie-based sessions with role-based access control

Quick Start

cd services/backend
npm install
npm run dev

The development server starts at http://localhost:3000 with API documentation at /documentation.

Development Guides

} href="/deploystack/development/backend/api" title="API Documentation" > Learn how to generate OpenAPI specifications, use Swagger UI, and implement Zod validation for automatic API documentation.

<Card icon={} href="/deploystack/development/backend/database" title="Database Management"

SQLite and PostgreSQL setup, schema management, migrations, and Drizzle ORM best practices.

<Card icon={} href="/deploystack/development/backend/plugins" title="Plugin System"

Create extensible plugins with isolated routes, database extensions, and security features for custom functionality.

<Card icon={} href="/deploystack/development/backend/global-settings" title="Global Settings"

Configuration management system with encrypted storage, role-based access, and plugin extensions.

<Card icon={} href="/deploystack/development/backend/security" title="Security & Roles"

Authentication, authorization, role-based access control, and security best practices.

<Card icon={} href="/deploystack/development/backend/mail" title="Mail System"

Email service configuration, SMTP setup, template management, and transactional email sending.

<Card icon={} href="/deploystack/development/backend/test" title="Testing"

Testing strategies, examples, and best practices for backend development and API testing.

<Card icon={} href="/deploystack/development/backend/roles" title="Roles Management"

User roles, permissions system, and access control implementation details.

<Card icon={} href="/deploystack/development/backend/gateway-client-config" title="Gateway Client Configuration"

API endpoint for generating client-specific gateway configuration files with dual authentication support.

Project Structure

services/backend/
├── src/
│   ├── routes/              # API route handlers
│   ├── db/                  # Database schema and configuration
│   ├── plugin-system/       # Plugin architecture
│   ├── global-settings/     # Core settings definitions
│   ├── auth/                # Authentication utilities
│   └── server.ts            # Main server configuration
├── plugins/                 # Extensible plugin directory
├── persistent_data/         # All persistent application data (backup this entire directory)
│   ├── database/            # SQLite database files
│   │   └── deploystack.db   # Main database (if using SQLite)
│   └── db.selection.json    # Database type configuration
└── drizzle/                 # Database migrations
│   └── migrations_sqlite/   # SQL migration files

Key Features

Plugin Architecture

  • Security Isolation: Routes automatically namespaced under /api/plugin/<id>/
  • Database Extensions: Plugins can safely add their own tables
  • Global Settings: Contribute configuration options
  • Lifecycle Management: Proper initialization and cleanup

API Documentation

  • Automatic Generation: OpenAPI 3.0 specs from Zod schemas
  • Interactive Testing: Swagger UI for API exploration
  • Type Safety: Request/response validation with TypeScript

Database Management

  • Multi-Database Support: SQLite (default) and PostgreSQL
  • Type-Safe ORM: Drizzle ORM with full TypeScript integration
  • Migration System: Automatic schema management
  • Plugin Extensions: Plugins can add their own tables

Development Workflow

  1. Setup: Install dependencies and start development server
  2. Database Initialization:
    • For first-time setup: Visit /setup in the frontend
    • For development: Call POST /api/db/setup directly
    • Creates persistent_data/db.selection.json and initializes database
  3. Development: Add routes, modify schemas, create plugins
  4. Testing: Run comprehensive test suite
  5. Documentation: Generate API specs for integration
  6. Backup: Always backup entire persistent_data/ directory for data persistence

For detailed implementation guides, security considerations, and best practices, explore the specific documentation sections above.