twotalesanimation
173 lines
4.0 KiB
Markdown
173 lines
4.0 KiB
Markdown
# xBid — VFX Quoting & Bidding SaaS
|
|
|
|
A professional full-stack VFX quoting application built with **Next.js 15**, **TypeScript**, **Tailwind CSS v4**, **Prisma ORM**, and **PostgreSQL**.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Clients** — manage client companies with full contact and billing info
|
|
- **Jobs / Quotes** — versioned quote documents with status workflow (Draft ? Sent ? Approved/Rejected)
|
|
- **Shots** — VFX shot breakdown with complexity multipliers and drag-and-drop reordering
|
|
- **Assets** — CG asset budget tracking (characters, environments, vehicles, etc.)
|
|
- **Line Items** — per-task cost rows with hours/days/artists/rates, markup, discount, tax
|
|
- **Rate Cards** — studio rate card library organized by department
|
|
- **PDF Export** — professional quote PDF with front page + detailed appendix
|
|
- **Decimal Precision** — all financials use `decimal.js` (no floating-point drift)
|
|
|
|
---
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|---|---|
|
|
| Framework | Next.js 15 (App Router, Server Actions) |
|
|
| Language | TypeScript |
|
|
| Styling | Tailwind CSS v4 + shadcn/ui |
|
|
| ORM | Prisma 7 + PostgreSQL 16 |
|
|
| Forms | React Hook Form + Zod |
|
|
| Drag & Drop | @dnd-kit/core + @dnd-kit/sortable |
|
|
| Finance Math | decimal.js |
|
|
| Notifications | sonner |
|
|
| PDF | HTML render via `/api/pdf/[id]` |
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 20+
|
|
- PostgreSQL 16 (or Docker)
|
|
- npm 10+
|
|
- `ts-node` for seeding: `npm install -g ts-node typescript`
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### 1. Clone & install
|
|
|
|
```bash
|
|
git clone <repo-url>
|
|
cd xBid
|
|
npm install
|
|
```
|
|
|
|
### 2. Configure environment
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env`:
|
|
|
|
```env
|
|
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/xbid"
|
|
NEXTAUTH_SECRET="your-random-secret-here"
|
|
NEXTAUTH_URL="http://localhost:3000"
|
|
```
|
|
|
|
### 3. Start PostgreSQL
|
|
|
|
**Option A — Docker (recommended):**
|
|
|
|
```bash
|
|
docker compose up -d postgres
|
|
```
|
|
|
|
**Option B — local PostgreSQL:**
|
|
|
|
```sql
|
|
CREATE DATABASE xbid;
|
|
```
|
|
|
|
### 4. Run database migrations
|
|
|
|
```bash
|
|
npm run db:generate # generate Prisma client
|
|
npm run db:migrate # run migrations (enter "init" as migration name)
|
|
```
|
|
|
|
### 5. Seed sample data
|
|
|
|
```bash
|
|
npm run db:seed
|
|
```
|
|
|
|
This creates 15 rate cards, 2 sample clients, 2 jobs with shots, assets, and line items.
|
|
|
|
### 6. Start development server
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Open http://localhost:3000
|
|
|
|
---
|
|
|
|
## Production (Docker)
|
|
|
|
```bash
|
|
docker compose up --build -d
|
|
```
|
|
|
|
After first run, apply migrations:
|
|
|
|
```bash
|
|
docker compose exec app npx prisma migrate deploy
|
|
docker compose exec app npx prisma db seed
|
|
```
|
|
|
|
---
|
|
|
|
## PDF Export
|
|
|
|
Navigate to any job and click **Download PDF**. The route at `/api/pdf/[id]` generates HTML with:
|
|
- **Front page**: client info, project details, shot/asset summary, financial totals, T&C
|
|
- **Appendix**: full per-shot and per-asset line item breakdown
|
|
|
|
Print to PDF via browser (Ctrl+P ? Save as PDF).
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
app/ Next.js App Router pages
|
|
api/pdf/[id]/ PDF generation endpoint
|
|
clients/ Client management
|
|
jobs/ Job management
|
|
rate-cards/ Rate card management
|
|
actions/ Server actions (CRUD)
|
|
components/
|
|
assets/ Asset editor
|
|
clients/ Client form & table
|
|
dashboard/ Stats & recent jobs
|
|
jobs/ Job form, table, detail, totals
|
|
layout/ Sidebar navigation
|
|
line-items/ Line item table & dialog
|
|
rate-cards/ Rate card management
|
|
shots/ Shot editor
|
|
ui/ shadcn/ui components
|
|
lib/
|
|
calculations.ts Decimal.js financial math
|
|
constants.ts Domain constants & defaults
|
|
prisma.ts Prisma client singleton
|
|
validations.ts Zod schemas
|
|
prisma/
|
|
schema.prisma Full database schema
|
|
seed.ts Sample data seeder
|
|
```
|
|
|
|
---
|
|
|
|
## Database Scripts
|
|
|
|
```bash
|
|
npm run db:generate # npx prisma generate
|
|
npm run db:migrate # npx prisma migrate dev
|
|
npm run db:seed # ts-node prisma/seed.ts
|
|
npm run db:studio # npx prisma studio (DB GUI at :5555)
|
|
```
|