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
│   │   ├── index.ts         # Command exports
│   │   ├── login.ts         # Authentication with cloud.deploystack.io
│   │   ├── logout.ts        # Clear local credentials
│   │   ├── start.ts         # Start the gateway server
│   │   ├── stop.ts          # Stop the gateway server
│   │   ├── status.ts        # Show gateway status
│   │   ├── mcp.ts           # MCP server management and tool discovery
│   │   └── config.ts        # Manage local configuration
│   ├── core/                # Core business logic
│   │   ├── auth/            # Authentication handling
│   │   │   ├── client.ts    # OAuth and API client
│   │   │   └── storage.ts   # Secure credential storage
│   │   ├── server/          # HTTP proxy server
│   │   │   ├── proxy.ts     # Request routing and dual-endpoint logic
│   │   │   ├── session-manager.ts # SSE session lifecycle management
│   │   │   └── sse-handler.ts # Server-Sent Events implementation
│   │   ├── process/         # MCP process management
│   │   │   ├── manager.ts   # Process lifecycle and stdio communication
│   │   │   └── runtime-state.ts # In-memory process state tracking
│   │   ├── mcp/             # MCP configuration management
│   │   │   ├── config-service.ts # Team config sync and processing
│   │   │   ├── config-processor.ts # Installation method processing
│   │   │   ├── tool-discovery.ts # MCP server tool discovery
│   │   │   ├── tool-cache.ts # Team-aware tool caching system
│   │   │   └── team-context-manager.ts # Team switching with process lifecycle
│   │   └── config/          # Configuration utilities
│   │       └── defaults.ts  # Default gateway settings
│   ├── utils/               # Shared utilities
│   │   ├── tool-discovery-manager.ts # Centralized tool discovery and caching
│   │   ├── state-comparator.ts # Compare expected vs actual running processes
│   │   ├── logger.ts        # Centralized logging with chalk
│   │   ├── spinner.ts       # Progress indicators with ora
│   │   ├── config.ts        # Configuration management
│   │   ├── errors.ts        # Custom error types
│   │   └── crypto.ts        # Encryption utilities
│   └── types/               # TypeScript type definitions
│       ├── index.ts         # Main type exports
│       ├── mcp.ts           # MCP protocol types
│       └── config.ts        # Configuration types
├── bin/                     # Executable entry
│   └── gateway.js           # Node.js shebang wrapper
├── dist/                    # Compiled JavaScript (gitignored)
├── tests/                   # Test suite
│   ├── unit/               # Unit tests
│   ├── integration/        # Integration tests
│   └── fixtures/           # Test data
├── scripts/                 # Development scripts
│   ├── build.ts            # Build script
│   └── release.ts          # Release automation
├── .config/                # Default configurations
│   └── defaults.json       # Default gateway settings
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
├── tsup.config.ts          # Build configuration
├── .env.example            # Environment variables template
└── 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
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

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