Skip to main content

Introduction

This repository is a clean TypeScript finance application rewrite with a NestJS backend, React frontend, Docusaurus docs, and low-cost Google Cloud staging.

Current Operating Model​

The application uses:

  • NestJS backend
  • TypeORM + PostgreSQL
  • React + Vite frontend
  • Tailwind CSS
  • TanStack Query + Zustand
  • Redis for future queue/cache/runtime support
  • Docusaurus docs
  • Terraform-managed Google Cloud staging
  • GitHub Actions deployment
  • docs-as-code
  • observability as part of feature delivery
  • explicit error handling and request correlation as part of runtime delivery
  • mobile-first UX as a non-negotiable product quality rule

The codebase must not depend on the old Laravel application. Do not copy PHP code, Laravel models, migrations, Blade views, frontend assets, package dependencies, or database schema files into this project.

Golden Rule​

Mobile UX comes first. Every user-facing feature must keep the smallest supported viewport simple, useful, intuitive, and free of horizontal overflow before desktop polish is considered complete.

Important summary cards and lists must offer obvious detail actions, preserve the account/category/month/date/review filters users chose, and provide a visible return path to the high-level view.

Dense forms are opened only after user intent, histories are paginated, and summary views show one selected flow at a time to keep the app simple for non-technical users.

Anything needing user action, especially classification review, must be visually highlighted and paired with a direct CTA to the exact filtered workflow where the action can be completed.

Vertical space is premium on mobile. Data comes first, active filters are summarized as compact chips, and filters or secondary controls appear only after explicit user intent. Button-opened creation, edit, and filter surfaces use centered app-themed modals/overlays with internal scroll instead of shifting the main page. App-owned filters use themed app controls; native date/calendar inputs are allowed.

Manual finance entry stays product-simple. Normal user workflows should not expose debit/credit lines, journals, accounting status, currency plumbing, or other implementation concepts.

Voice actions are short, explicit, preview-first, and confirmable. The app records only after user intent and never saves finance data from voice without a confirmation step. AI voice interpretation must preserve the transcript's direction: income/receipts are positive deposits, while payments, purchases, card bills, and invoice-payment language are withdrawals.

Focused filters and expanded filter panels always need an obvious in-place exit, so users can return to the full view without navigating away.

Destructive or session-ending actions use app-themed confirmation dialogs instead of native browser popups, so the interaction keeps the selected theme and mobile flow.

Observability also comes first for runtime work. Logs, metrics, request correlation, and user-safe errors are required unless a task records a clear no-delta rationale.

First Product Slice​

The current implementation includes:

  • finance dashboard with explicit month selection, custom ranges, and account filters
  • review-first account-aware invoice upload route
  • async Gemini invoice classification and digital PDF transaction extraction jobs with notification-driven preview review and visible row-level source badges
  • review-first account-aware bank statement upload route, including async PDF statement classification
  • baseline invoice category suggestions, including Pagamento de Fatura and iFood as Aplicativos
  • classification review queue with single and bulk actions
  • statement transfer and credit detection
  • transaction ledger route with linkable category, account, review, and date filters
  • persisted Resumo and Despesas filters across tab changes until the user clears or changes them
  • category management with user-scoped categories, rename for any category, delete-protected defaults, and deletion blocked while transactions use a category
  • account records with safe Conta principal default
  • budget alerts and management route with one selected alert view at a time
  • recurring expense route with projection for the next month, selectable next 12 months, next quarter, semester, or full year, plus recurring-entry management
  • global voice action flow for short commands, using Speech-to-Text plus Gemini Flash-Lite with local-rule fallback and confirmation before writes
  • reports route
  • runtime status route
  • TypeORM-backed finance read/write API
  • email/password login
  • Google SSO
  • authenticated user-level finance data isolation
  • light-default theme with a dark-mode switch

Local Commands​

From the repo root:

  • npm run setup
  • npm run services:up
  • npm run dev
  • npm run docs:dev when docs are needed
  • npm run validate before pushing

Staging​

Current staging runs in Google Cloud project finance-app-499623.

  • Frontend: financeapp-staging-web
  • Backend: financeapp-staging-api
  • Docs: financeapp-staging-docs

The exact public URLs are printed by the Deploy Staging workflow.

Source Of Truth Hierarchy​

Use this order when documents and implementation disagree:

  1. .tasks/INDEX.md and the active task file
  2. implementation files
  3. route/router/controller/interface definitions
  4. manifests and runnable scripts
  5. infra templates and deploy scripts
  6. summary docs and docs portal pages