# Openship Project Structure: Modular Architecture and Core Components Guide

> Explore the Openship project structure an organized monorepo. Understand core components like API CLI edge routing TLS and unified interfaces for Desktop Web and CLI.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: architecture
- Published: 2026-07-31

---

**Openship organizes its deployment platform into a monorepo where `packages/core` orchestrates the API and CLI, `packages/edge` handles routing and TLS, and `apps/` delivers Desktop, Web, and CLI interfaces that share a unified control plane.**

Openship is an open-source, self-hostable deployment platform developed by oblien/openship that bundles CI/CD pipelines, reverse proxying, and application runtime into a single system. Understanding the Openship project structure reveals how its modular architecture separates the control plane from build pipelines, edge routing, and user interfaces while maintaining consistency across all interaction modes.

## Core Control Plane (packages/core)

The central nervous system of Openship resides in `packages/core`, implementing the API server, command-line interface, and internal orchestration logic.

### CLI Bootstrap

[`packages/core/src/cli.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/cli.ts) serves as the entry point for the command-line interface. This file parses user commands such as `openship up`, `openship init`, and `openship deploy`, then delegates execution to the appropriate handlers within the control plane.

### API Server Initialization

[`packages/core/src/app.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/app.ts) creates the HTTP server that exposes REST endpoints, MCP (machine-to-machine communication) protocols, and static assets for the web dashboard. This Express-style application server handles incoming requests from all three interfaces (Desktop, Web, and CLI).

### Service Registry

[`packages/core/src/index.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/index.ts) acts as the wiring harness, instantiating and connecting subsystems including the database layer, Docker integration, edge proxy management, and build pipelines. It exposes these services through a unified API surface used by the rest of the application.

## Build and Deployment Pipeline

Openship implements a four-stage deployment pipeline managed through dedicated modules in the core package.

### Stack Detection

[`packages/core/src/pipeline/detect.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/pipeline/detect.ts) inspects project metadata—specifically [`package.json`](https://github.com/oblien/openship/blob/main/package.json), lockfiles, [`docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker-compose.yml), and optional [`openship.json`](https://github.com/oblien/openship/blob/main/openship.json) configurations—to automatically infer the technology stack, package manager, build commands, and exposed ports.

### Build Execution

[`packages/core/src/pipeline/build.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/pipeline/build.ts) executes the resolved build process either inside an isolated Docker container or directly on the host system (Bare mode). This module produces immutable artifacts ready for deployment, handling both containerized and binary releases.

## Edge Routing and TLS Termination

The `packages/edge` directory contains the OpenResty-based (NGINX + Lua) reverse proxy implementation. 

[`packages/edge/src/proxy.ts`](https://github.com/oblien/openship/blob/main/packages/edge/src/proxy.ts) dynamically generates virtual-host configurations for each deployed project and automatically provisions Let's Encrypt certificates via HTTP-01 challenges. The edge proxy runs in host-network mode on ports 80 and 443, routing incoming traffic to the appropriate application containers or processes.

## User Interfaces and Applications

Openship provides three distinct interfaces that consume the same control-plane API, ensuring consistent behavior regardless of how users interact with the platform.

- **Desktop Application**: An Electron-based GUI located in `apps/desktop` that runs the control plane locally and can drive remote servers via SSH, ideal for solo developers requiring visual deployment management.

- **Web Dashboard**: A Next.js single-page application configured via `apps/dashboard/next.config.mjs`, served by the API server at [`packages/core/src/app.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/app.ts), designed for team collaboration and centralized management.

- **CLI Tool**: A thin, scriptable client that bundles the API and dashboard binary for headless deployments and CI/CD integration.

## Adapters and Extensibility

The `packages/adapters` directory contains pluggable modules that integrate with external services such as cloud providers and secret stores. Each adapter follows a contract-based pattern—implementing required methods and registering with the core service registry defined in [`packages/core/src/index.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/index.ts)—allowing developers to extend Openship functionality without modifying core logic.

## Self-Hosting Configuration

For production deployments, [`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml) defines the complete infrastructure stack including PostgreSQL for persistence, Redis for caching, the API server, dashboard assets, and the edge proxy.

## Practical Usage Examples

Initialize a new project and deploy using the CLI:

```bash

# Install the CLI

curl -fsSL https://get.openship.io | sh

# Create openship.json and link repository

openship init

# Execute full pipeline: detect → build → run → route

openship deploy

```

Launch a self-hosted instance using Docker Compose:

```bash
git clone https://github.com/oblien/openship.git
cd openship
cp .env.example .env
docker compose -f docker/docker-compose.yml up -d

```

Query the control-plane API directly:

```bash
curl -H "Authorization: Bearer $OPENSHIP_TOKEN" \
     http://localhost:3000/api/v1/projects

```

## Summary

- **Openship project structure** follows a monorepo pattern with clear separation between `packages/core` (orchestration), `packages/edge` (routing), and `apps/` (interfaces)
- [`packages/core/src/cli.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/cli.ts) parses all command-line input and initializes the control plane
- [`packages/core/src/app.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/app.ts) bootstraps the API server handling REST endpoints and MCP protocols
- [`packages/core/src/pipeline/detect.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/pipeline/detect.ts) and [`build.ts`](https://github.com/oblien/openship/blob/main/build.ts) implement the automated build pipeline
- [`packages/edge/src/proxy.ts`](https://github.com/oblien/openship/blob/main/packages/edge/src/proxy.ts) manages dynamic routing and automatic TLS certificate provisioning
- Three interfaces (Desktop, Web, CLI) share the same backend API via [`packages/core/src/index.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/index.ts) service registry

## Frequently Asked Questions

### What is the main entry point for the Openship CLI?

The main entry point is [`packages/core/src/cli.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/cli.ts), which bootstraps the command-line interface and parses commands such as `openship up`, `openship init`, and `openship deploy` before delegating to the appropriate handlers in the control plane.

### How does Openship automatically detect the technology stack for a project?

Stack detection occurs in [`packages/core/src/pipeline/detect.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/pipeline/detect.ts), which inspects project files including [`package.json`](https://github.com/oblien/openship/blob/main/package.json), lockfiles, and [`docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker-compose.yml) to automatically infer the build command, package manager, and exposed ports without requiring manual configuration.

### Where does Openship handle SSL termination and reverse proxy configuration?

Routing and TLS termination are handled by the edge proxy in [`packages/edge/src/proxy.ts`](https://github.com/oblien/openship/blob/main/packages/edge/src/proxy.ts), which uses OpenResty (NGINX with Lua) to dynamically generate virtual-host configurations and automatically provision Let's Encrypt certificates via HTTP-01 challenges.

### How do the Desktop, Web, and CLI interfaces interact with the backend?

All three interfaces communicate with the same control-plane API implemented in [`packages/core/src/app.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/app.ts). The Desktop app runs the control plane locally via Electron, the Web dashboard is a Next.js SPA served by the API, and the CLI provides scriptable access to the same endpoints, ensuring consistent behavior across all interaction modes according to the oblien/openship source code.