A personal dashboard for tracking fuel receipts and costs.
Stack: Next.js (App Router), Appwrite Cloud (Auth, Storage, Databases, Functions, Sites), OpenAI (vision parsing), shadcn/ui, Recharts.
- 📤 Multi-image upload (receipts) to Appwrite Storage
- ⚙️ Appwrite Function auto-parses receipts (OpenAI), writes structured logs
- 📊 Dashboard: price/L over time, spend by month/year, summary cards
- 🚗 Multi-car management with owner-scoped CRUD
- 📦 Export tools: filtered CSV + receipt ZIP archive
- 🔎 OCR issue workflows: failed/duplicate queue, retry, replace, merge/keep
- 🔐 Only pre-created Appwrite users can sign in
- 🧩 Monorepo-friendly: Next.js site + Functions in one repository
- 🚀 Git-based auto deploys
- Appwrite Function (from Git)
- Next.js on Appwrite Sites (from Git)
This README matches your current layout and uses Git deploys without tarballs.
repo-root/
├─ Upright/
│ └─ functions/
│ └─ extract-fuel-data/ # Appwrite Function (Git-deployed)
│ ├─ package.json
│ └─ src/
│ └─ main.js # Entrypoint for the function
├─ src/
│ └─ app/ # Next.js app (App Router)
│ ├─ page.tsx
│ ├─ dashboard/
│ └─ ... components, api, etc.
├─ public/
├─ package.json
├─ README.md
└─ .gitignore
You can keep this exact structure. Appwrite lets you set a root directory per product:
- Function root:
Upright/functions/extract-fuel-data(entrypoint:src/main.js)- Site root: repository root (since your Next.js lives at repo root)
If you later prefer a cleaner monorepo, consider:
repo-root/
├─ apps/
│ └─ web/ # Next.js site
└─ functions/
└─ extract-fuel-data/ # Appwrite Function
(Then set Site Root = apps/web, Function Root = functions/extract-fuel-data.)
pnpm install
pnpm dev # Next.js at http://localhost:3000Create .env.local at the repo root (or at apps/web if you move the site later), and fill with values below.
Create .env.local in the site root (here: repo root):
NEXT_PUBLIC_APPWRITE_ENDPOINT=...
NEXT_PUBLIC_APPWRITE_PROJECT_ID=...
NEXT_PUBLIC_DB_ID=...
NEXT_PUBLIC_CARS_ID=...
NEXT_PUBLIC_FUELLOGS_ID=...
NEXT_PUBLIC_RECEIPTS_BUCKET=...
# Server-only (used by /api routes):
OPENAI_API_KEY=...
OPENAI_MODEL=gpt-5-mini
In Appwrite → Sites → [Your Site] → Settings → Variables, mirror these for production.
Use Appwrite → Functions → [extract-fuel-data] → Settings → Variables to add:
DB_ID=...
COLLECTION_ID=...
BUCKET_ID=...
OPENAI_API_KEY=...
OPENAI_MODEL=gpt-5-mini
APPWRITE_ENDPOINT=...
APPWRITE_PROJECT_ID=...
APPWRITE_API_KEY=...
APPWRITE_DB_ID=...
APPWRITE_CARS_COLLECTION_ID=...
APPWRITE_FUELLOGS_COLLECTION_ID=...
APPWRITE_OCR_JOBS_COLLECTION_ID=...
APPWRITE_RECEIPTS_BUCKET_ID=...
APPWRITE_OCR_FUNCTION_ID=...
NEXT_PUBLIC_OCR_JOBS_ID=...
- Appwrite Console → Functions → create/select extract-fuel-data.
- Git settings → Connect repository → select this repo + branch.
- Root directory:
Upright/functions/extract-fuel-data - Entrypoint:
src/main.js - Save. Push to the configured branch to build and (if configured) auto-activate the new deployment.
For manual uploads (not needed here), you would upload a
code.tar.gz, but Git deploys never require a tarball.
- Appwrite Console → Sites → Create site → Connect repository.
- Choose this repo + branch.
- Root directory: repo root (empty field) since your Next.js is at the top level.
- Framework: Next.js.
- Build settings (default are fine):
- Install:
npm install(orpnpm i) - Build:
npm run build(orpnpm build) - Output:
./.next
- Install:
- Add the required Site Variables (same names as .env).
- Deploy. Subsequent pushes to the branch will auto-create and activate a new deployment.
- Trigger: set file-create event for your receipts bucket, e.g.
buckets.{YOUR_BUCKET_ID}.files.*.create - File permissions: when uploading from the site, set
Permission.read(Role.users())so the client app can preview. - Document permissions: when the function writes FuelLogs, add
Permission.read(Role.users())(andupdateif you want editing).
Create an OCR_JOBS collection with fields:
ownerUserId(string, required)carId(string, required)receiptFileId(string, required)receiptSha256(string, optional)status(string, required)attemptCount(integer, required)errorMessage(string, optional)parsedPayload(string, optional)fuelLogId(string, optional)duplicateOfFuelLogId(string, optional)supersededByJobId(string, optional)lastRequestId(string, optional)
Recommended indexes:
(ownerUserId, status, $createdAt)receiptFileIdreceiptSha256
Run this once after adding the new ownerUserId/receiptFileIds fields:
node scripts/backfill-owner.mjsDefaults:
- owner user:
68efbd48002488e79301 - fallback car:
Audi A4
Add (or keep) these in .gitignore:
# env & secrets
.env
*.env
*.env.local
**/.env
**/.env.local
# Appwrite descriptors (if you export secrets — avoid committing)
appwrite.json
# builds & caches
.next/
out/
dist/
node_modules/
*.log
# OS/IDE
.DS_Store
Thumbs.db
.vscode/*
!.vscode/extensions.json
MIT