Skip to main content

​
DeployStack Backend Development

The DeployStack backend is a modern, high-performance Node.js application built with Fastify, TypeScript, and Drizzle ORM. It serves as the central control plane managing MCP server catalogs, team configurations, satellite orchestration, and user authentication with enterprise-grade features.

​
Technology Stack

  • Framework: Fastify for high-performance HTTP server
  • Language: TypeScript for type safety
  • Database: SQLite (default) or PostgreSQL with Drizzle ORM
  • Validation: JSON Schema for request/response validation and OpenAPI generation
  • Plugin System: Extensible architecture with security isolation
  • Authentication: Dual authentication system - cookie-based sessions for frontend and OAuth 2.1 for satellite access

​
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

API Documentation

Learn how to generate OpenAPI specifications, use Swagger UI, and implement JSON Schema validation for automatic API documentation.

Database Management

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

Plugin System

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

Global Settings

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

Security & Roles

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

Mail System

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

Testing

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

Roles Management

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

Satellite Communication

API endpoints for satellite registration, configuration management, and command orchestration with polling-based communication.

Background Job Queue

Database-backed job processing system with persistent storage, automatic retries, and rate limiting for long-running background tasks.

Satellite Events

Real-time event processing from satellites with convention-based handlers routing to business tables for operational visibility.

​
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 JSON 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.
⌘I