Main Directories and Their Purposes in oblien/openship: Complete Monorepo Guide

TLDR: The oblien/openship repository is organized as a pnpm monorepo containing four main application directories (apps/web, apps/dashboard, apps/cli, apps/desktop), shared package libraries (packages/ui, packages/db-email), and infrastructure folders (docker, scripts, docs) that collectively provide a self-hosted shipping management platform.

The openship project follows a monorepo architecture that consolidates multiple interconnected applications and shared libraries into a single repository. Understanding the main directories and their purposes in oblien/openship is essential for developers contributing to the web interface, CLI tooling, or desktop client. Each top-level folder hosts a distinct concern, from the public-facing marketing site to Docker deployment configurations.

Application Directories

The apps/ directory contains the primary deployable units of the openship ecosystem.

apps/web

This directory houses the public-facing website built with Next.js and TypeScript. It serves as the marketing site, documentation portal, and demo entry point for the platform. The application configuration resides in apps/web/next.config.js, which handles routing and build optimizations for the static and server-side rendered pages.

apps/dashboard

The self-hosted management UI that ship owners use to configure projects, view deployments, and manage resources. This is a Next.js application packaged with a Dockerfile located at apps/dashboard/Dockerfile for containerized deployment. The dashboard communicates with backend services to provide real-time shipping analytics and configuration interfaces.

apps/cli

Command-line interface implementation used for provisioning, building, and interacting with OpenShip services. Key commands include openship login and openship deploy. The entry point for the CLI tool is defined in apps/cli/src/cli.ts, which handles argument parsing and command routing. Developers interact with this package to automate deployment workflows and manage projects from terminal environments.

apps/desktop

An Electron-based desktop client that bundles the dashboard UI for a native application experience. This directory wraps the web-based dashboard in a standalone application window, providing system-level integrations while reusing the frontend components from the dashboard application.

Shared Package Directories

The packages/ directory contains library code shared across multiple applications.

packages/ui

Shared React component library providing styled UI primitives, theming utilities, and design system components consumed by both the web and dashboard apps. The package includes utility functions such as the cn() helper located in packages/ui/src/lib/cn.ts, which handles conditional Tailwind CSS class merging. This centralizes UI consistency across the monorepo.

packages/db-email

Helper package for sending transactional email with templating and database-backed queueing. This shared library abstracts email delivery logic, allowing both the web application and API endpoints to queue and send notifications reliably through database-managed job queues.

Infrastructure and Configuration

Supporting directories provide deployment, documentation, and automation capabilities.

docker

Contains Docker Compose files and Dockerfiles that define the multi-container deployment stack. The primary orchestration file is docker/docker-compose.yml, which wires together services including PostgreSQL, Redis, and the API layer. This directory enables self-hosted deployments using containerized infrastructure.

scripts

Utility scripts used for release automation, GeoIP database updates, and other maintenance tasks. The scripts/release.ts file handles version bumping and changelog generation across the monorepo, ensuring synchronized releases of interdependent packages.

docs

Markdown documentation covering installation procedures, internationalization (i18n), edge-routing requirements, and platform guides. This directory serves as the source for the project's documentation site.

fixtures

Sample projects and deployment fixtures used for integration tests and demos. These include example applications (such as basic Laravel setups) that test the platform's deployment capabilities and provide working examples for new users.

Root Configuration Files

The repository root contains workspace-level configuration that binds the monorepo together. The pnpm-workspace.yaml file declares which packages belong to the pnpm workspace, enabling dependency sharing and cross-package scripting. Root package.json defines shared scripts and development dependencies, while tsconfig.base.json provides TypeScript base settings inherited by applications and packages throughout the repository.

Working with the Codebase

Running the Web Site Locally

Start the Next.js development server for the marketing site:

pnpm install
pnpm --filter @openship/web dev

Building and Using the CLI

Compile and execute CLI commands for project provisioning according to the implementation in apps/cli/src/cli.ts:

pnpm --filter @openship/cli build
pnpm --filter @openship/cli exec -- openship provision \
  --project my-project \
  --region us-east-1

Launching the Desktop Client

Run the Electron application in development mode:

pnpm --filter @openship/desktop dev

Deploying with Docker Compose

Start the full production stack defined in docker/docker-compose.yml:

docker compose -f docker/docker-compose.yml up -d

Summary

• Four main applications: The apps/ directory contains the web marketing site (apps/web), management dashboard (apps/dashboard), command-line interface (apps/cli), and Electron desktop wrapper (apps/desktop).
• Shared libraries: packages/ui provides React components and Tailwind utilities like cn() found in packages/ui/src/lib/cn.ts, while packages/db-email handles transactional email with database queueing.
• Containerization: The docker/ directory contains docker-compose.yml and related configurations for deploying PostgreSQL, Redis, and application services.
• Automation: The scripts/ directory contains maintenance utilities including scripts/release.ts for coordinated version management across the monorepo.
• Workspace management: pnpm-workspace.yaml and root TypeScript configuration coordinate dependencies and builds across the monorepo structure.

Frequently Asked Questions

What is the purpose of the apps/cli directory in openship?

The apps/cli directory contains the command-line interface implementation that enables automation of OpenShip services. According to the source code in apps/cli/src/cli.ts, this package handles provisioning, deployment commands, and authentication workflows (such as openship login), allowing developers to manage shipping projects programmatically from terminal environments.

How does the packages/ui directory support other applications?

The packages/ui directory serves as a shared component library that exports React primitives and styling utilities consumed by both apps/web and apps/dashboard. The packages/ui/src/lib/cn.ts utility function provides conditional Tailwind CSS class merging, ensuring consistent theming and design system implementation across the web interface and management dashboard without code duplication.

Where are the Docker deployment configurations located?

Docker deployment configurations reside in the docker/ directory at the repository root. The docker/docker-compose.yml file defines the multi-container orchestration for PostgreSQL databases, Redis caching layers, and API services required for self-hosted instances. Additionally, apps/dashboard/Dockerfile provides the container definition for the management UI specifically.

What is the role of the scripts directory in the openship monorepo?

The scripts/ directory contains automation utilities for repository maintenance, including scripts/release.ts which manages version bumping and changelog generation across the pnpm workspace. These scripts handle tasks such as GeoIP database updates and coordinated releases that affect multiple packages simultaneously, ensuring the monorepo remains synchronized during deployment cycles.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}