Project management that helps teams learn and improve
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.
| Scope | Result |
|---|---|
| Audit | Full baseline across Categories 1-7 |
| Implementation | Fixes shipped across type safety, performance, tests, runtime handling, and accessibility |
| Outcome | All 7 categories now meet the submission target in the packaged verification docs |
High-signal results:
- Type safety:
26.87%reduction by upstream/master grep recount and29.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 msand65 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.
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.
Ship has four main views, each designed for different questions:
| View | What it answers |
|---|---|
| Docs | "Where's that document?" — Wiki-style pages for team knowledge |
| Issues | "What needs to be done?" — Track tasks, bugs, and features |
| Projects | "What are we building?" — Group issues into deliverables |
| Teams | "Who's doing what?" — See workload across people and weeks |
- Create documents for anything your team needs to remember — meeting notes, specs, onboarding guides
- Create issues for work that needs to get done — assign them to people and track progress
- Group issues into projects to organize related work
- 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.
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
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.
- Plan (Weekly Plan) — Before the week, write down what you intend to accomplish and why
- Execute (The Week) — Do the work; issues track what was actually done
- 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.
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.
# 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 devOnce it's running, open your browser to:
Log in with the demo account:
- Email:
[email protected] - Password:
admin123
| Service | URL | Description |
|---|---|---|
| Web app | http://localhost:5173 | The Ship interface |
| API server | http://localhost:3000 | Backend services |
| Swagger UI | http://localhost:3000/api/docs | Interactive API documentation |
| OpenAPI spec | http://localhost:3000/api/openapi.json | OpenAPI 3.0 specification |
| PostgreSQL | localhost:5432 | Database (via Docker) |
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 testsShip 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
| Layer | Technology |
|---|---|
| Frontend | React, Vite, TailwindCSS |
| Editor | TipTap + Yjs (real-time collaboration) |
| Backend | Express, Node.js |
| Database | PostgreSQL |
| Real-time | WebSocket |
- Everything is a document — Single
documentstable with adocument_typefield - 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.tsShip uses Playwright for end-to-end testing with 73+ tests covering all major functionality.
Ship supports multiple deployment patterns:
| Environment | Recommended Approach |
|---|---|
| Development | Local with Docker Compose |
| Staging | AWS Elastic Beanstalk |
| Production | AWS GovCloud with Terraform |
# 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| Variable | Description | Default |
|---|---|---|
DATABASE_URL |
PostgreSQL connection string | Required |
SESSION_SECRET |
Cookie signing secret | Required |
PORT |
API server port | 3000 |
- 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
- 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