# Top-Level Directories in the Openship Repository: Complete Monorepo Guide > Explore the top-level directories in the Openship monorepo: apps, docker, docs, packages, .github, and .claude. Understand this complete monorepo guide for efficient code organization. - Repository: [oblien/openship](https://github.com/oblien/openship) - Tags: deep-dive - Published: 2026-07-31 --- **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)](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`](https://github.com/oblien/openship/blob/main/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)](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)](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)](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)](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)](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: ```bash # List all top-level directories ls -d */ # Output: apps/ docs/ docker/ packages/ .github/ .claude/ ``` To run the web dashboard locally: ```bash 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: ```bash cd docker docker compose up -d # Starts postgres, redis, api, dashboard, edge ``` To build shared packages: ```bash 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)](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)](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)](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml)** – Core orchestration file for the self-hosted stack - **[`apps/web/next.config.mjs`](https://github.com/oblien/openship/blob/main/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)](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`](https://github.com/oblien/openship/blob/main/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)](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`](https://github.com/oblien/openship/blob/main/.claude/skills/openship-config/SKILL.md) configure AI-specific features and are not part of the production runtime or application logic.