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

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 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 explicitly declares the monorepo boundaries:

packages:
  - 'apps/*'
  - 'packages/*'

Additional configuration files include 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, a React component responsible for generating Open Graph images. The API layer entry point is located at 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 – The entry point for the shared UI component library
• packages/core/src/apps/README.md – Documentation for core application utilities

These packages typically contain:

• .ts and .tsx source files
• 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 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, 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 – A TypeScript automation script used by CI pipelines to manage versioning and deployments
• 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 – 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:

# 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:

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:

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, pnpm-workspace.yaml, and 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 and individual Dockerfile definitions provide containerized deployment options
• Automation scripts in 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 exports reusable React components, while packages/core/ provides shared business logic. This structure prevents code duplication across the web, API, and desktop applications.

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