Openship Directory Structure: Complete Monorepo Layout Guide

The openship repository follows a TypeScript-based monorepo architecture organized into apps/ for deployable services, packages/ for shared libraries, and docker/ for self-hosting orchestration, all managed through PNPM workspaces defined in pnpm-workspace.yaml.

The openship directory structure implements a workspace-based monorepo pattern that separates user-facing applications from reusable core libraries. This organization enables independent versioning and building of components while maintaining a unified dependency tree. Understanding this layout is essential for contributing to the platform or deploying self-hosted instances according to the oblien/openship source code.

Top-Level Organization Overview

The repository root contains six logical zones that separate runtime services from infrastructure and documentation:

• apps/ – User-facing applications including the web dashboard, API backend, and email service
• packages/ – Reusable libraries covering UI components, database schemas, and onboarding logic
• docker/ – Docker Compose configurations for self-hosting the complete stack
• docs/ – Installation guides, routing requirements, and internationalization files
• scripts/ – Release automation and CLI installation scripts
• Configuration files – Root-level TypeScript, PNPM, and project metadata files

Each directory operates as part of a unified workspace defined in pnpm-workspace.yaml, allowing packages to share dependencies while building independently.

The Apps Directory: Deployable Services

The apps/ folder contains three distinct deployable services, each with its own tsconfig.json, source code, and Dockerfile.

apps/web (Next.js Dashboard)

This package hosts the React-based web dashboard built with Next.js. It consumes shared components from packages/ui and communicates with apps/api for data operations. The entry point and routing logic follow standard Next.js conventions within the apps/web/ path.

apps/api (Backend API)

The apps/api/ directory contains the REST and MCP (Model Context Protocol) API that powers the dashboard and CLI interactions. This backend service handles business logic, authentication, and orchestrates calls to the database layers defined in packages/db. The runtime mode selection logic (Compose vs. Bare) lives within this application's entry point.

apps/email (Email Service)

Located at apps/email/, this service manages SMTP connections, email templating, and notification delivery. It utilizes the separate packages/db-email schema for mail-related data storage and operates as a standalone microservice within the Docker Compose stack.

The Packages Directory: Core Libraries

The packages/ directory houses five specialized libraries that provide shared functionality across applications.

packages/ui (Shared Components)

This library exports reusable React components and styling utilities. Key files include src/index.tsx (the package entry point) and src/components/card.tsx (component implementations). Applications import these components directly from the workspace, ensuring UI consistency across the platform.

packages/db (Primary Database Layer)

Containing Drizzle-ORM schema definitions and repository patterns, this package manages the PostgreSQL data layer. Critical files include src/schema/project.ts for table definitions and src/repos/project.repo.ts for data access logic. All database migrations and core entity definitions reside here.

packages/db-email (Mail Schema)

This separate package isolates mail-related database concerns, providing src/schema/vmail.ts for email table structures and src/client.ts for database connection handling. This separation allows the email service to operate with a distinct schema while maintaining type safety.

packages/onboarding (Setup Wizard)

The onboarding package contains logic for the initial platform setup, including SSH validation and configuration generation. Key implementation files are src/flow.ts (orchestrating the setup sequence) and src/api-client.ts (handling validation requests).

packages/adapters (Integration Layer)

This package houses integration adapters for cloud providers, CI/CD executors, and logging services. While source files reside under src/, the directory includes comprehensive documentation at docs/ARCHITECTURE.md and docs/BUILD-PIPELINE.md detailing adapter implementation patterns.

Docker and Deployment Configuration

The docker/ directory provides production-ready orchestration files for self-hosting:

• docker/docker-compose.yml – Production stack definition including Postgres, Redis, API, dashboard, and OpenResty edge proxy
• docker/docker-compose.build.yml – Build-from-source variant used by openship up --build
• docker-compose.yml (root) – SaaS control-plane configuration (not intended for app hosting)

These configurations spin up the full platform stack with a single command, mounting the built applications from their respective apps/ directories.

Documentation and Automation

docs/ Folder

The documentation directory contains installation.md for quick-start guides and oblien-edge-routing-requirements.md for edge-proxy configuration. The i18n/ subdirectory houses README translations in Arabic, Chinese, and other languages.

scripts/ Folder

Automation utilities include:

• scripts/release.ts – TypeScript release orchestration script used by CI pipelines
• scripts/install.sh and scripts/install.ps1 – Cross-platform CLI bootstrap scripts for Unix and Windows

Workspace Configuration Files

Several root-level files govern the monorepo behavior:

• pnpm-workspace.yaml – Declares which directories are included in the PNPM workspace (typically apps/* and packages/*)
• tsconfig.base.json – Base TypeScript compiler options inherited by all packages via their local tsconfig.json files
• package.json – Root project metadata and workspace-level scripts
• README.md – Primary project documentation and architecture overview

Practical Usage Examples

Clone the repository and install dependencies using PNPM workspaces:

# Install the CLI (bundles API + dashboard) - executes scripts/install.sh

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

Start the full self-hosted stack using the Docker configurations:

# Production-ready stack from docker/docker-compose.yml

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

Develop the web dashboard locally:

cd apps/web
npm install   # Pulls shared UI package from workspace

npm run dev   # Starts Next.js development server

Summary

• The openship directory structure separates concerns into apps/ (runtimes), packages/ (libraries), and docker/ (infrastructure)
• User-facing services live in apps/web/, apps/api/, and apps/email/, each with independent deployment configurations
• Shared code resides in packages/, with packages/db/ handling core PostgreSQL schemas via Drizzle ORM and packages/ui/ providing React components
• Self-hosting is simplified through docker/docker-compose.yml, which orchestrates the entire stack including databases and edge proxies
• Workspace management relies on pnpm-workspace.yaml and tsconfig.base.json to maintain consistency across the TypeScript monorepo

Frequently Asked Questions

What is the purpose of the apps directory in openship?

The apps/ directory contains three deployable services: apps/web/ provides the Next.js React dashboard, apps/api/ hosts the REST/MCP backend API, and apps/email/ manages SMTP and notification delivery. Each application includes its own Dockerfile and TypeScript configuration while consuming shared libraries from the packages/ directory.

How does openship manage shared code between applications?

Shared functionality resides in the packages/ directory, which is linked through PNPM workspaces defined in pnpm-workspace.yaml. For example, packages/ui/src/index.tsx exports React components imported by apps/web/, and packages/db/src/schema/project.ts defines database schemas used by apps/api/. This workspace pattern ensures type safety and dependency deduplication across the monorepo.

Where are the database schemas defined in the openship repository?

Database schemas are split between two packages: packages/db/ contains the primary Drizzle-ORM schemas for the PostgreSQL store (including src/schema/project.ts and repositories like src/repos/project.repo.ts), while packages/db-email/ isolates mail-related tables in src/schema/vmail.ts with its own client at src/client.ts for the email service.

How do I run the openship platform locally for development?

Navigate to the specific application directory (such as apps/web/ or apps/api/) and run npm install followed by npm run dev to start the development server. For the complete stack, use docker compose -f docker/docker-compose.yml up -d from the repository root, which spins up Postgres, Redis, the API, dashboard, and edge proxy as configured in the docker/ directory.

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