Finora

Spend Smarter. Save More.

A personal finance tracker and financial intelligence platform. Tracks income, expenses, budgets and saving goals, and turns that data into rule-based (non-AI) insights, forecasts and a financial health score — per the spec in requirements/Finora — Complete Project Specification & Development Plan.md.

This README is written so a new developer can go from a fresh clone to a fully running app, end to end, without asking anyone anything. Follow it top to bottom the first time; use the table of contents to jump back in later.

Table of contents

1. Tech stack
2. Prerequisites
3. Quick start
4. Step-by-step setup
5. Seeded accounts
6. Project structure
7. Available scripts
8. Why some things are built this way
9. The admin dashboard
10. Deployment
11. What's implemented
12. Troubleshooting

Tech stack

• apps/client — Next.js 16 (App Router), TypeScript, Tailwind CSS v4, Better Auth (email/password + Google OAuth, JWT plugin, admin plugin), TanStack Query, React Hook Form + Zod, Recharts.
• apps/server — NestJS 11, TypeScript, REST, Prisma. Verifies requests via Better Auth's JWT/JWKS (it does not own login itself); exposes an admin-only module for site health/traffic stats.
• apps/mobile — Expo (React Native + Expo Router), TypeScript. Foundation phase: auth (email/password + Google, via @better-auth/expo) and a dashboard summary screen, sharing the same backend as the web app. See apps/mobile — more screens are being added incrementally.
• packages/database — the shared Prisma schema (Postgres, hosted on Neon), used by both apps/client and apps/server.
• packages/types, packages/validation — shared enums and Zod schemas, kept independent of @finora/database so the Prisma/Node runtime never ends up in a browser (or Expo) bundle.
• packages/utils — currency (৳ BDT, South Asian digit grouping) and date helpers, shared by all three apps.

Prerequisites

Install these before touching the repo:

• Node.js ≥ 20 (developed and tested on 22.x — node -v to check).
• pnpm 10.x, via Corepack (bundled with Node):

  corepack enable
  corepack prepare [email protected] --activate
  

• Git.
• A free Neon account (hosted Postgres — no local Postgres install needed).
• (Optional, for Google sign-in) a Google Cloud Console project with an OAuth client — see step 8 below.
• (Optional, for the mobile app) the Expo Go app on your phone, or an Android/iOS emulator set up via Android Studio / Xcode.

No local Postgres, no Docker, no global CLI installs beyond pnpm — everything else is a workspace dependency.

Quick start (tl;dr)

For someone who's done this before and just wants the commands:

git clone <this-repo-url> finora && cd finora
corepack enable && corepack prepare [email protected] --activate
pnpm install

# create packages/database/.env, apps/server/.env, apps/client/.env.local
# (see "Environment files" below for exact contents)

pnpm --filter @finora/database exec prisma migrate dev
pnpm --filter @finora/database run seed
pnpm dev

Then open http://localhost:3000 and log in as [email protected] / Pa$$w0rd (seeded), or register your own account. If any of that is unclear, read the full walkthrough below.

Step-by-step setup

1. Clone and install tooling

git clone <this-repo-url> finora
cd finora
corepack enable
corepack prepare [email protected] --activate

This repo pins packageManager: [email protected] in package.json — Corepack reads that and makes sure everyone on the team uses the exact same pnpm version, so pnpm install produces the same lockfile result for everyone.

2. Provision Postgres

Create a free Neon project and copy its connection string (Neon shows it on the project dashboard, looks like postgresql://user:password@host/db?sslmode=require). This is the only external service you need an account for to run the app locally.

3. Environment files

Next.js, Prisma, and Expo each read their own env file — there's no shared root .env that all three consume automatically. Copy each .env.example below and fill in real values:

cp packages/database/.env.example packages/database/.env
cp apps/server/.env.example apps/server/.env
cp apps/client/.env.example apps/client/.env.local
cp apps/mobile/.env.example apps/mobile/.env      # only needed if you're running the mobile app

File	Variables	Notes
packages/database/.env	DATABASE_URL	Same Neon connection string everywhere.
apps/server/.env	DATABASE_URL, PORT, WEB_APP_URL, BETTER_AUTH_URL	PORT defaults to 4000 locally.
apps/client/.env.local	DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL, NEXT_PUBLIC_API_URL, GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET	The last two are optional — see step 8.
apps/mobile/.env	EXPO_PUBLIC_AUTH_URL, EXPO_PUBLIC_API_URL	Only needed to run the mobile app (step 9).

Generate a BETTER_AUTH_SECRET:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Paste the result into apps/client/.env.local. Leave GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET blank for now — the app runs fully on email/password without them, and step 8 covers turning Google sign-in on later.

4. Install dependencies

pnpm install

This is the beginning of the README. Read the rest at the original. Read the full README ↗