Cowat _{^{/ko.wat/ — a pun on the French « covoit » (short for covoiturage)}}

Note

Carpooling management platform for organizations — connecting drivers and passengers within a shared workspace.

Cowat is a full-stack TypeScript web application that lets organizations coordinate daily commutes. Drivers post their routes and available seats; passengers request bookings. Admins manage users, monitor activity, and configure notification channels all within a multi-tenant, role-based workspace.

---

Features

For users

• Commute posting Drivers create one-way or round-trip commutes with customizable stops, departure times, and available seats
• Commute templates Save recurring routes as templates to speed up daily commute creation
• Booking requests Passengers request a spot on a commute; drivers accept or decline
• Location management Save and reuse personal pickup/dropoff locations
• Notification preferences Choose how and when to receive updates (email, Slack)

For managers

• Organization management Create and manage organizations, invite users by email
• User management View, create, update, and ban users within an organization
• Stats dashboard Monitor commute activity and usage over time
• Slack integration Configure org-level Slack channels for automated notifications

Platform

• Multi-tenancy Full organization isolation with role-based access control (admin, user)
• Internationalization English and French supported throughout the UI and emails
• OpenAPI Auto-generated API documentation available in development

---

Tech stack

Layer	Technology
Framework	TanStack Start + TanStack Router
UI	React 19, Tailwind CSS 4, shadcn/ui
Data fetching	TanStack Query
Forms	React Hook Form + Zod
State	Zustand
API	oRPC (TypeScript RPC with OpenAPI support)
ORM	Prisma
Auth	Better Auth
Database	PostgreSQL
Storage	MinIO (S3-compatible)
Emails	React Email + Resend
Notifications	Slack Bolt + jsx-slack
i18n	i18next
Unit tests	Vitest
E2E tests	Playwright
Component dev	Storybook
Runtime	Node.js >= 24

---

Requirements

• Node.js >= 24
• pnpm
• Docker (runs PostgreSQL + MinIO locally)

---

Getting started

1. Clone and install

git clone <repo-url>
cd cowat
pnpm install

2. Configure environment

cp .env.example .env

Key variables to review (defaults work out-of-the-box with Docker):

Variable	Description
DATABASE_URL	PostgreSQL connection string
AUTH_SECRET	Secret key for session signing change in production
EMAIL_SERVER	SMTP server (defaults to maildev for local dev)
RESEND_API_KEY	Resend API key (required in production)
S3_*	MinIO/S3 credentials for file uploads

Note

Do not change EMAIL_SERVER for local development the default points to the maildev container which catches all outgoing emails.

3. Start services and initialize the database

pnpm dk:init   # Start Docker (PostgreSQL + MinIO)
pnpm db:init   # Push schema + seed initial data

4. Run the development server

pnpm dev

The application is available at http://localhost:3000.

Note

No Docker? Set up a PostgreSQL database manually and update DATABASE_URL, then run pnpm db:push && pnpm db:seed.

---

IDE setup

VS Code

cp .vscode/settings.example.json .vscode/settings.json

Zed

cp .zed/settings.example.json .zed/settings.json

---

Development reference

Scripts

Development

Command	Description
pnpm dev	Start the dev server (app + SMTP watcher)
pnpm storybook	Open Storybook component explorer at localhost:6006

Database

Command	Description
pnpm dk:init	Initialize Docker services (first time)
pnpm dk:start	Start Docker services
pnpm dk:stop	Stop Docker services
pnpm dk:clear	Remove Docker volumes (destructive)
pnpm db:init	Push schema + seed data
pnpm db:push	Sync Prisma schema to the database
pnpm db:seed	Seed the database
pnpm db:reset	Full reset (destructive)
pnpm db:seed:week	Re-seed commutes for the current week
pnpm db:ui	Open Prisma Studio

Code quality

Command	Description
pnpm lint	Run all linters (oxlint + TypeScript)
pnpm format	Format code with oxfmt

Code generation

Command	Description
pnpm gen:prisma	Regenerate Prisma client
pnpm gen:icons	Generate icon components from SVG sources
pnpm gen:build-info	Generate build metadata

---

Email development

All emails are intercepted locally by maildev.

• Maildev UI: http://localhost:1080
• Preview a template: http://localhost:3000/api/dev/email/{template}
  • Example: http://localhost:3000/api/dev/email/login-code
• Preview in a specific language: append ?language=fr (or en)
• Pass props to a template: append ?propName=value as query parameters

Email templates are built with React Email and live in src/emails/templates/.

---

API documentation

OpenAPI documentation is auto-generated from oRPC router definitions and accessible at:

http://localhost:3000/api/openapi/app

---

Custom icons

Place SVG files in src/components/icons/svg-sources/ and run:

pnpm gen:icons

Warning

SVG files must be named with the icon- prefix (e.g. icon-external-link.svg), be square, and use #000 as the fill color (it will be replaced with currentColor).

---

Environment indicator

Display a labeled banner in non-production environments by setting:

VITE_ENV_NAME="staging"
VITE_ENV_EMOJI="🔬"
VITE_ENV_COLOR="teal"

---

Testing

Unit tests

pnpm test       # Run tests in headless mode
pnpm test:ui    # Open interactive test UI

End-to-end tests

E2E tests use Playwright. A summary of all test scenarios is available in the repository.

pnpm e2e        # Run all tests headlessly (CI mode)
pnpm e2e:setup  # Generate auth context (required once, and after DB changes)
pnpm e2e:ui     # Open Playwright UI to run and debug specific tests

Warning

The generated E2E context files contain authentication state. Re-run pnpm e2e:setup after any local database changes. This step runs automatically in CI.

---

Production

pnpm install
pnpm build
pnpm start

Optionally build Storybook to expose it at /storybook:

pnpm storybook:build
pnpm build
pnpm start

---

Project structure

src/
├── app/                  # Client-side app entry, providers, global styles
├── components/           # Shared UI components and icons
├── emails/               # React Email templates
├── features/             # Feature modules (auth, commute, booking, …)
│   ├── account/
│   ├── auth/
│   ├── booking/
│   ├── build-info/
│   ├── commute/
│   ├── commute-request/
│   ├── commute-template/
│   ├── dashboard/
│   ├── devtools/
│   ├── location/
│   ├── notification/
│   ├── organization/
│   ├── push/
│   ├── slack/
│   ├── stats/
│   └── user/
├── locales/              # i18n translation files (en, fr)
├── routes/               # TanStack Router file-based routes
│   ├── api/              # Server API routes (RPC, REST, uploads, dev tools)
│   ├── app/              # User-facing routes (/app/$orgSlug/…)
│   ├── invitations/      # Invitation acceptance flow
│   ├── login/            # Auth / login pages
│   └── manager/          # Manager routes (/manager/$orgSlug/…)
├── server/
│   ├── db/               # Prisma client + middleware (soft-delete)
│   └── routers/          # oRPC procedure definitions
└── utils/                # Shared utilities and helpers