Top-Level Directories in the Openship Repository: Complete Monorepo Guide

The Openship monorepo organizes its codebase into six top-level directories—apps/, docker/, docs/, packages/, .github/, and .claude/—that separate front-end applications, infrastructure configuration, documentation, shared libraries, CI/CD automation, and AI tooling metadata.

Openship is an open-source shipping platform built as a modular monorepo. Understanding the top-level directories in the Openship repository allows developers to navigate the codebase efficiently, whether they are customizing the web dashboard, modifying Docker deployments, or contributing to shared packages.

Directory Structure Overview

The repository root contains six distinct folders that enforce a clear separation of concerns:

• apps/ – Front-end applications including the web dashboard and optional email server
• docker/ – Docker Compose files defining the self-hosted stack
• docs/ – User documentation, screenshots, and architecture diagrams
• packages/ – Reusable TypeScript libraries and shared services
• .github/ – GitHub workflows, issue templates, and contribution guidelines
• .claude/ – Internal metadata for Claude AI tooling (non-runtime)

apps/

The apps/ directory houses the client-facing applications. The primary application resides in apps/web/, which contains the Next.js dashboard defined in [apps/web/package.json](https://github.com/oblien/openship/blob/main/apps/web/package.json). This is where the main user interface code lives, including the configuration at apps/web/next.config.mjs.

docker/

Infrastructure definitions live in the docker/ folder. The [docker/docker-compose.yml](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml) file orchestrates the complete self-hosted stack, including PostgreSQL, Redis, API services, and the edge gateway. This directory controls how the platform deploys in containerized environments.

docs/

User-facing and contributor documentation occupies the docs/ directory. Files like [docs/installation.md](https://github.com/oblien/openship/blob/main/docs/installation.md) provide deployment guides, while subdirectories contain screenshots and architecture diagrams that explain the platform's design.

packages/

Shared libraries reside in packages/, implementing the monorepo's reusable components. The UI component library entry point is at [packages/ui/src/index.tsx](https://github.com/oblien/openship/blob/main/packages/ui/src/index.tsx), alongside database utilities and onboarding flows. These packages are imported across multiple applications to maintain consistency.

.github/

Automation and community files are stored in .github/. The [.github/workflows/ci.yml](https://github.com/oblien/openship/blob/main/.github/workflows/ci.yml) defines continuous integration pipelines, while issue templates and contribution guidelines help manage the open-source workflow.

.claude/

This directory contains metadata for AI-assisted development tooling. Files like [.claude/skills/openship-config/SKILL.md](https://github.com/oblien/openship/blob/main/.claude/skills/openship-config/SKILL.md) configure Claude-specific features and are not part of the runtime application code.

Navigating the Codebase

Use these command-line operations to explore the top-level directories:

# List all top-level directories

ls -d */               

# Output: apps/  docs/  docker/  packages/  .github/  .claude/

To run the web dashboard locally:

cd apps/web
npm install            # Install UI dependencies

npm run dev            # Start Next.js dev server at http://localhost:3000

To deploy the full self-hosted stack:

cd docker
docker compose up -d   # Starts postgres, redis, api, dashboard, edge

To build shared packages:

cd packages/ui
npm install
npm run build          # Produces compiled UI library in ./dist

Key Configuration Files

Several critical files work alongside the top-level directories to define the monorepo structure:

• [package.json](https://github.com/oblien/openship/blob/main/package.json) – Root npm workspace definition listing all monorepo packages
• [pnpm-workspace.yaml](https://github.com/oblien/openship/blob/main/pnpm-workspace.yaml) – Declares workspace layout for pnpm package management
• [docker/docker-compose.yml](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml) – Core orchestration file for the self-hosted stack
• apps/web/next.config.mjs – Next.js configuration for the web dashboard
• [packages/ui/src/index.tsx](https://github.com/oblien/openship/blob/main/packages/ui/src/index.tsx) – Entry point for the reusable UI component library

Summary

• The Openship repository organizes code into six top-level directories that separate applications, infrastructure, documentation, libraries, automation, and tooling.
• The apps/ directory contains the Next.js web dashboard and optional server components.
• docker/ holds the Docker Compose configuration required for self-hosted deployments.
• packages/ stores shared TypeScript libraries including UI components and database utilities.
• .github/ manages CI/CD pipelines and community contribution workflows.
• docs/ provides user guides and architectural documentation.
• .claude/ contains AI-specific metadata not used in production runtime.

Frequently Asked Questions

What is the purpose of the packages/ directory in Openship?

The packages/ directory stores reusable TypeScript libraries shared across the monorepo. According to the Openship source code, this includes UI components (entry at packages/ui/src/index.tsx), database utilities, and onboarding flows that multiple applications import to maintain consistency and reduce code duplication.

How do I start the Openship development environment?

Navigate to apps/web/ and run npm install followed by npm run dev to start the Next.js development server on localhost:3000. For the complete stack including database and API services, change to the docker/ directory and execute docker compose up -d to orchestrate all containers.

Where are the Docker configuration files located in the Openship repository?

All Docker-related files reside in the docker/ top-level directory. The primary configuration is [docker/docker-compose.yml](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml), which defines services for PostgreSQL, Redis, the API layer, dashboard, and edge components required for self-hosting.

What is stored in the .claude/ directory?

The .claude/ directory contains internal metadata used by Claude AI tooling for assisted development. As implemented in oblien/openship, files like .claude/skills/openship-config/SKILL.md configure AI-specific features and are not part of the production runtime or application logic.

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