MoneyWrapped

Problem Statement

Bank statements are dense, boring, and intimidating — people rarely understand their own spending. Spotify Wrapped proved that the same raw data becomes irresistible when it's turned into a personal, narrative, shareable story. There was no equivalent for money, especially one that understands Nigerian bank statement formats (Moniepoint, OPay, GTBank) and currency.

Proposed Solution

MoneyWrapped is "Spotify Wrapped for your finances." Upload a bank statement (CSV or PDF), and an AI pipeline turns it into a swipeable, animated, year-in-review story: spending personality, daily burn rate, top recipients, who you transfer to most, financial health score, category breakdowns, and shareable cards.

Full Solution Details

Frontend story screens (each a distinct animated "slide"): overview, spending breakdown, spender personality, daily burn rate, top recipient, transfers-to-people / "your people" stats, financial health, financial challenge, and a final financial report — plus a delightful fun-fact stack shown while analysis is pending, and graceful pending/failed/success states.

Backend pipeline: file upload (multer) → parse CSV (csv-parser) or PDF (pdf-parse / pdfdataextract) → create an async analysis job → run AI categorization/insights (OpenAI) → persist results. Includes user accounts, an admin surface, tier config (usage tiers), rate limiting, and DB migrations with a runner.

Technical Documentation

Frontend — React + TypeScript on Feature-Sliced Design; each feature (analysis, analysis-result) decomposes into parts/ → screens/ → components/ with barrel exports, Framer Motion for the slide animations, TanStack Query for server state, and the author's Meemaw library. The result feature explicitly models the three lifecycle states (analysis-pending with a fun-fact stack, analysis-success with ~12 story screens, analysis-failed).

Backend — Node + Express + TypeScript + MongoDB (Mongoose), layered as configs → controllers (analysis/file/user/admin) → middlewares (auth, upload, rate-limit, validate) → models (user, file, analysisJob) → routes. Security via helmet, CORS, JWT + bcrypt, express-validator, express-rate-limit; node-cache for caching; module-alias for path aliases; Winston logging; a migrations runner; and mocks for offline/dev. The analysisJob model decouples slow AI/parsing work from the request, so uploads return immediately and the frontend polls for completion.

Tech Stack

React, TypeScript, Framer Motion, TanStack Query, Meemaw (frontend); Node.js, Express, TypeScript, MongoDB/Mongoose, OpenAI, multer, csv-parser, pdf-parse/pdfdataextract, JWT, bcrypt, helmet, express-rate-limit, node-cache, Winston (backend).

System Design

Upload statement (CSV/PDF) ─multer─► File controller
        │
        ▼
  Parse: csv-parser  OR  pdf-parse / pdfdataextract
        │
        ▼
  Create analysisJob (async)  ──► OpenAI categorization + insights
        │                                  │
        ▼                                  ▼
  MongoDB (users, files, jobs)      story data (personality, burn rate,
        ▲                                   top recipients, health, ...)
        │ poll status
Frontend: pending(fun-facts) → success(12 animated screens) → share

Smart Architectural Decisions

• Async job model. Parsing a PDF and calling an LLM is slow; the analysisJob decouples it from the upload request so the UI never blocks — the frontend's pending/fun-fact screen turns that latency into delight instead of dead time.
• Multi-format, Nigeria-aware ingestion. Supporting both CSV and PDF (two PDF extractors as fallback) and Moniepoint/OPay/GTBank formats tackles the messiest part of the problem — real, inconsistent bank exports.
• Story-as-architecture on the frontend. Modeling each insight as its own screen/part under explicit pending/success/failed states makes the "Wrapped" narrative maintainable and easy to extend with new slides.
• Productionized backend: helmet/CORS/rate-limit/validation, tiered usage, an admin surface, and a migrations runner show this was built to actually run, not just demo.

Impacts

Turns intimidating bank statements into a shareable, AI-generated financial story tuned for Nigerian banks — combining a genuinely fun frontend with a production-grade async backend.

Demonstrated Skills

Full-stack TypeScript; document parsing (CSV + PDF, multi-extractor fallback); async job pipelines decoupling slow AI work; LLM-driven categorization/insights; data storytelling + motion design (Framer Motion, multi-screen narrative); Feature-Sliced Design; backend security/ops (helmet, rate limiting, tiers, migrations, admin).