# beenvoice

Beenvoice is a freelancer and small-business invoicing platform with a Next.js web application/API and an Expo mobile companion. The repository is a Bun workspace orchestrated by Turborepo.

## Workspace map

```text
beenvoice/
├── apps/
│   ├── web/             # Next.js dashboard, tRPC API, PostgreSQL/Drizzle
│   ├── mobile/          # Expo Router mobile app and iOS widgets
│   └── worker/          # PostgreSQL-backed scheduler and background jobs
├── packages/
│   ├── domain/          # Platform-neutral shared rules and parsing
│   └── email/           # Resend and SMTP/Mailpit delivery adapter
├── Dockerfile
├── docker-compose*.yml
├── package.json
└── turbo.json
```

The mobile app consumes the same tRPC API and Better Auth sessions as the web app. It imports the server router type at compile time, while runtime-safe shared behavior lives in `@beenvoice/domain`.

## Quick start

```bash
bun install

cp apps/web/.env.example apps/web/.env.local
cp apps/mobile/.env.example apps/mobile/.env

bun run --filter @beenvoice/web docker:up
bun run --filter @beenvoice/web db:push
bun run dev
```

`bun run dev` starts Next.js on port 3000, Expo Metro on port 8082, and the background worker. For a physical iPhone, set `EXPO_PUBLIC_API_URL` in `apps/mobile/.env` to a host the device can reach and configure the web app's canonical/auth URLs consistently.

Useful workspace commands:

```bash
bun run typecheck
bun run lint
bun run test
bun run build
bun run check
bun run email:preview    # sends a PDF-bearing message to local Mailpit
```

Run an app-specific command with a workspace filter:

```bash
bun run --filter @beenvoice/web db:migrate
bun run --filter @beenvoice/mobile ios
bun run --filter @beenvoice/mobile ios:release:upload
```

## Production Docker deployment

Keep production web configuration in `apps/web/.env`, then run from the repository root:

```bash
git pull
./scripts/docker-deploy.sh
```

The root Dockerfile installs the frozen Bun workspace lockfile and exposes separate `final` (web) and `worker` targets. The Compose stack starts both; the web container runs migrations before serving requests and the worker tolerates that short startup race.

## Documentation

- [Web setup](./apps/web/README.md)
- [Web architecture](./apps/web/docs/ARCHITECTURE.md)
- [Mobile setup](./apps/mobile/README.md)
- [Mobile architecture](./apps/mobile/docs/ARCHITECTURE.md)
- [Worker architecture](./apps/worker/README.md)
- [Shared domain package](./packages/domain/README.md)
- [Email delivery package](./packages/email/README.md)

## Product concepts

- Clients with optional default hourly rates
- Businesses and sender branding
- Draft, sent, paid, and overdue invoices
- Time tracking and invoice attachment
- Recurring invoices, expenses, payments, and templates
- Public invoice links and API-key-authenticated automation