Buck Web Application
🌟 Overview
Buck is a modern, high-performance web application designed to help users take full control of their personal finances. Combining an intuitive, responsive frontend with machine learning forecasting models and real-time backend synchronization, Buck delivers actionable spending insights, multi-wallet management, goal tracking, and AI financial advisory services.
🛠️ Technology Stack
| Layer | Technologies |
|---|
| Frontend Framework | Next.js 15 (App Router), React 19, TypeScript |
| Motion & Animations | Framer Motion (GPU-accelerated springs, path tracing, scroll linking) |
| Styling & Design System | Modern Vanilla CSS, CSS Variables, Theme Tokens (Dark & Light mode support) |
| Authentication & Database | Supabase (SSR Client, Row-Level Security, PostgreSQL) |
| AI Engine | Buck_AI/: Python FastAPI on Google Gemini Flash. AI Financial Advisor (live), AI Forecaster (planned) |
| Icons & Media | React Icons (FontAwesome, HeroIcons) |
✨ Key Features & UI/UX Design System
1. Unified Header & Topbar Scroll Indicators
- Traditional Scrollbar Concealment: Native operating system scrollbars are concealed across scroll containers (
scrollbar-width: none;, ::-webkit-scrollbar { display: none; }) for a clean, distraction-free aesthetic.
- Landing Page Header: When scrolled, the header morphs into frosted glass (
backdrop-filter: blur(18px)) while a warm gold/orange gradient progress indicator sweeps smoothly across the header's bottom border.
- Dashboard Topbar: Dynamically tracks inner dashboard content scrolling using Framer Motion
useScroll({ container: mainRef }) and useSpring.
- Unified Border Integration: The scroll track functions directly as the header's crisp
2px bottom border line, preventing jagged step mismatches or double-line rendering artifacts.
2. Interactive Modal Perimeter Scroll Glow
- Dynamic
<ScrollGlowModalCard>: For scrollable documents (e.g. Terms of Use, Privacy Policy), a dynamic SVG border <motion.rect pathLength={smoothProgress}> illuminates around the perimeter of the dialog as the user scrolls.
- Content-Aware Scroll Detection: Uses a
ResizeObserver to evaluate whether content exceeds viewport boundaries, applying the SVG glow strictly when scrollable.
- Desktop Bounds: Modals are strictly bounded (
width: min(880px, 100%), max-height min(82dvh, 760px)) to ensure optimal readability across widescreen displays.
- Isolated Static Dialogs: Compact popups (e.g. Contact Us confirmation modal at
maxWidth: 420px) maintain isolated static card layouts.
3. Comprehensive Financial Management
- Multi-Wallet Budgeting: Manage multiple accounts (Cash, Bank, Credit Card, Savings) with dedicated budget limits and active wallet selection.
- Expense Categorization: Instant logging with auto-categorization powered by AI embeddings.
- Financial Goals & Multipliers: Set savings goals with Normal, Moderate, or Aggressive pace profiles.
- Expense Forecasting: Time-series spending projections adapting to historical trends and lifestyle adjustments.
- AI Financial Advisor: Contextual financial tips, spending analysis, and actionable budgeting recommendations.
- Admin Dashboard: Platform monitoring, database cache inspection, and maintenance tools.
🚀 Getting Started
Prerequisites
- Node.js: v18.18.0 or higher
- npm / pnpm / yarn
1. Clone the Repository
git clone https://github.com/Scorch879/Buck-Web-Application.git
cd Buck-Web-Application/buck
2. Install Dependencies
npm install
3. Configure Environment Variables
Create a .env.local file inside the buck/ directory:
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
4. Run the Development Server
npm run dev
Open http://localhost:3000 in your browser.
5. Production Build
npm run build
npm run start
📚 Documentation
Start at docs/README.md. It maps every document and says which one answers what.
