# Openship Directory Structure: Complete Monorepo Layout Guide > Understand the openship directory structure. Explore its monorepo layout with apps, packages, and docker folders for efficient development and deployment. Learn more! - Repository: [oblien/openship](https://github.com/oblien/openship) - Tags: deep-dive - Published: 2026-07-31 --- **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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/src/index.tsx) (the package entry point) and [`src/components/card.tsx`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/src/schema/project.ts) for table definitions and [`src/repos/project.repo.ts`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/src/schema/vmail.ts) for email table structures and [`src/client.ts`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/src/flow.ts) (orchestrating the setup sequence) and [`src/api-client.ts`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/docs/ARCHITECTURE.md) and [`docs/BUILD-PIPELINE.md`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml)** – Production stack definition including Postgres, Redis, API, dashboard, and OpenResty edge proxy - **[`docker/docker-compose.build.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.build.yml)** – Build-from-source variant used by `openship up --build` - **[`docker-compose.yml`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/installation.md) for quick-start guides and [`oblien-edge-routing-requirements.md`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/scripts/release.ts)** – TypeScript release orchestration script used by CI pipelines - **[`scripts/install.sh`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/pnpm-workspace.yaml)** – Declares which directories are included in the PNPM workspace (typically `apps/*` and `packages/*`) - **[`tsconfig.base.json`](https://github.com/oblien/openship/blob/main/tsconfig.base.json)** – Base TypeScript compiler options inherited by all packages via their local [`tsconfig.json`](https://github.com/oblien/openship/blob/main/tsconfig.json) files - **[`package.json`](https://github.com/oblien/openship/blob/main/package.json)** – Root project metadata and workspace-level scripts - **[`README.md`](https://github.com/oblien/openship/blob/main/README.md)** – Primary project documentation and architecture overview ## Practical Usage Examples Clone the repository and install dependencies using PNPM workspaces: ```bash # 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: ```bash # Production-ready stack from docker/docker-compose.yml docker compose -f docker/docker-compose.yml up -d ``` Develop the web dashboard locally: ```bash 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`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml), which orchestrates the entire stack including databases and edge proxies - **Workspace management** relies on [`pnpm-workspace.yaml`](https://github.com/oblien/openship/blob/main/pnpm-workspace.yaml) and [`tsconfig.base.json`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/pnpm-workspace.yaml). For example, [`packages/ui/src/index.tsx`](https://github.com/oblien/openship/blob/main/packages/ui/src/index.tsx) exports React components imported by `apps/web/`, and [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/src/schema/project.ts) and repositories like [`src/repos/project.repo.ts`](https://github.com/oblien/openship/blob/main/src/repos/project.repo.ts)), while `packages/db-email/` isolates mail-related tables in [`src/schema/vmail.ts`](https://github.com/oblien/openship/blob/main/src/schema/vmail.ts) with its own client at [`src/client.ts`](https://github.com/oblien/openship/blob/main/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.