PulseLedger

Financial clarity, elevated.
A premium, frontend-first personal finance experience designed like a real product, not a demo.

---

🚀 Project Overview

PulseLedger is a modern expense intelligence platform that helps users understand, manage, and optimize their money with confidence. It combines elegant UX, role-aware experiences, actionable analytics, and resilient local persistence to deliver a high-fidelity finance product feel.

The mission is simple: transform raw transaction logs into decisions users can trust, while keeping the architecture production-oriented and backend-ready.

✨ Key Features

• Smart Insights: AI-Lite style auto-categorization patterns and spending alerts surface unusual behavior before it becomes a problem.
• Reactive Budgets: Dynamic progress bars and threshold-based warning states update instantly as transactions change.
• Role-Based Experience: Simulated Admin vs User access paths demonstrate permissions, safeguards, and controlled actions.
• Data Portability: One-click CSV Export enables users to take their transaction history anywhere.

🛠️ Tech Stack

• Frontend: React 18, Vite
• Styling: Tailwind CSS (Custom Glassmorphism theme)
• State: Zustand (with LocalStorage Persistence)
• Charts: Recharts (Responsive & Theme-aware)
• Icons: Lucide React

🧭 Project Structure

src
├── App.css
├── App.tsx
├── assets
│   ├── hero.png
│   ├── react.svg
│   └── vite.svg
├── components
│   ├── guide
│   │   └── GuideModal.tsx
│   ├── layout
│   │   ├── AppShell.tsx
│   │   ├── ProtectedRoute.tsx
│   │   ├── RouteFallback.tsx
│   │   └── TopBar.tsx
│   └── ui
│       └── Card.tsx
├── data
│   └── mockData.ts
├── index.css
├── main.tsx
├── pages
│   ├── BudgetsPage.tsx
│   ├── DashboardPage.tsx
│   ├── InsightsPage.tsx
│   ├── LoginPage.tsx
│   ├── NotFoundPage.tsx
│   ├── SettingsPage.tsx
│   └── TransactionsPage.tsx
├── services
│   ├── apiClient.ts
│   ├── authService.ts
│   ├── financeService.ts
│   └── localStorage.ts
├── store
│   ├── authStore.ts
│   ├── financeStore.ts
│   ├── settingsStore.ts
│   └── themeStore.ts
├── types
│   ├── api.ts
│   └── models.ts
└── utils
  ├── export.ts
  ├── formatters.ts
  ├── insights.ts
  ├── permissions.ts
  └── validation.ts

Folder Responsibilities
- components: Reusable UI and layout building blocks (shell, top bar, route wrappers, and shared cards/modals).
- hooks: Reserved for shared custom React hooks and cross-page stateful logic (not present yet in this repo).
- pages: Route-level screens that compose domain logic and UI for each app section.
- store: Zustand state containers and async actions for auth, finance, settings, and theme.
- types: TypeScript contracts for domain models and API request/response shapes.
- utils: Pure helper logic for validation, formatting, permissions, insights, and CSV export.

Key Root Configuration Points
- tailwind.config.js: Tailwind theme/content/dark-mode configuration surface.
- vercel.json: Deployment and routing configuration entry point for Vercel environments.

🧠 Technical Highlights

Derived State (Performance-first budget intelligence)

Budgets are computed as derived state from the transaction array instead of duplicated storage. This means the UI calculates category spend and threshold status on-the-fly from the latest source data, avoiding synchronization bugs and reducing stale state risk.

Benefits:

• Single source of truth for financial data
• Faster and safer updates during add/edit/delete flows
• Better maintainability as business rules evolve

Theme-Awareness (Design system that adapts automatically)

PulseLedger uses CSS variables and theme-driven visual tokens so cards, typography, contrast, and chart accents shift smoothly across Light and Dark modes. SVG and gradient-driven chart surfaces are aligned with these variables to preserve readability, depth, and visual consistency regardless of theme.

Benefits:

• Consistent brand feel across themes
• Improved accessibility through adaptive contrast
• Cleaner theming model with reusable design tokens

📦 Setup Instructions

npm install
npm run dev
npm run build

👤 Author

Yash Agarwal