Gateway Project Structure

The DeployStack Gateway is structured as a TypeScript CLI application using Commander.js with a modular architecture designed for maintainability and extensibility.

Directory Overview

services/gateway/
├── src/                      # Source code
│   ├── index.ts             # CLI entry point and command registration
│   ├── commands/            # Command implementations
│   │   ├── login.ts         # Authentication with cloud.deploystack.io
│   │   ├── start.ts         # Start the gateway server
│   │   ├── refresh.ts       # Root-level refresh command
│   │   └── ...              # Other CLI commands
│   ├── core/                # Core business logic
│   │   ├── auth/            # Authentication handling
│   │   ├── server/          # HTTP proxy server with SSE support
│   │   ├── process/         # MCP process management
│   │   ├── mcp/             # MCP configuration management
│   │   └── config/          # Configuration utilities
│   ├── services/            # Shared business services
│   │   ├── refresh-service.ts # Shared MCP configuration refresh logic
│   │   ├── server-start-service.ts # Centralized server startup logic
│   │   └── ...              # Other shared services
│   ├── utils/               # Shared utilities
│   │   ├── logger.ts        # Centralized logging
│   │   └── ...              # Other utilities
│   └── types/               # TypeScript type definitions
├── bin/gateway.js           # Executable entry point
├── dist/                    # Compiled JavaScript (gitignored)
├── tests/                   # Test suite
├── package.json             # Dependencies and scripts
├── tsconfig.json            # TypeScript configuration
└── README.md                # Gateway-specific documentation

Key Design Decisions

Modular Architecture

The codebase is organized into distinct modules:

Commands: User-facing CLI commands
Core: Business logic separated by domain
Services: Shared business services for cross-command functionality
Utils: Reusable utilities and helpers

Process Management

The process/ module handles the complexity of:

Managing persistent background MCP server processes
Runtime state tracking and team isolation
Managing stdio communication with running processes
Injecting environment variables securely at startup
Graceful process lifecycle management following MCP protocol

Security First

Credentials are never stored in plain text
All sensitive data is encrypted at rest
Environment injection happens at runtime only

Developer Experience

Intuitive command structure (deploystack login, deploystack start, deploystack mcp)
Rich CLI feedback with colors and progress indicators
Clear error messages with actionable solutions
MCP server management and tool discovery capabilities

Module Responsibilities

Commands Layer

Each command file exports a function that registers itself with Commander.js:

export function registerLoginCommand(program: Command) {
  program
    .command('login')
    .description('Authenticate with DeployStack cloud')
    .action(async () => {
      // Implementation
    });
}

Core Modules

auth/: Handles OAuth flow and token management

Secure storage of access tokens
Automatic token refresh
Session management

server/: HTTP proxy server with dual transport support

proxy.ts: Dual-endpoint routing (GET /sse for SSE connections, POST /message for session-based JSON-RPC)
session-manager.ts: Cryptographically secure session lifecycle management
sse-handler.ts: Server-Sent Events implementation for VS Code compatibility

process/: MCP server process lifecycle

Persistent background process management
Runtime state tracking with team isolation
Stdio transport implementation for continuous communication
Graceful lifecycle management following MCP protocol
Enterprise management layer (MCP servers as toggleable tools)

mcp/: Configuration management and processing

Team configuration synchronization with cloud control plane
Raw API data storage and processed config generation
Secure credential injection and environment variable management
MCP server tool discovery and capability exploration
Team-aware tool caching system as detailed in Caching System
Installation method processing for correct server spawning

services/: Shared business services for cross-command functionality

refresh-service.ts: Centralized MCP configuration refresh logic used by both deploystack refresh and deploystack mcp --refresh commands
Eliminates code duplication while maintaining identical behavior across commands
Provides consistent error handling and user feedback

utils/: Shared utilities and centralized services

tool-discovery-manager.ts: Centralized tool discovery eliminating code duplication across commands
Logging, configuration, and encryption utilities
Progress indicators and error handling

config/: Configuration utilities and defaults

Default gateway settings and validation
Configuration file management
Environment-specific overrides

Build Output

The TypeScript code is compiled to CommonJS for maximum compatibility:

Source maps for debugging
Minified for production
External dependencies preserved

On this page