Spendwise Project Guide

Tech Stack

• •Frontend: React 18 + Vite 5
• •Styling: Tailwind CSS 3 + custom utility classes
• •UI: lucide-react icons, Recharts, AG Grid Community
• •Backend: Express JSON API + server/db.json persistence
• •Utils: date-fns, uuid, clsx, tailwind-merge

Project Structure

spendwise-app/
├── src/
│   ├── components/          # UI components
│   │   ├── DashboardFilters.jsx
│   │   ├── ErrorBoundary.jsx
│   │   ├── ExpensePieChart.jsx
│   │   ├── Header.jsx
│   │   ├── Modal.jsx
│   │   ├── Sidebar.jsx      # Mobile-responsive
│   │   ├── SpendingTrend.jsx
│   │   ├── Toast.jsx        # Error notifications
│   │   └── TransactionForm.jsx
│   ├── context/
│   │   └── FinanceContext.jsx  # Global state + API sync
│   ├── lib/                    # Shared utilities
│   │   ├── utils.js            # cn() helper
│   │   ├── formatters.js       # Currency/date formatting
│   │   └── helpers.js          # Category filtering, validation
│   ├── pages/
│   │   ├── Dashboard.jsx
│   │   ├── Transactions.jsx
│   │   └── Categories.jsx
│   ├── App.jsx
│   ├── main.jsx
│   └── index.css               # Tailwind + custom utilities
├── server/
│   ├── index.js                # Express API with validation
│   └── db.json                 # Local data store
├── index.html
├── tailwind.config.js
└── vite.config.js

Frontend Patterns (React)

State & Data

• •Use FinanceContext for shared state and derived data
• •Key state: transactions, categories, dateRange, selectedCategoryIds
• •Derived data (memoized): filteredTransactions, categoryMap, expenseCategories, periodSpending, totalSpending
• •Status flags: isLoading, isSaving, error
• •All CRUD operations use useCallback for stable references

Utilities (src/lib/)

• •utils.js: cn() for merging Tailwind classes
• •formatters.js: formatCurrency(), formatDollars(), formatDate(), toInputDate()
• •helpers.js: getExpenseCategories(), isExpense(), isValidColor(), sanitizeColor()

Styling

• •Prefer Tailwind classes; use glass-card and mesh-gradient utilities
• •Use Manrope for display and body text
• •Primary color: #009485, background: #0a0b10
• •Use cn() from src/lib/utils.js for conditional classes

Error Handling

• •ErrorBoundary wraps app for crash recovery
• •Toast component shows save errors
• •Forms show inline validation errors
• •Loading states during fetch/save operations

Routing

• •react-router-dom with Sidebar as persistent navigation
• •Pages live in src/pages and should be self-contained
• •Mobile sidebar uses hamburger menu

Backend Patterns (Express)

API Endpoints

Validation

• •UUIDs validated with regex
• •Strings sanitized (HTML stripped, length limited)
• •Types enforced (expense/income)
• •Amounts must be non-negative numbers
• •Colors must be valid hex format

Data Storage

• •Data stored in server/db.json
• •Writes use atomic temp-file + rename pattern
• •Write queue prevents race conditions

Quick Commands

npm run dev       # Vite dev server
npm run server    # Express API (nodemon)
npm run start:all # Run both
npm run build     # Production build
npm run lint      # ESLint

Rules

1. •Keep UI in React components; avoid direct DOM manipulation
2. •Use Tailwind for layout and theming; keep glassmorphic feel
3. •Use utilities from src/lib/ instead of duplicating code
4. •Keep API contract stable (/api/data, /api/save)
5. •Avoid new dependencies unless clearly justified
6. •All interactive elements need focus states and ARIA attributes

Related Skills

• •ui-patterns: Tailwind + UI consistency
• •quality-checklist: Pre-commit verification

Related Docs

• •README.md: Setup and overview
• •ARCHITECTURE.md: Detailed technical documentation