Contributing

Document Purpose

This document explains how to contribute to the Tripinger project. It covers the workflow for opening issues, creating branches, submitting pull requests, running tests, handling database migrations, and keeping documentation and security in sync with the rest of the monorepo.

Tripinger is currently documentation-led: architecture, database, environment, and DevOps plans are defined ahead of full implementation. Contributions should respect those plans while remaining practical as the codebase grows.

Project Overview

Tripinger is an all-in-one Sri Lankan travel platform that combines:

• Accommodation booking.
• Vehicle rentals (including tuk-tuks, bikes, cars).
• Experiences and activities.
• Food arrangements and reservations.
• AI-powered trip planning and budgeting.
• Reviews and social travel features.
• Partner tools and admin operations.

The monorepo is expected to include:

• apps/api: NestJS + TypeScript backend API, PostgreSQL, Redis, search, payments, AI.
• apps/web: public traveler-facing web app (React + Vite + Tailwind).
• apps/admin: internal admin dashboard for verification, moderation, operations.
• apps/partner: partner portal for hotels, vehicle owners, restaurants, guides, and other suppliers.
• docs/: architecture, database, environments, DevOps, governance (ARCHITECTURE.md, DATABASE.md, ENVIRONMENTS.md, DEVOPS.md, SECURITY.md, CODE_OF_CONDUCT.md).

Understanding this context will help you place your changes in the right part of the system.

Getting Started

Prerequisites

Before contributing, install or ensure access to:

• Node.js LTS.
• The chosen package manager (for example, pnpm; confirm in README.md).
• Docker and Docker Compose for local infrastructure (PostgreSQL, Redis, search).
• A local .env derived from .env.example, with test or sandbox values only.

Repository setup (typical)

git clone REPOSITORY_URL
cd tripinger

# Install dependencies
pnpm install

# Copy environment template
cp .env.example .env

# Start local infrastructure (Docker)
pnpm dockerup

# Start development apps as needed
pnpm --filter api dev
pnpm --filter web dev
pnpm --filter admin dev
pnpm --filter partner dev

Exact command names may change once the monorepo scripts are finalized; always check the root README.md and app-specific READMEs.

Code of Conduct and Security

Before contributing, please read:

• CODE_OF_CONDUCT.md – behaviour expectations, respect, inclusivity, and reporting of conduct issues.
• SECURITY.md – how to report vulnerabilities, handle secrets, and protect sensitive data.

All contributions must adhere to these policies. For security issues, follow the private reporting process described in SECURITY.md rather than opening public issues. [web:569]

Branching and Workflow

Tripinger uses a branch-based workflow aligned with the environment model (local, dev, staging, prod).

Branch types

Typical branches:

• main: production-bound, protected branch.
• dev: integration branch for development environment deployments.
• feature/*: short-lived branches for features, fixes, docs.

Contribution flow

1. Create a feature branch

   git checkout dev
   git pull origin dev
   git checkout -b feature/your-change-name

2. Make changes in the appropriate app or docs.

• Keep code within the relevant domain module (auth, hotels, vehicles, bookings, payments, reviews, planner, notifications).
• Update documentation when you change architecture, database, environments, or DevOps behaviour.

3. Run tests and checks locally (see “Testing and Quality”).

4. Open a pull request (PR) targeting dev.

• Clearly describe what you changed and why.
• Mention database migrations, new env vars, or security-relevant changes explicitly.

5. Respond to review feedback, update your branch, and ensure CI passes before merge.

Types of Contributions

You can contribute in several ways:

• Features: new functionality in web, API, admin, or partner apps (auth flows, booking pages, planner tools, partner dashboards).
• Fixes: bug fixes, performance improvements, and production-issue resolutions.
• Documentation: improvements to docs/* (architecture, database, environments, DevOps, governance).
• Database and migrations: schema improvements, new domain tables, ERD clarifications under docs/database/*.
• Testing and CI: new test cases, test infrastructure, or CI workflow enhancements.

For large or architectural changes, propose an RFC or design note before implementing, referencing docs/ARCHITECTURE.md and docs/DATABASE.md.

Code and Architecture Conventions

Domain-driven structure

The backend and apps are organized by domain, not just by technical layer.

Examples (API):

• apps/api/src/modules/auth – auth and sessions.
• apps/api/src/modules/users – user identity and profiles.
• apps/api/src/modules/hotels, vehicles, experiences – supply.
• apps/api/src/modules/bookings – booking lifecycle.
• apps/api/src/modules/payments, payouts – payment flows.
• apps/api/src/modules/reviews, social – trust and community.
• apps/api/src/modules/planner, budgets – itineraries and budgeting.

When adding functionality:

• Place code in the domain module that owns the data and logic.
• Avoid cross-domain coupling; use shared services or utilities only for truly common concerns.

Technology stack

Align with the documented stack:

• Frontend: React + Vite + TypeScript + Tailwind.
• Backend: Node.js + NestJS + TypeScript.
• Database: PostgreSQL + Prisma (migrations).
• Cache/search/media: Redis, Elasticsearch/OpenSearch, S3/Cloudinary.
• External services: PayHere, Stripe, SendGrid, Twilio, OpenAI, Mapbox, etc.

Major deviations (for example, new frameworks) should be discussed and approved before implementation.

Database and Migration Responsibilities

Tripinger’s database architecture and migration docs set clear expectations for schema changes.

Migration rules

If your work affects the database:

• Version every schema change

• Use Prisma migrations for all structural changes (tables, columns, indexes, constraints, enums).

• Do not manually modify production databases.

• Align schema with application code

• Ensure migrations and code changes ship together.

• Maintain backward compatibility where deployments are staged.

• Prefer additive, safe changes

• Avoid dropping tables/columns without staged plans and backfills.

• Use history tables and soft migrations for lifecycle-critical data (bookings, payments, partner verification).

Contributor steps for DB changes

• Edit schema.prisma as needed.
• Generate and apply migrations locally (prisma migrate dev).
• Ensure CI can apply migrations via prisma migrate diff and prisma migrate deploy.
• Update ERDs and domain docs under docs/database/* to match new schemas.
• Mention migrations and any backfill scripts explicitly in your PR description.

Environment and Secrets

Environments and secret handling are documented in ENVIRONMENTS.md, DOCKER.md, DEVOPS.md, and SECURITY.md. Contributors must follow these rules.

Environment variables

When adding an env var:

• Add a placeholder and brief description to .env.example.
• Reference it in relevant app READMEs (API/admin/partner/web) if needed.
• Do not commit real secrets; use provider dashboards and CI secret stores.

Examples:

• Backend: DATABASE_URL, REDIS_URL, ELASTICSEARCH_NODE, JWT_ACCESS_SECRET, JWT_REFRESH_SECRET.
• Integrations: PAYHERE_MERCHANT_ID, PAYHERE_SECRET, STRIPE_SECRET_KEY, SENDGRID_API_KEY, MAPBOX_ACCESS_TOKEN, OPENAI_API_KEY.
• Frontend: VITE_WEB_API_BASE_URL, VITE_ADMIN_API_BASE_URL, VITE_PARTNER_API_BASE_URL.

Environment separation

• Do not copy production data to dev or local environments.
• Use masked or synthetic data outside production.
• Ensure configuration for dev/staging/prod matches the environment matrix in ENVIRONMENTS.md.

Testing and Quality

Testing is critical, especially for auth, booking, payments, partner onboarding, and admin operations.

Minimum expectations per PR

Depending on the change, you should:

• Run unit tests for affected services, guards, and utilities.

• Run integration tests for updated APIs.

• Run e2e tests for critical flows if your changes touch them:

• User registration/login.

• Hotel search and booking.

• Vehicle listing search and booking.

• Payment intent and webhook handling.

• Partner login and listing updates.

• Admin verification and moderation actions.

• Planner session and itinerary creation.

• Verify frontend changes in web/admin/partner apps:

• Routing and guards.

• Forms, validation, and error states.

• Tables, filters, and dashboards.

CI integration

GitHub Actions runs CI workflows that typically:

• Install dependencies.
• Validate Prisma migrations (migrate diff, migrate deploy).
• Run test suites (unit, integration, e2e).
• Build apps to catch compile errors.

Your PR should pass CI without new failures. If CI fails, check logs, fix issues, and push updates to your branch.

Issues and Pull Requests

Opening issues

When reporting a bug or proposing a feature:

• Check existing issues to avoid duplicates. [web:588][web:590]
• Include:
• A clear title and description.
• Steps to reproduce (for bugs).
• Expected vs actual behaviour.
• Environment details (local, dev, staging, prod).
• Any relevant logs or screenshots (redacted for sensitive data).

Security vulnerabilities should not be reported via public issues—use SECURITY.md guidance instead. [web:569]

Creating pull requests

When opening a PR:

• Use a descriptive title (for example, “Add booking status history and Prisma migration”).

• Link to any related issue or design note.

• Explain your changes, including:

• Functional impact.

• Database/migration changes.

• New env vars or provider integrations.

• Testing performed (list test suites or manual checks).

• Keep PRs focused; avoid mixing unrelated changes. [web:588]

• Allow maintainer edits on the branch if possible (for minor fixes).

Security-Sensitive Contributions

If your work touches sensitive areas (auth, payments, partner verification, KYC documents, admin actions, audit logs):

• Follow the guidance in SECURITY.md.
• Avoid logging personal or financial data.
• Use provider references rather than raw payment instrument data.
• Implement strict authorization checks and least-privilege access.
• Coordinate with maintainers for review and deployment planning.

Large Changes and Architecture Evolution

For major changes (new domains, significant refactors, new providers):

1. Draft a short design note or RFC:

• Problem and goals.
• Proposed solution and alternatives.
• Impact on architecture, database, migrations, environments, and CI/CD.

2. Share it in the project planning channel or via an issue labeled as a design proposal.

3. Incorporate feedback, update relevant docs, and then begin implementation.

This keeps Tripinger aligned with its documented architecture while allowing the system to evolve deliberately.

Attribution and Status

This CONTRIBUTING.md is part of Tripinger’s Phase 1 governance foundation. It is designed to work alongside:

• CODE_OF_CONDUCT.md for behaviour.
• SECURITY.md for vulnerability reporting and data protection.
• docs/ARCHITECTURE.md, docs/DATABASE.md, docs/ENVIRONMENTS.md, and docs/DEVOPS.md for technical direction.

As implementation decisions and teams evolve, this document may be updated to refine workflows and expectations. Contributors are responsible for staying informed of the current version and following its guidance.