> ## 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.

# Development Guide

> Complete development documentation for DeployStack - the first MCP-as-a-Service platform with satellite infrastructure and cloud control plane.

Welcome to the DeployStack development documentation! DeployStack eliminates MCP adoption friction by transforming complex installations into simple URL configurations through managed satellite infrastructure.

## Architecture Overview

DeployStack implements an MCP-as-a-Service architecture that eliminates installation friction:

* **Frontend**: Vue 3 + TypeScript web application (cloud.deploystack.io) for team management and configuration
* **Backend**: Fastify-based cloud control plane handling authentication, teams, and satellite coordination
* **Satellite Infrastructure**: Managed MCP servers accessible via HTTPS URLs - no installation required
* **Shared**: Common utilities and TypeScript types used across all services
* **Dual Deployment**: Global satellites (DeployStack-managed) and team satellites (customer-deployed)

## Development Areas

<CardGroup cols={3}>
  <Card icon="code" href="/development/frontend" title="Frontend Development">
    Vue 3 web application with TypeScript, Vite, and shadcn-vue components. Team management interface for satellite configuration and usage analytics.
  </Card>

  <Card icon="server" href="/development/backend" title="Backend Development">
    Fastify cloud control plane with Drizzle ORM, JWT authentication, team management, and satellite coordination APIs.
  </Card>

  <Card icon="cloud" href="/development/satellite" title="Satellite Development">
    MCP-as-a-Service infrastructure with global satellites, team satellites, zero-installation access, and enterprise-grade security.
  </Card>
</CardGroup>

## Getting Started

### Prerequisites

* Node.js 18 or higher
* npm 8 or higher
* Git for version control
* Docker (for local PostgreSQL)

### Quick Setup

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/deploystackio/deploystack.git
    cd deploystack
    ```
  </Step>

  <Step title="Start PostgreSQL (Terminal 1)">
    ```bash theme={null}
    cd services/backend
    npm install
    npm run postgres:local
    ```

    This starts PostgreSQL 18 in Docker with default credentials (`deploystack`/`deploystack`).
  </Step>

  <Step title="Configure and Start Backend (Terminal 1)">
    ```bash theme={null}
    cp .env.example .env
    npm run dev
    ```

    Backend runs at [http://localhost:3000](http://localhost:3000)
  </Step>

  <Step title="Complete Setup Wizard">
    Open [http://localhost:5173/setup](http://localhost:5173/setup) in your browser to:

    * Initialize the database
    * Create your admin account
    * Configure basic settings
  </Step>

  <Step title="Start Frontend (Terminal 2)">
    ```bash theme={null}
    cd services/frontend
    npm install
    npm run dev
    ```

    Frontend runs at [http://localhost:5173](http://localhost:5173)
  </Step>

  <Step title="Start Satellite (Terminal 3 - Optional)">
    ```bash theme={null}
    cd services/satellite
    npm install
    cp .env.example .env
    # Edit .env: add DEPLOYSTACK_REGISTRATION_TOKEN from admin panel
    npm run dev
    ```

    Satellite runs at [http://localhost:3001](http://localhost:3001)

    <Info>
      To get a registration token, go to Admin → Satellites → Pairing in the DeployStack UI after completing the setup wizard.
    </Info>
  </Step>
</Steps>

## Development Workflow

1. **Choose Your Service**: Select frontend, backend, or satellite based on your contribution area
2. **Set Up Environment**: Follow the specific setup guides for your chosen service
3. **Understand Architecture**: Review how services interact (Frontend ↔ Backend ↔ Satellite)
4. **Make Changes**: Implement features following established patterns (Vue SFC for frontend, plugins for backend, managed services for satellite)
5. **Test**: Run comprehensive test suites for your service
6. **Submit**: Create pull requests following our contribution guidelines

## Project Structure

```bash theme={null}
deploystack/
├── services/
│   ├── frontend/           # Vue 3 frontend application
│   │   ├── src/
│   │   ├── public/
│   │   └── package.json
│   ├── backend/            # Fastify backend API
│   │   ├── src/
│   │   ├── plugins/
│   │   └── package.json
│   ├── satellite/          # Satellite edge worker (like GitHub Actions runner)
│   │   ├── src/
│   │   ├── config/
│   │   └── package.json
│   └── shared/             # Shared utilities and types
│       └── package.json
├── docs/                   # Documentation
└── docker-compose.yml     # Development environment
```

## Key Technologies

### Frontend Stack

* **Vue 3** with Composition API and Single File Components (SFC)
* **TypeScript** for type safety throughout the application
* **Vite** for fast HMR and optimized builds
* **TailwindCSS** with shadcn-vue component library
* **Direct fetch()** API calls (no axios or API client libraries)
* **Vue I18n** for multi-language support

### Backend Stack

* **Fastify** for high-performance cloud control plane
* **TypeScript** with full type safety
* **Drizzle ORM** with PostgreSQL
* **Plugin System** with isolated routes (`/api/plugin/<id>/`)
* **Role-Based Access Control** with session management

### Satellite Stack

* **Node.js** edge worker runtime (like GitHub Actions runner)
* **HTTP Proxy + stdio Communication** for dual MCP server deployment (external HTTP endpoints and local subprocesses)
* **OAuth 2.1 Resource Server** with Backend token introspection
* **Team Isolation** using Linux namespaces, cgroups, and resource jailing
* **Dual Deployment Model** global satellites (DeployStack-managed) and team satellites (customer-deployed)
* **Process Management** with automatic cleanup, selective restart, and lifecycle management

## Development Philosophy

### MCP-as-a-Service Platform

DeployStack provides managed MCP infrastructure through:

* **Zero Installation Friction**: Transform complex MCP setup into simple URL configuration
* **Managed Satellite Infrastructure**: Global satellites and enterprise team satellites
* **Enterprise Progression**: Freemium satellites → paid tiers → team satellites
* **Universal Compatibility**: Supports MCP servers in any language via managed infrastructure

### Code Quality

* **Type Safety**: TypeScript throughout the stack
* **Testing**: Comprehensive test coverage
* **Documentation**: Clear, up-to-date documentation
* **Security**: Built-in security best practices

## Contributing

We welcome contributions to DeployStack! Key areas include:

* **Frontend**: Vue components, UI/UX improvements, satellite management features
* **Backend**: API endpoints, satellite coordination, JWT authentication
* **Satellite**: Managed infrastructure, team isolation, deployment patterns
* **Documentation**: Guides, examples, API documentation
* **MCP Servers**: New satellite-hosted MCP server integrations
* **Security**: Enhanced team isolation, enterprise deployment features

## Community

* **GitHub**: [deploystackio/deploystack](https://github.com/deploystackio/deploystack)
* **Issues**: Report bugs and request features

For detailed development guides, choose your area of interest from the cards above. Each section contains comprehensive documentation for getting started, best practices, and advanced topics.