> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deploystack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Backend Development

> Complete guide to developing and contributing to the DeployStack backend - a high-performance Node.js application built with Fastify, TypeScript, and extensible plugin architecture.

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**: 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

```bash theme={null}
cd services/backend
npm install

# Start PostgreSQL (requires Docker)
npm run postgres:local

# Configure environment
cp .env.example .env

# Start development server
npm run dev
```

The development server starts at `http://localhost:3000`.

<Info>
  On first run, visit `http://localhost:5173/setup` (frontend) to initialize the database and create your admin account.
</Info>

## Development Guides

<CardGroup cols={3}>
  <Card icon="book-open" href="/development/backend/api/index" title="API Documentation">
    Learn how to generate OpenAPI specifications, use Swagger UI, and implement JSON Schema validation for automatic API documentation.
  </Card>

  <Card icon="database" href="/development/backend/database/index" title="Database Management">
    PostgreSQL setup, schema management, migrations, and Drizzle ORM best practices.
  </Card>

  <Card icon="plug" href="/development/backend/plugins" title="Plugin System">
    Create extensible plugins with isolated routes, database extensions, and security features for custom functionality.
  </Card>

  <Card icon="settings" href="/development/backend/global-settings" title="Global Settings">
    Configuration management system with encrypted storage, role-based access, and plugin extensions.
  </Card>

  <Card icon="shield" href="/development/backend/security" title="Security & Roles">
    Authentication, authorization, role-based access control, and security best practices.
  </Card>

  <Card icon="mail" href="/development/backend/mail" title="Mail System">
    Email service configuration, SMTP setup, template management, and transactional email sending.
  </Card>

  <Card icon="test-tube" href="/development/backend/test" title="Testing">
    Testing strategies, examples, and best practices for backend development and API testing.
  </Card>

  <Card icon="wrench" href="/development/backend/roles" title="Roles Management">
    User roles, permissions system, and access control implementation details.
  </Card>

  <Card icon="terminal" href="/development/backend/satellite-communication" title="Satellite Communication">
    API endpoints for satellite registration, configuration management, and command orchestration with polling-based communication.
  </Card>

  <Card icon="list-todo" href="/development/backend/job-queue" title="Background Job Queue">
    Database-backed job processing system with persistent storage, automatic retries, and rate limiting for long-running background tasks.
  </Card>

  <Card icon="clock" href="/development/backend/cron" title="Cron Job Scheduling">
    Schedule recurring background tasks using cron expressions integrated with the job queue system.
  </Card>

  <Card icon="terminal" href="/development/backend/satellite/events" title="Satellite Events">
    Real-time event processing from satellites with convention-based handlers routing to business tables for operational visibility.
  </Card>
</CardGroup>

## Project Structure

```bash theme={null}
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)
│   └── db.selection.json    # Database type configuration
└── drizzle/                 # Database migrations
│   └── migrations_postgres/ # PostgreSQL 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

* **PostgreSQL Database**: Production-ready database with full ACID compliance
* **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.