Project management that helps teams learn and improve

Audit and Improvement Snapshot

This fork was used for a full 7-category audit, targeted fixes, and reproducible before/after verification. The work was completed in roughly one focused day.

High-signal results:

• Type safety: 26.87% reduction by upstream/master grep recount and 29.37% reduction by syntax-aware AST recount
• Bundle size: main entry chunk 2073.74 kB -> 970.30 kB
• API search latency: P95 72 ms -> 28 ms and 65 ms -> 6 ms
• Database query efficiency: slowest measured search query 2.860 ms -> 1.181 ms
• Accessibility: critical/serious axe violations cleared on /login, /issues, /team/allocation, /docs, and /programs

Detailed evidence lives in docs/submission/presearch-codex.md, docs/submission/final-narrative.md, and docs/submission/verification-record.md.

What is Ship?

Ship is a project management tool that combines documentation, issue tracking, and plan-driven weekly workflows 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.

How to Use Ship

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

The Basics

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. Write weekly plans to declare what you intend to accomplish each week

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

The Ship Philosophy

Everything is a Document

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 weeks are documents too — they can contain notes, decisions, and context

Plans Are the Unit of Intent

Ship is plan-driven: each week starts with a written plan declaring what you intend to accomplish and ends with a retro capturing what you learned. Issues are a trailing indicator of what was done, not a leading indicator of what to do.

1. Plan (Weekly Plan) — Before the week, write down what you intend to accomplish and why
2. Execute (The Week) — Do the work; issues track what was actually done
3. Reflect (Weekly Retro) — After the week, 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.

Learning, Not Compliance

Documentation requirements in Ship are visible but not blocking. You can start a new week 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.

Getting Started

Prerequisites

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

Setup

# 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
cp web/.env.example web/.env

# 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

Open the App

Once it's running, open your browser to:

http://localhost:5173

Log in with the demo account:

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

What's Running

Common Commands

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

Technical Details

Architecture

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

Tech Stack

Design Decisions

• 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.

Repository Structure

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

Testing

# 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.

Deployment

Ship supports multiple deployment patterns:

Docker

# 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

Environment Variables

Security

• 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.

Accessibility

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

Contributing

We welcome contributions. See CONTRIBUTING.md for guidelines.

Documentation

• Application Architecture — Tech stack and design decisions
• Unified Document Model — Data model and sync architecture
• Document Model Conventions — Terminology and patterns
• Week Documentation Philosophy — Why weekly plans and retros work the way they do
• Accountability Philosophy — How Ship enforces accountability
• Accountability Manager Guide — Using approval workflows
• Contributing Guidelines — How to contribute
• Security Policy — Vulnerability reporting

License

MIT License