# What Files Are in the Openship Directory? Complete Guide to the Repository Structure

> Explore the OpenShip directory structure. Understand TypeScript monorepo files, apps, packages, Docker definitions, and automation scripts. Get a complete guide to the repository.

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

---

**The openship directory contains a TypeScript monorepo with configuration files, application code, shared libraries, Docker definitions, and automation scripts organized under standard directories like `apps/`, `packages/`, and `docker/`.**

The `oblien/openship` repository is a unified platform that combines a web dashboard, API server, desktop client, and reusable UI components. Understanding the file types and directory layout is essential for contributors and developers deploying the shipping management platform. This guide breaks down every major file category found throughout the codebase, from root-level metadata to nested application source files.

## Project Metadata and Configuration Files

At the repository root, you’ll find standard monorepo configuration files that define the project structure and dependencies.

**[`package.json`](https://github.com/oblien/openship/blob/main/package.json)** sits at the root level and declares workspace patterns, build scripts, and shared dependencies. According to the openship source code, this file references workspaces via `apps/*` and `packages/*` globs.

**[`pnpm-workspace.yaml`](https://github.com/oblien/openship/blob/main/pnpm-workspace.yaml)** explicitly declares the monorepo boundaries:

```yaml
packages:
  - 'apps/*'
  - 'packages/*'

```

Additional configuration files include **[`tsconfig.base.json`](https://github.com/oblien/openship/blob/main/tsconfig.base.json)** (shared TypeScript compiler options), **`.prettierrc`** (code formatting rules), and **`.env.example`** (environment variable templates). These files ensure consistency across the multiple TypeScript applications contained in the repository.

## Application Source Code (apps/ Directory)

The `apps/` directory contains deployable applications written in TypeScript and TSX. Each subdirectory represents a distinct service:

- **`apps/web/`** – The Next.js dashboard and frontend interface
- **`apps/api/`** – The backend API server
- **`apps/desktop/`** – Electron-based desktop client
- **`apps/edge/`** – Edge runtime functions

Typical file types here include:
- **`.ts`** and **`.tsx`** files for React components and API routes
- **`.css`** files for styling
- **`Dockerfile`** definitions for containerization

For example, the web application includes **[`apps/web/src/lib/og-image.tsx`](https://github.com/oblien/openship/blob/main/apps/web/src/lib/og-image.tsx)**, a React component responsible for generating Open Graph images. The API layer entry point is located at **[`apps/api/src/index.ts`](https://github.com/oblien/openship/blob/main/apps/api/src/index.ts)**.

## Shared Libraries (packages/ Directory)

The `packages/` directory houses reusable code consumed by multiple applications. These libraries follow the same TypeScript conventions but export public APIs for cross-project usage.

Key files include:
- **[`packages/ui/src/index.tsx`](https://github.com/oblien/openship/blob/main/packages/ui/src/index.tsx)** – The entry point for the shared UI component library
- **[`packages/core/src/apps/README.md`](https://github.com/oblien/openship/blob/main/packages/core/src/apps/README.md)** – Documentation for core application utilities

These packages typically contain:
- **`.ts`** and **`.tsx`** source files
- **[`package.json`](https://github.com/oblien/openship/blob/main/package.json)** files defining their individual dependencies
- **README.md** files documenting API usage

## Build and Deployment Configuration

Containerization and infrastructure files reside primarily in the `docker/` directory and application roots.

**[`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml)** orchestrates the development environment, spinning up the web dashboard alongside dependent services. Individual applications contain their own **`Dockerfile`** definitions for production builds.

Continuous integration is configured in **[`.github/workflows/ci.yml`](https://github.com/oblien/openship/blob/main/.github/workflows/ci.yml)**, which defines GitHub Actions pipelines for testing and linting on pull requests.

## Scripts and Automation

The `scripts/` directory contains automation logic for releases and installation:

- **[`scripts/release.ts`](https://github.com/oblien/openship/blob/main/scripts/release.ts)** – A TypeScript automation script used by CI pipelines to manage versioning and deployments
- **[`scripts/install.sh`](https://github.com/oblien/openship/blob/main/scripts/install.sh)** – Shell script for automated installation
- **`scripts/install.ps1`** – PowerShell variant for Windows environments

These scripts handle tasks from dependency installation to production deployments across the monorepo.

## Documentation and Assets

Documentation files use Markdown and image formats stored in the `docs/` directory:

- **[`docs/installation.md`](https://github.com/oblien/openship/blob/main/docs/installation.md)** – Detailed setup instructions covering three deployment modes
- **`docs/screenshots/screen.png`** – Visual assets for documentation

Utility files at the root include **`.gitignore`** for version control exclusions and **`.nvmrc`** for Node.js version management.

## Practical Code Examples

To interact with these files programmatically, use the following approaches:

**Listing common file types in the repository:**

```bash

# From the repository root

find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.json" -o -name "*.md" -o -name "*.yml" \) \
| sort | uniq -c | sort -nr

```

**Reading the main package configuration:**

```typescript
import fs from "fs";
import path from "path";

const pkgPath = path.resolve(__dirname, "..", "package.json");
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
console.log(`Project name: ${pkg.name}`);
console.log(`Workspaces: ${pkg.workspaces?.join(", ")}`);

```

**Starting the development environment:**

```bash
docker compose -f docker/docker-compose.yml up --build

```

## Summary

- **The openship directory** contains a TypeScript monorepo with applications under `apps/` and shared libraries under `packages/`
- **Configuration files** like [`package.json`](https://github.com/oblien/openship/blob/main/package.json), [`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) define the workspace boundaries and build rules
- **Source code** primarily uses `.ts` and `.tsx` extensions for React components and API endpoints
- **Docker files** in [`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml) and individual `Dockerfile` definitions provide containerized deployment options
- **Automation scripts** in [`scripts/release.ts`](https://github.com/oblien/openship/blob/main/scripts/release.ts) and GitHub workflows handle CI/CD pipelines
- **Documentation** resides in `docs/` with Markdown guides and screenshot assets

## Frequently Asked Questions

### What programming language is the openship repository written in?

The openship repository is primarily written in **TypeScript**, with TSX files for React components and standard `.ts` files for backend logic and utilities. Shell scripts (`.sh`) and PowerShell scripts (`.ps1`) handle installation and automation tasks.

### Where are the main applications located in the openship directory?

The main applications reside in the **`apps/`** directory, which contains subdirectories for `web` (dashboard), `api` (backend server), `desktop` (Electron client), and `edge` (edge functions). Each subdirectory functions as an independent deployable unit with its own source code and configuration.

### How do I start the openship platform locally using the provided files?

Run `docker compose -f docker/docker-compose.yml up --build` from the repository root. This command reads the Docker Compose configuration and builds the necessary images for the web dashboard and its dependencies, creating a complete local development environment.

### What is the purpose of the packages directory in openship?

The **`packages/`** directory contains shared libraries that multiple applications import. For example, [`packages/ui/src/index.tsx`](https://github.com/oblien/openship/blob/main/packages/ui/src/index.tsx) exports reusable React components, while `packages/core/` provides shared business logic. This structure prevents code duplication across the web, API, and desktop applications.