96 lines
4.1 KiB
Markdown
96 lines
4.1 KiB
Markdown
# beenvoice workspace
|
|
|
|
Local development layout for the **beenvoice** product: a freelancer/small-business invoicing platform with a Next.js web app and an Expo mobile companion.
|
|
|
|
```
|
|
beenvoice-meta/
|
|
├── beenvoice-web/ # Web API + dashboard (Next.js 16, tRPC, PostgreSQL)
|
|
├── beenvoice-app/ # Mobile app (Expo, React Native, dev client)
|
|
└── beenvoice.icon/ # iOS app icon asset (icon composer)
|
|
```
|
|
|
|
Each subdirectory is its own git repository. This folder is a convenience layout for working on both clients against one API.
|
|
|
|
| Repo | Remote |
|
|
|------|--------|
|
|
| Web | [git.soconnor.dev/soconnor/beenvoice-web](https://git.soconnor.dev/soconnor/beenvoice-web) |
|
|
| Mobile | [git.soconnor.dev/soconnor/beenvoice-app](https://git.soconnor.dev/soconnor/beenvoice-app) |
|
|
|
|
## Quick start (full stack)
|
|
|
|
```bash
|
|
# 1. API + database
|
|
cd beenvoice-web
|
|
cp .env.example .env.local # edit DATABASE_URL, AUTH_SECRET, etc.
|
|
docker compose -f docker-compose.dev.yml up -d
|
|
bun install && bun run db:push
|
|
bun run dev # http://localhost:3000
|
|
|
|
# 2. Mobile (simulator)
|
|
cd ../beenvoice-app
|
|
cp .env.example .env # EXPO_PUBLIC_API_URL=http://localhost:3000
|
|
bun install
|
|
bun run ios # Metro on :8082, native dev build
|
|
```
|
|
|
|
Physical iPhone: set `EXPO_PUBLIC_API_URL` to your Mac's LAN IP; ensure `beenvoice-web` has `BETTER_AUTH_URL` matching a host the device can reach (trusted origins are derived from `BETTER_AUTH_URL` / `NEXT_PUBLIC_APP_URL`).
|
|
|
|
## Production deploy (Docker)
|
|
|
|
From `beenvoice-web` with `.env` configured (see [beenvoice-web/README.md](./beenvoice-web/README.md#docker-deployment-app--database)):
|
|
|
|
```bash
|
|
cd beenvoice-web
|
|
git pull
|
|
./scripts/docker-deploy.sh # rebuild app image + restart (not docker-compose.dev.yml)
|
|
```
|
|
|
|
Plain `docker compose up -d` without `--build` reuses the existing local image and will not pick up code from `git pull`.
|
|
|
|
## How the pieces connect
|
|
|
|
| Layer | Repo | Transport | Auth |
|
|
|-------|------|-----------|------|
|
|
| Web UI | `beenvoice-web` | tRPC `/api/trpc` (cookies) | better-auth session |
|
|
| Mobile UI | `beenvoice-app` | tRPC `/api/trpc` (cookie header) | better-auth + `@better-auth/expo` → SecureStore |
|
|
| Automation | `beenvoice-web` MCP `/api/mcp` | JSON-RPC | API key (`bv_…`) only |
|
|
| Public invoices | `beenvoice-web` `/i/[token]` | HTTP | unauthenticated token |
|
|
|
|
Mobile imports **tRPC router types** from `beenvoice-web/src/server/api/root` via `tsconfig` path mapping — keep API changes type-checked in both repos.
|
|
|
|
## Documentation map
|
|
|
|
| Doc | Contents |
|
|
|-----|----------|
|
|
| [beenvoice-web/README.md](./beenvoice-web/README.md) | Web setup, Docker deploy, scripts |
|
|
| [beenvoice-web/docs/ARCHITECTURE.md](./beenvoice-web/docs/ARCHITECTURE.md) | Server architecture (dense) |
|
|
| [beenvoice-app/README.md](./beenvoice-app/README.md) | Mobile setup, troubleshooting |
|
|
| [beenvoice-app/docs/ARCHITECTURE.md](./beenvoice-app/docs/ARCHITECTURE.md) | Mobile architecture (dense) |
|
|
| [beenvoice-web/docs/](./beenvoice-web/docs/) | UI guides (forms, tables, breadcrumbs, email) |
|
|
|
|
## Shared domain concepts
|
|
|
|
- **Clients** — billable contacts with optional default hourly rate
|
|
- **Businesses** — sender profiles (logo, address, Resend email config)
|
|
- **Invoices** — draft → sent → paid; line items; PDF + email; public share token
|
|
- **Time entries** — clock in/out; one running timer per user; auto-attach to open invoice
|
|
- **Recurring invoices**, **expenses**, **payments**, **templates** — full web support; mobile covers a core CRUD subset
|
|
|
|
## Environment cheat sheet
|
|
|
|
| Variable | Where | Purpose |
|
|
|----------|-------|---------|
|
|
| `DATABASE_URL` | beenvoice-web | PostgreSQL |
|
|
| `AUTH_SECRET`, `BETTER_AUTH_URL` | beenvoice-web | better-auth |
|
|
| `EXPO_PUBLIC_API_URL` | beenvoice-app | API base for mobile |
|
|
| `DISABLE_SIGNUPS` | beenvoice-web | `true` blocks new registrations |
|
|
| `RESEND_*` | beenvoice-web | Invoice / reset email |
|
|
|
|
## Ports
|
|
|
|
| Service | Default port |
|
|
|---------|----------------|
|
|
| Next.js (beenvoice-web) | 3000 |
|
|
| Postgres (dev compose) | 5432 |
|
|
| Metro (beenvoice-app) | **8082** (intentionally not 8081) |
|