Directory Structure for Openship Dependencies: Complete Monorepo Guide

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, 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 and 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 – Public API exports
• packages/onboarding/src/flow.ts – Step-by-step onboarding orchestration logic
• 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 – Core customer projects and container definitions
• packages/db/src/schema/deployment.ts – Application deployment records
• packages/db/src/schema/service.ts – Individual services belonging to projects
• packages/db/src/schema/github.ts – GitHub integration metadata
• packages/db/src/schema/notification.ts – User-visible event storage
• packages/db/src/schema/audit-event.ts – Privileged action auditing

The schema index at 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, 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 – Virtual mail table definitions
• 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 – Wrapper around the ssh2 library implementing the SystemSSH class for remote command execution
• 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 – Transforms Dockerfile syntax into an internal AST representation
• 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 – Registry of supported tools including docker, kubectl, and certbot
• 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 – Validates Dockerfile generation logic
• packages/adapters/test/system-ssh-executor.test.ts – Tests SSH command execution flows
• packages/adapters/test/cloud-workload-cmd.test.ts – Validates cloud-specific workload commands
• packages/adapters/test/resource-limits.test.ts – Ensures container resource constraints are enforced

Example: Inserting a Project Record

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.

Example: Remote Command Execution

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 automatically handles connection lifecycle and teardown.

Example: Dockerfile Generation

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.

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 and deployment.ts
• Infrastructure adapters in packages/adapters handle SSH operations via system-ssh.ts and Dockerfile generation via parser.ts and compiler.ts
• Entry points for onboarding logic reside in packages/onboarding/src/flow.ts
• Email functionality is encapsulated in packages/db-email/src/client.ts
• Vitest validates all components, with migration safety checks in 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. The 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 provides a low-level wrapper around the ssh2 library, while 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 for database migrations and 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 converts raw Dockerfile syntax into an internal AST, and 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.

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