Ship logo

Project management that helps teams learn and improve

License PRs Welcome Section 508 Compliant WCAG 2.1 AA

Ship is a project management tool that combines documentation, issue tracking, and sprint planning in one place. Instead of switching between a wiki, a task tracker, and a spreadsheet, everything lives together.

Built by the U.S. Department of the Treasury for government teams, but useful for any organization that wants to work more effectively.

Ship has four main views, each designed for different questions:

1. Create documents for anything your team needs to remember — meeting notes, specs, onboarding guides
2. Create issues for work that needs to get done — assign them to people and track progress
3. Group issues into projects to organize related work
4. Plan sprints to decide what to work on in the next two weeks

Everyone on the team can edit documents at the same time. You'll see other people's cursors as they type.

In Ship, there's no difference between a "wiki page" and an "issue" at the data level. They're all documents with different properties. This means:

• You can link any document to any other document
• Issues can have rich content, not just a title and description
• Projects and sprints are documents too — they can contain notes, decisions, and context

Ship treats each sprint as an experiment:

1. Hypothesis (Sprint Plan) — Before the sprint, write down what you plan to do and what you expect to happen
2. Experiment (The Sprint) — Do the work
3. Conclusion (Sprint Retro) — After the sprint, write down what actually happened and what you learned

This isn't paperwork for paperwork's sake. Teams that skip retrospectives repeat the same mistakes. Teams that write things down learn and improve.

Documentation requirements in Ship are visible but not blocking. You can start a new sprint without finishing the last retro. But the system makes missing documentation obvious — it shows up as a visual indicator that escalates from yellow to red over time.

The goal isn't to check boxes. It's to capture what your team learned so you can get better.

• Node.js 20 or newer
• pnpm (npm install -g pnpm)
• Docker (for the database)

# 1. Clone the repository
git clone https://github.com/US-Department-of-the-Treasury/ship.git
cd ship
# 2. Install dependencies
pnpm install
# 3. Configure environment
cp api/.env.example api/.env.local
# 4. Start the database
docker-compose up -d
# 5. Create sample data
pnpm db:seed
# 6. Run database migrations
pnpm db:migrate
# 7. Start the application
pnpm dev

Once it's running, open your browser to:

http://localhost:5173

Log in with the demo account:

• Email: dev@ship.local
• Password: admin123

pnpm dev # Start everything
pnpm dev:web # Start just the web app
pnpm dev:api # Start just the API
pnpm db:seed # Reset database with sample data
pnpm db:migrate # Run database migrations
pnpm test # Run tests

Ship is a monorepo with three packages:

• web/ — React frontend with TipTap editor for real-time collaboration
• api/ — Express backend with WebSocket support
• shared/ — TypeScript types used by both

• Everything is a document — Single documents table with a document_type field
• Server is truth — Offline-tolerant, syncs when reconnected
• Boring technology — Well-understood tools over cutting-edge experiments
• E2E testing — 73+ Playwright tests covering real user flows

See docs/application-architecture.md for more.

ship/
├── api/ # Express backend
│ ├── src/
│ │ ├── routes/ # REST endpoints
│ │ ├── collaboration/ # WebSocket + Yjs sync
│ │ └── db/ # Database queries
│ └── package.json
│
├── web/ # React frontend
│ ├── src/
│ │ ├── components/ # UI components
│ │ ├── pages/ # Route pages
│ │ └── hooks/ # Custom hooks
│ └── package.json
│
├── shared/ # Shared TypeScript types
├── e2e/ # Playwright E2E tests
└── docs/ # Architecture documentation

# Run all E2E tests
pnpm test
# Run tests with UI
pnpm test:ui
# Run specific test file
pnpm test e2e/documents.spec.ts

Ship uses Playwright for end-to-end testing with 73+ tests covering all major functionality.

Ship supports multiple deployment patterns:

# Build production images
docker build -t ship-api ./api
docker build -t ship-web ./web
# Run with Docker Compose
docker-compose -f docker-compose.prod.yml up

• No external telemetry — No Sentry, PostHog, or third-party analytics
• No external CDN — All assets served from your infrastructure
• Session timeout — 15-minute idle timeout (government standard)
• Audit logging — Track all document operations

Reporting Vulnerabilities: See SECURITY.md for our vulnerability disclosure policy.

Ship is Section 508 compliant and meets WCAG 2.1 AA standards:

• All color contrasts meet 4.5:1 minimum
• Full keyboard navigation
• Screen reader support
• Visible focus indicators

We welcome contributions. See CONTRIBUTING.md for guidelines.

• Application Architecture — Tech stack and design decisions
• Unified Document Model — Data model and sync architecture
• Document Model Conventions — Terminology and patterns
• Sprint Documentation Philosophy — Why sprints work the way they do
• Contributing Guidelines — How to contribute
• Security Policy — Vulnerability reporting

MIT License