Skip to content

README.md

Latest commit

 

History

History
80 lines (65 loc) · 2.57 KB

README.md

File metadata and controls

80 lines (65 loc) · 2.57 KB
Raw

💸 Ledger - Decoupled Personal Expense Tracker Architecture

A high-performance, minimal personal finance dashboard split into decoupled client/ and server/ packages.

📁 Monorepo Folder Structure

expense-tracker/
├── client/                     # Next.js 15 Frontend Application
│   ├── app/                    # Next.js App Router (Dashboard, Analytics, Categories, Transactions, Settings, Profile)
│   ├── components/             # Reusable UI & Layout Components (Dock Sidebar, Navbar, Modals)
│   ├── features/               # Domain feature modules (Dashboard, Expenses, Analytics, Categories, Profile)
│   ├── lib/
│   │   ├── api/api-client.ts   # Decoupled API Client (supports NEXT_PUBLIC_API_URL)
│   │   ├── auth/auth-context.ts# Pluggable Auth Context (login, OAuth, logout slots)
│   │   ├── config/app-config.ts# Configurable Backend Connection Modes (LOCAL_PRISMA vs REMOTE_HTTP)
│   ├── package.json
│   └── tsconfig.json
│
├── server/                     # Standalone Express & Database Server
│   ├── src/                    # Backend API Controllers & Route Handlers
│   ├── prisma/                 # Prisma PostgreSQL Schema & Database Seed Scripts
│   ├── package.json
│   ├── tsconfig.json
│   └── .env
│
└── package.json                # Root Monorepo Scripts

🔌 How to Plug In Your Backend & Database

Option A: Plug Your Custom API Server into server/

  1. Place your backend API code inside server/src/.
  2. Configure environment variables in server/.env: 
    PORT=5000
DATABASE_URL="postgresql://user:password@localhost:5432/ledger?schema=public"
CORS_ORIGIN="http://localhost:3000"
  3. In client/.env, point the frontend API client to your backend server: 
    NEXT_PUBLIC_BACKEND_MODE="REMOTE_HTTP"
NEXT_PUBLIC_API_URL="http://localhost:5000/api/v1"

Option B: Run Next.js App Router + Prisma PostgreSQL locally in client/

  1. Set DATABASE_URL in client/.env.
  2. Run database migrations: 
    cd client
npx prisma db push

🚀 Quick Start (Local Development)

1. Install Dependencies

# Install client dependencies
cd client && npm install

# Install server dependencies
cd ../server && npm install

2. Run Applications

# From the root directory:

# Start Next.js Frontend (Runs on http://localhost:3000)
npm run dev:client

# Start Express Backend Server (Runs on http://localhost:5000)
npm run dev:server