BudgetGenius Hexagonal Architecture and PWA Approach

Iridescent ripples of a bright blue and pink liquid

🧠 Project Overview

Goal: Allow users to easily manage their personal finances from any device, visualizing key metrics and spending patterns. Current Features:

Google sign-up and login (OAuth2). Dashboard with a monthly summary. Breakdown of expenses by category. Transaction management (create, edit, delete). Responsive UX with support for app installation (PWA). Interactive charts for visual insights.

🏗️ Architecture: Hexagonal (Ports & Adapters)

We applied the hexagonal architecture pattern to decouple domains from infrastructure and prepare the code for scalability and testing.

graph LR
  A["Controllers (Adapters)"] --> B[Application Services]
  B --> C["Domain (Entities, Use Cases)"]
  B --> D["Ports (Interfaces)"]
  D --> E["Repositories (Adapters)"]
  D --> F["External APIs (Google, Redis)"]
  E --> G[PostgreSQL]

This structure allows us to:

Easily test business rules (pure domain). Change providers without altering core logic. Adapt the backend to other frontends (mobile, CLI, etc.).

🧰 Technologies Used

🔙 Backend (NestJS + TypeORM) NestJS as a scalable framework with support for testing and dependency injection. TypeORM + PostgreSQL for ORM and relational database. Redis for caching (tokens, sessions). Passport.js + OAuth2 for Google authentication. JWT for access and refresh tokens. Hexagonal architecture to separate domain, application, and infrastructure.

🎨 Frontend (React + TailwindCSS)

React with Hooks and Context for lightweight state management. TailwindCSS for a modern and responsive UI. Recharts for interactive charts (pie, bar, etc.). localStorage for token persistence (PWA-ready). React Router DOM for declarative navigation.

📦 Infraestructura y despliegue

Firebase Hosting for frontend + PWA + automatic HTTPS. Render.com for the backend with externally connected PostgreSQL and Redis. Google Cloud Console for OAuth2 configuration. CORS, CSRF, and environment-controlled security.

🌐 Navegación de usuario y flujos

🧭 General Navigation Flow

graph LR
  A[Login con Google] --> B[Callback Backend]
  B --> C[Generar Tokens]
  C --> D[Redirige al Front con tokens]
  D --> E[Guardar tokens en localStorage]
  E --> F[Dashboard]
  F --> G[Consulta de gastos]
  F --> H[Crear/editar transacción]
  F --> I[Ver breakdown de categorías]

🧪 Key Use Cases

graph LR
  A[Usuario autenticado] --> B[GET /overview]
  A --> C[GET /categories]
  A --> D[POST /transaction]
  A --> E[PUT /transaction/:id]
  A --> F[DELETE /transaction/:id]

🔐 Key Technical Decisions

✅ 1. Passwordless OAuth Users created via Google have no password (null) and are authenticated solely via OAuth. This is managed without affecting authorization flows or persistence.

✅ 2. JWT + localStorage for PWA Migrated from httpOnly cookies to localStorage to enable BudgetGenius’s use as a Progressive Web App. This also facilitates offline functionality and background retries.

✅ 3. Firebase Hosting for Frontend Leverages PWA, HTTPS, telemetry, redirects, and more. Replaced Vercel to centralize on a platform offering better browser integration.

📊 Charts and Data Visualization

An ExpenseCategories component was included with real-time visualization of:

Total expenses Most expensive category Percentage distribution with colors and tooltips These metrics come from a single overviewService.getBreakdownByCategory() service, reused across multiple views, adhering to the DRY principle.

📈 Current Outcome

✔️ Functional MVP deployed

✔️ Users can authenticate and use the app

✔️ Complete Infrastructure: DB, backend, frontend, and OAuth

✔️ Solid foundation to continue scaling to premium features

📝 Next Steps

Full offline support (background transactions) Push notifications with Firebase Premium subscriptions and payment gateway Financial data export (CSV, PDF)

📎 Conclusion

BudgetGenius demonstrates how it’s possible to build a functional, robust, and modern app with open-source tools, good practices, and long-term architectural decisions. We hope this experience serves as a guide for your next MVP, startup, or learning project. Want to explore the code or contribute?

🌐 Live demo Budget Genius IA
🔗 Fullstack Repository (NestJS) (private repo)