# Directory Structure for Openship Dependencies: Complete Monorepo Guide

> Explore the Openship monorepo directory structure for managing dependencies. Learn how packages organize database schemas, adapters, and UI components in this comprehensive guide.

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

---

**Openship organizes its dependencies into a modular monorepo under `packages/`, isolating concerns like database schemas, SSH adapters, and UI components into discrete TypeScript packages with independent entry points and comprehensive test suites.**

The oblien/openship repository follows a strict **packages-per-concern** layout that separates business logic, infrastructure adapters, and database schemas into self-contained units. Understanding the directory structure for Openship dependencies is essential for contributing to the platform or extending its capabilities with custom adapters. Each package maintains its own [`package.json`](https://github.com/oblien/openship/blob/main/package.json), TypeScript configuration, and Vitest test suite while sharing common runtime conventions.

## Core Packages and Shared Infrastructure

The foundation of the Openship architecture rests on three primary packages that handle user interface rendering, onboarding flows, and shared business logic.

### UI and Onboarding Modules

The `packages/ui` directory contains React-based frontend components for the management console, configured via [`packages/ui/package.json`](https://github.com/oblien/openship/blob/main/packages/ui/package.json) and [`packages/ui/tsconfig.json`](https://github.com/oblien/openship/blob/main/packages/ui/tsconfig.json). 

The `packages/onboarding` directory manages user registration flows and SSH key provisioning. Critical entry points include:

- [`packages/onboarding/src/index.ts`](https://github.com/oblien/openship/blob/main/packages/onboarding/src/index.ts) – Public API exports
- [`packages/onboarding/src/flow.ts`](https://github.com/oblien/openship/blob/main/packages/onboarding/src/flow.ts) – Step-by-step onboarding orchestration logic
- [`packages/onboarding/src/ssh.ts`](https://github.com/oblien/openship/blob/main/packages/onboarding/src/ssh.ts) – SSH key generation and validation utilities

These modules import shared utilities from `packages/core`, ensuring consistent validation logic across the frontend and backend boundaries.

## Database Layer Dependencies

Openship persists application state using **Drizzle ORM**, with schemas isolated in dedicated database packages.

### Primary Schema Definitions (`packages/db`)

The `packages/db` directory defines the persistence layer through individual table files under `src/schema/`:

- [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts) – Core customer projects and container definitions
- [`packages/db/src/schema/deployment.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/deployment.ts) – Application deployment records
- [`packages/db/src/schema/service.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/service.ts) – Individual services belonging to projects
- [`packages/db/src/schema/github.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/github.ts) – GitHub integration metadata
- [`packages/db/src/schema/notification.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/notification.ts) – User-visible event storage
- [`packages/db/src/schema/audit-event.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/audit-event.ts) – Privileged action auditing

The schema index at [`packages/db/src/schema/index.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/index.ts) aggregates all table definitions for consumption by other packages.

Data integrity is enforced by [`packages/db/src/restore-wipe-gate.test.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/restore-wipe-gate.test.ts), a Vitest suite that validates schema migrations and safe data-wipe procedures before production deployment.

### Email Integration (`packages/db-email`)

The `packages/db-email` package extends the core database with mail-specific entities. Key files include:

- [`packages/db-email/src/schema/vmail.ts`](https://github.com/oblien/openship/blob/main/packages/db-email/src/schema/vmail.ts) – Virtual mail table definitions
- [`packages/db-email/src/client.ts`](https://github.com/oblien/openship/blob/main/packages/db-email/src/client.ts) – Thin wrapper client used by higher-level services for email operations

## Infrastructure Adapters

The `packages/adapters` directory translates high-level Openship concepts into concrete runtime artifacts including Docker containers, systemd units, and SSH tunnels.

### System Operations and SSH

Low-level host interactions are handled by the system adapter submodule:

- [`packages/adapters/src/system/system-ssh.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/system-ssh.ts) – Wrapper around the `ssh2` library implementing the `SystemSSH` class for remote command execution
- [`packages/adapters/src/system/system-ssh-executor.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/system-ssh-executor.ts) – Higher-level executor that tunnels commands into containers via SSH connections

### Dockerfile Processing

Containerization logic resides in the dockerfile submodule:

- [`packages/adapters/src/dockerfile/parser.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/dockerfile/parser.ts) – Transforms Dockerfile syntax into an internal AST representation
- [`packages/adapters/src/dockerfile/compiler.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/dockerfile/compiler.ts) – Converts the AST back into concrete Dockerfile output for build steps

### Toolchain Management

The toolchain submodule manages external binary dependencies:

- [`packages/adapters/src/toolchain/catalog.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/toolchain/catalog.ts) – Registry of supported tools including `docker`, `kubectl`, and `certbot`
- [`packages/adapters/src/toolchain/checks.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/toolchain/checks.ts) – Pre-flight version and capability validation for host environments

## Testing Structure and Validation

Each package contains a `test/` directory with Vitest suites validating component behavior:

- [`packages/adapters/test/docker-build-plan.test.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/test/docker-build-plan.test.ts) – Validates Dockerfile generation logic
- [`packages/adapters/test/system-ssh-executor.test.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/test/system-ssh-executor.test.ts) – Tests SSH command execution flows
- [`packages/adapters/test/cloud-workload-cmd.test.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/test/cloud-workload-cmd.test.ts) – Validates cloud-specific workload commands
- [`packages/adapters/test/resource-limits.test.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/test/resource-limits.test.ts) – Ensures container resource constraints are enforced

### Example: Inserting a Project Record

```typescript
import { db } from '@openship/db';
import { project } from '@openship/db/src/schema/project';

// Insert a new project with a friendly name
await db
  .insert(project)
  .values({ name: 'my-awesome-app', slug: 'awesome-app' })
  .run();

```

This example consumes the Drizzle schema defined in [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts).

### Example: Remote Command Execution

```typescript
import { SystemSSH } from '@openship/adapters/src/system/system-ssh';

const ssh = new SystemSSH({
  host: 'example.server.com',
  username: 'openship',
  privateKey: process.env.SSH_PRIVATE_KEY!,
});

const output = await ssh.exec('docker ps --format "{{.Names}}"');
console.log('Running containers:', output);

```

The `SystemSSH` class from [`packages/adapters/src/system/system-ssh.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/system-ssh.ts) automatically handles connection lifecycle and teardown.

### Example: Dockerfile Generation

```typescript
import { DockerfileParser } from '@openship/adapters/src/dockerfile/parser';
import { DockerfileCompiler } from '@openship/adapters/src/dockerfile/compiler';

const spec = `
FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm ci && npm run build
CMD ["node", "dist/index.js"]
`;

const ast = DockerfileParser.parse(spec);
const dockerfile = DockerfileCompiler.compile(ast);
console.log(dockerfile);

```

This pipeline uses the parser and compiler modules to transform string specifications into buildable Dockerfiles, as exercised in [`packages/adapters/test/docker-build-plan.test.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/test/docker-build-plan.test.ts).

## Summary

- Openship uses a **monorepo structure** under `packages/` to isolate dependencies by functional concern
- **Database schemas** are defined in `packages/db/src/schema/` using Drizzle ORM, with tables split into discrete files like [`project.ts`](https://github.com/oblien/openship/blob/main/project.ts) and [`deployment.ts`](https://github.com/oblien/openship/blob/main/deployment.ts)
- **Infrastructure adapters** in `packages/adapters` handle SSH operations via [`system-ssh.ts`](https://github.com/oblien/openship/blob/main/system-ssh.ts) and Dockerfile generation via [`parser.ts`](https://github.com/oblien/openship/blob/main/parser.ts) and [`compiler.ts`](https://github.com/oblien/openship/blob/main/compiler.ts)
- **Entry points** for onboarding logic reside in [`packages/onboarding/src/flow.ts`](https://github.com/oblien/openship/blob/main/packages/onboarding/src/flow.ts)
- **Email functionality** is encapsulated in [`packages/db-email/src/client.ts`](https://github.com/oblien/openship/blob/main/packages/db-email/src/client.ts)
- **Vitest** validates all components, with migration safety checks in [`packages/db/src/restore-wipe-gate.test.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/restore-wipe-gate.test.ts)

## Frequently Asked Questions

### Where are the database schema definitions located in Openship?

The schema definitions reside in `packages/db/src/schema/`, with each table (projects, deployments, services) stored in its own TypeScript file such as [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts). The [`packages/db/src/schema/index.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/index.ts) file exports all table definitions for use across the monorepo.

### How does Openship handle SSH connections to remote hosts?

SSH functionality is implemented in the adapters package. The `SystemSSH` class defined in [`packages/adapters/src/system/system-ssh.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/system-ssh.ts) provides a low-level wrapper around the `ssh2` library, while [`packages/adapters/src/system/system-ssh-executor.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/system-ssh-executor.ts) offers a higher-level interface for executing commands inside containers via established tunnels.

### What testing framework validates the directory structure components?

Openship uses **Vitest** for all testing. The repository includes comprehensive test suites such as [`packages/db/src/restore-wipe-gate.test.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/restore-wipe-gate.test.ts) for database migrations and [`packages/adapters/test/docker-build-plan.test.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/test/docker-build-plan.test.ts) for containerization logic, ensuring each package maintains isolation while integrating correctly with the broader system.

### How are Dockerfiles generated from high-level specifications?

The adapters package includes a two-stage pipeline: [`packages/adapters/src/dockerfile/parser.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/dockerfile/parser.ts) converts raw Dockerfile syntax into an internal AST, and [`packages/adapters/src/dockerfile/compiler.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/dockerfile/compiler.ts) renders that AST back into valid Dockerfile output. This allows programmatic manipulation of container definitions before shipping them to the build daemon.