Monorepo Guide

Document Purpose

This document defines the intended monorepo structure for Tripinger. It explains how applications, shared packages, infrastructure configuration, documentation, and workspace tooling should be organized so the platform can scale without fragmenting into inconsistent project conventions.

Tripinger is planned as a multi-surface platform with a shared backend, multiple frontend applications, common configuration patterns, and repository-level documentation. A monorepo is therefore the preferred repository model because it allows these surfaces to evolve together while keeping shared code, engineering standards, and delivery workflows aligned.

Monorepo Objectives

The Tripinger monorepo should support the following goals:

• Keep all Phase 1 applications inside one repository.
• Make shared types, utilities, and conventions reusable across apps.
• Reduce duplicated tooling and configuration.
• Allow coordinated changes across frontend, backend, infrastructure, and docs.
• Keep app boundaries clear even while code lives in one repository.
• Support fast local development and scalable CI pipelines.
• Preserve a clean path from MVP implementation to a larger platform architecture.

The current documentation already assumes a monorepo-style structure rather than multiple separate repositories. The root README identifies a repository layout with top-level governance files, multiple applications, shared docs, and a dedicated documentation hierarchy for architecture, database, environments, Docker, and DevOps topics.

Why Monorepo for Tripinger

Tripinger is not a single app. It is a platform with several tightly related product surfaces:

• A public web app for travelers
• A backend API platform
• An admin dashboard for internal operations
• A partner portal for supply-side users

These applications share product concepts, domain language, integrations, release timing, and environment rules. The architecture document also defines them as specialized interfaces over one shared product domain and one core backend platform. That makes a monorepo a more natural fit than multiple disconnected repositories.

A monorepo is especially useful here because it helps the team coordinate changes such as:

• Adding a new booking status used by API, admin, partner, and public web flows
• Introducing a new environment variable required across surfaces
• Updating shared auth behavior
• Aligning domain terminology and API contracts
• Evolving build, CI, linting, and deployment workflows centrally

Repository Model

The planned repository model is a single product monorepo with multiple deployable applications and shared packages. It should be organized around clear application ownership while still supporting shared engineering assets.

The current repository direction is documentation-first, so exact folders may still evolve. Even so, the generated README and app-level READMEs already describe a consistent pattern in which apps live under apps/, shared documentation lives under docs/, and platform-wide files remain at the repository root.

Top-Level Structure

The current documentation plan supports a repository shape similar to the following:

tripinger/
├── README.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── .env.example
├── package.json
├── pnpm-workspace.yaml
├── turbo.json
├── tsconfig.base.json
├── apps/
│   ├── api/
│   ├── web/
│   ├── admin/
│   └── partner/
├── packages/
│   ├── config/
│   ├── types/
│   ├── ui/
│   ├── utils/
│   ├── eslint-config/
│   └── tsconfig/
├── docs/
│   ├── ARCHITECTURE.md
│   ├── DATABASE.md
│   ├── DOCKER.md
│   ├── TECH_STACK.md
│   ├── MONOREPO.md
│   ├── ENVIRONMENTS.md
│   ├── DEVOPS.md
│   └── database/
├── docker/
├── scripts/
└── .github/
    └── workflows/

This structure extends the root README’s documented repository layout by adding the expected workspace and shared-package directories needed for an actual monorepo implementation. The app names and core documentation locations are already reflected in the existing generated files.

Application Boundaries

The monorepo currently assumes four first-class applications.

This separation is already reinforced in the architecture document, which defines these surfaces as distinct applications with different responsibilities and user groups. The monorepo should preserve those boundaries even when code is developed together.

Shared Package Strategy

The repository should avoid copying common logic across apps. Instead, shared code should move into dedicated workspace packages with well-defined responsibilities.

Recommended shared packages

These packages are a logical consequence of the documented TypeScript-first stack and multi-app repository model. Shared packages are especially useful where the public web app, admin dashboard, and partner portal all rely on the same underlying API platform and domain vocabulary.

What should not be shared too early

Not everything belongs in packages/. The monorepo should avoid premature abstraction.

Do not aggressively centralize:

• App-specific route definitions
• Product-surface-specific layout components
• Business logic that only one app uses
• Domain code that still changes rapidly and only exists in one surface
• Backend-only logic reused nowhere else

A good rule is to extract shared code only after it is clearly stable and reused by more than one application.

Workspace Tooling

The approved documentation set implies a workspace-driven development model, and the stack baseline treats pnpm workspaces and Turborepo as the intended monorepo tooling direction. The root README also leaves the exact package manager as pending confirmation, but the generated app READMEs already use pnpm in their local setup examples, making it the practical default for the repository plan.

Package manager

pnpm should be the standard package manager for the monorepo because it works well with multi-package repositories, promotes dependency consistency, and handles workspace filtering efficiently. The app setup flows in the current documentation already use commands such as pnpm install, pnpm docker:up, and pnpm --filter <app> dev.

Task orchestration

Turborepo should be used for monorepo task orchestration. It is a strong fit for:

• Parallel builds and tests
• Cache-aware task execution
• Per-app filtering
• Shared pipeline configuration
• Scalable CI behavior as the repository grows

This is especially helpful for a platform where changes may affect only one app sometimes and multiple surfaces at other times.

Workspace Configuration Direction

The repository should include these workspace-level files:

• pnpm-workspace.yaml
• turbo.json
• package.json
• tsconfig.base.json
• .gitignore
• .editorconfig
• .npmrc if required
• root linting and formatting config files once standardized

Example workspace packages declaration

packages:
  - apps/*
  - packages/*

Example root scripts direction

{
  "scripts": {
    "dev": "turbo run dev --parallel",
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "typecheck": "turbo run typecheck",
    "clean": "turbo run clean",
    "docker:up": "docker compose up -d",
    "docker:down": "docker compose down"
  }
}

These script names align with the existing documentation style, which already expects root-level orchestration commands and app-filtered development commands.

App Structure Expectations

Each app should remain internally organized by feature or domain rather than becoming a flat technical dump. The existing app READMEs already describe this direction clearly.

API app

The API should be organized by business domain modules such as auth, users, hotels, vehicles, bookings, payments, reviews, notifications, partners, admin, compliance, and AI. Shared backend concerns should live in central support folders like common/, config/, integrations/, jobs/, and prisma/.

Web app

The public web app should be organized by traveler-facing product domains such as auth, hotels, vehicles, planner, budgets, bookings, reviews, profile, and trips, while reusable UI elements remain in shared component layers.

Admin app

The admin app should be organized by operational workflows such as dashboard, users, partners, hotels, vehicles, bookings, payments, reviews, moderation, compliance, support, and reports.

Partner app

The partner portal should be organized by supplier workflows such as onboarding, profile, listings, availability, pricing, bookings, documents, reviews, analytics, and payouts.

The monorepo should preserve these internal structures rather than flattening all logic into repository-level shared folders.

Cross-App Dependency Rules

A monorepo only stays healthy if dependencies are intentional.

Allowed dependency direction

• Frontend apps may depend on shared packages.
• The API app may depend on shared non-UI packages.
• Shared packages may depend on other lower-level shared packages when justified.
• Documentation and scripts may support all apps.
• Root config should orchestrate but not replace app ownership.

Forbidden or discouraged dependency direction

• One app should not import directly from another app.
• Frontend apps should not depend on backend runtime code.
• Shared packages should not quietly import app-specific implementation details.
• Admin and partner apps should not bypass the API boundary by reading database code directly.
• Public web code should not embed privileged admin assumptions.

A simple rule is: apps communicate through APIs and shared contracts, not through direct code reach-through into each other.

Shared Types and Contracts

Because the same product concepts appear across web, partner, admin, and API surfaces, the repository should centralize stable shared contracts when helpful.

Strong candidates for shared contracts include:

• Common identifiers
• Shared enum-like domain values
• API response wrappers if standardized
• Pagination types
• Filter and sort parameter shapes
• Reusable date, currency, and localization helpers
• Shared validation constants where appropriate

However, DTO ownership should still remain closest to the app or API domain that defines the contract. Shared packages should hold stable cross-surface contracts, not every internal backend implementation detail.

Documentation Placement Rules

The current repository already treats documentation as a first-class concern, with architecture, database, environment, Docker, and app-level guides explicitly mapped in the root README.

The monorepo should preserve a clear documentation hierarchy:

Root-level docs

Use root-level files for project-wide governance and collaboration material:

• README.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md

docs/

Use docs/ for cross-cutting technical documentation:

• architecture
• database
• environments
• DevOps
• Docker
• monorepo rules
• technology stack
• platform-wide standards

App-local docs

Use app-local README.md files and docs/ folders for app-specific guidance:

• local setup
• route structure
• app architecture notes
• feature-specific design docs
• API-specific docs such as auth and API conventions

This matches the structure already described in the root README and the generated app READMEs.

Environment and Configuration Ownership

The monorepo should centralize shared configuration patterns while keeping secrets and app-specific public variables clearly scoped.

Root ownership

The repository root should own:

• .env.example
• shared config documentation
• local Docker-backed infrastructure defaults
• common development scripts

App ownership

Each app should own:

• its own runtime-specific environment variable usage
• its own public-safe config conventions
• its own validation of required variables at startup

This aligns with the current app docs, which reference the root .env.example as the canonical variable source while still defining app-specific frontend variables and API-specific secrets.

Local Development Workflow

The monorepo should support both full-platform development and focused per-app development.

Standard local flow

1. Install workspace dependencies once at the root.
2. Copy .env.example to .env.
3. Start infrastructure services through Docker.
4. Start either all apps together or only the target app.
5. Use workspace filtering for app-specific development.
6. Run shared lint, typecheck, and test commands from the root when validating changes.

Expected command style

pnpm install
cp .env.example .env
pnpm docker:up
pnpm dev

Focused development examples

pnpm --filter api dev
pnpm --filter web dev
pnpm --filter admin dev
pnpm --filter partner dev

These flows are already consistent with the generated application setup guides.

Build and CI Strategy

A monorepo becomes especially valuable when CI can understand which parts of the repository changed.

The repository should aim for:

• Root-managed CI pipelines
• Cache-aware builds and tests
• Filtered execution when only one app or package changes
• Shared typecheck and lint standards
• Independent app build targets
• Cross-app validation for shared package changes

This approach matches the broader platform direction described in the architecture and root docs, which already assume CI/CD automation and independently deployable surfaces.

Deployment Model in a Monorepo

Even though the repository is unified, deployments should remain surface-specific.

A monorepo should not force all apps to release together every time. Instead, it should make coordinated releases possible when needed and independent releases possible when safer.

Ownership and Change Boundaries

To keep the repository maintainable, each major area should have clear ownership:

• apps/api owns backend business logic and integration behavior.
• apps/web owns traveler-facing UX and flows.
• apps/admin owns internal operational UX.
• apps/partner owns supplier workflows.
• packages/* own stable reusable building blocks.
• docs/ owns cross-cutting platform documentation.
• root config files own workspace behavior and engineering standards.

This keeps the monorepo from becoming a shared dumping ground.

Naming and Conventions

The monorepo should adopt naming conventions that are simple and predictable.

Directory naming

• Use lowercase names.
• Use singular app names where already established: api, web, admin, partner.
• Use lowercase hyphenated names for scripts and docs where needed.

Package naming

Recommended internal package naming pattern:

@tripinger/types
@tripinger/utils
@tripinger/config
@tripinger/ui
@tripinger/eslint-config
@tripinger/tsconfig

Script naming

Use consistent root script names such as:

• dev
• build
• test
• lint
• typecheck
• clean
• docker:up
• docker:down

What Belongs Outside the Monorepo

The current documentation scope does not yet include every future system. Some things may remain outside the main repository until justified.

Examples that may stay outside initially:

• one-off data migration utilities not needed long-term
• temporary research prototypes
• infra-only repos if the deployment platform later requires strong separation
• analytics or data-platform projects with very different tooling needs

At the current Phase 1 documentation stage, however, the core product surfaces and their shared code should remain in the same repository.

Risks and Controls

A monorepo improves coordination, but it also creates operational risks if not managed carefully.

Risks

• Blurred ownership across apps
• Over-sharing unstable code
• Slow CI pipelines if everything runs every time
• Hidden coupling between apps
• Inconsistent app-level architecture despite a shared repo
• Root config changes breaking all apps at once

Controls

• Keep app boundaries explicit
• Use shared packages deliberately, not aggressively
• Use filtered tasks and caching in CI
• Require documentation updates when repository structure changes
• Keep env ownership and deployment boundaries clear
• Review cross-app imports carefully

Assumptions

The following assumptions are used in this document:

• Tripinger remains a single monorepo for the Phase 1 application set.
• The four first-class surfaces are apps/web, apps/api, apps/admin, and apps/partner.
• pnpm is the practical workspace package manager baseline in the current docs.
• Turborepo is the intended monorepo task orchestration layer based on the current stack direction.
• Shared packages will be introduced as implementation begins, even though the root README’s current draft structure is still documentation-oriented.

Current Status

This monorepo guide defines the planned repository structure and workspace conventions for Tripinger based on the current generated documentation set. Exact package lists, root scripts, and shared package boundaries should be finalized when repository scaffolding is committed, but the app separation, workspace model, and documentation hierarchy described here should be treated as the baseline direction.