EZ Wallet

EZ Wallet is a personal "data wallet" for AI chats. You keep sensitive context (your writing style, project notes, health info) in a PIN-locked, encrypted vault of cards, attach a card only when a prompt needs it, and send it to Google Gemini through a proxy that stores no prompts or replies.

It's a FastAPI backend with a Next.js frontend, using PostgreSQL (Neon) or SQLite.

---

1. Prerequisites

Tool	Version	Check with
Python	3.11 or newer (tested on 3.11, 3.12, 3.13)	python3 --version
Node.js	20 or newer (comes with npm)	node --version
git	any	git --version

You don't need Docker, a database server, or any API keys. Ports 8000 (backend) and 3000 (frontend) must be free.

---

2. Run it

Use two terminals. Start the backend first.

Terminal 1: backend (http://localhost:8000)

macOS / Linux

git clone https://github.com/sugabubba7/ezwallet.git
cd ezwallet/backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --port 8000

Windows (PowerShell)

git clone https://github.com/sugabubba7/ezwallet.git
cd ezwallet\backend
py -3 -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn app.main:app --port 8000

Wait for Application startup complete., then check it from any other terminal:

curl http://localhost:8000/healthz

It should return {"status":"ok"}.

Terminal 2: frontend (http://localhost:3000)

cd ezwallet/frontend
npm install
npm run dev

Open http://localhost:3000. Register a new account, or log in with the grading account:

Username	Password	Vault PIN
NYUgrader	Courant2026!	2026

On the login screen, type the username into the "Email or username" box. The PIN unlocks the wallet cards on the dashboard (click the eye icon).

---

3. Environment

File	In git?	What's in it
backend/.env	✅ committed on purpose	The working config for grading: the throwaway database made for this assignment, the course's grading login, and non-secret settings. Nothing in it protects anything real
backend/.env.example	✅	Every variable the backend reads, with an explanation of each
backend/.env.local	❌ git-ignored	Created automatically on first run. Holds the two real secrets (JWT_SECRET, WALLET_ENCRYPTION_KEY), plus any personal keys you add (Gemini, Google)
frontend/.env.local.example	✅	Optional frontend settings. The frontend needs no env file to run locally

Which secrets matter, and why they're handled differently:

• Database URL: a throwaway database created only for this assignment, so it's committed as the brief asks.
• JWT_SECRET and WALLET_ENCRYPTION_KEY: real secrets, so they are never committed. The backend generates them on first start and saves them to backend/.env.local, and later restarts reuse them. There's nothing to copy by hand.
• Personal API keys (Gemini, Google OAuth): these are my accounts, so they aren't in the repo. The app runs fine without them:
  • Gemini: without a key, the "Ask Gemini" box returns a clear 503 message. To enable it, add GEMINI_API_KEY=... to backend/.env.local.
  • Google sign-in: the button shows "(not configured)". To enable it, add GOOGLE_CLIENT_ID=... to backend/.env.local and NEXT_PUBLIC_GOOGLE_CLIENT_ID=... to frontend/.env.local.

Priority order: real environment variables > backend/.env.local > backend/.env.

---

4. Anything weird (read this if something fails)

• Start the backend before the frontend. The frontend forwards every /api/* request to http://127.0.0.1:8000.
• Migrations run automatically when the backend starts (Alembic upgrade head). There's no separate migrate command. You'll see Running upgrade … -> 0003 the first time.
• Seeding is automatic, too. On startup, the NYUgrader account is created if it doesn't exist. Every new account gets 3 sample wallet cards and 5 sample chat summaries, so the dashboard isn't empty.
• First start writes backend/.env.local. Don't delete it: it holds the key that decrypts wallet cards.
• "Address already in use" / wrong app answering on port 8000: check curl http://localhost:8000/healthz. If the reply isn't exactly {"status":"ok"}, another program owns the port. Find it with lsof -i :8000 (macOS/Linux) and stop it.
• macOS zsh: copy commands without trailing # comments. By default zsh passes them as arguments.
• Reset all local data (only when using SQLite): stop the backend and delete backend/wallet.db*.

---

5. API

JSON in, JSON out. Protected routes take Authorization: Bearer <token>. Every error has the shape {"detail": "message"}.

The assignment's endpoints

Method	Path	Auth	Request body	Success	Errors
GET	/healthz	no	none	200 {"status":"ok"}	none
POST	/api/auth/register	no	{"email"?, "username"?, "password", "pin"?} (email or username required)	201 {token, access_token, token_type, user}	400 invalid input · 409 email/username taken
POST	/api/auth/login	no	{"email" | "username", "password"}	200 {token, access_token, token_type, user}	400 · 401 wrong credentials
GET	/api/auth/me	yes	none	200 user	401
GET	/api/users/:id	yes	none	200 user	401 · 404 not yours
PATCH	/api/users/:id	yes	any of {"email", "username", "password", "current_password"}	200 user	400 · 401 · 404 not yours · 409 taken
DELETE	/api/users/:id	yes	none	200 {"message": "User deleted"}	401 · 404 not yours

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗