ferxodj/cash-flow-supabase

1. This is a single Next.js App Router application that serves both the UI and the backend. The repository is organized around app/, with pages, layouts, client components, and a large set of server route.ts handlers under app/api/.

2. The UI is split into two major product modes:

- home_finanzas_solo for personal finances.

- home_finanzas_parejas for shared/couple finances.

These have their own shells, sidebars, dashboards, charts, and section pages, so the architecture is intentionally domain-separated at the route and component level.

3. The public/auth surfaces are small but important: landing pages, a not-authenticated screen, auth callback handling, password reset, and couple invitation acceptance/rejection flows. The repo also has dedicated routes for login/logout/me and OAuth/session management.

4. The backend is mostly API-first. The app/api/ tree exposes CRUD and summary endpoints for finance entities such as incomes, savings, debts, investments, budget categories, fx losses, user preferences/goals, and profile data. Many endpoints are grouped by domain, with nested routes for actions like withdraw, revert, analytics, monthly summaries, and item-by-id operations.

5. There are two data domains with different boundaries:

- Solo finances: incomes, savings, investments, budget distribution, losses, profile, and personal analytics.

- Couple finances: invite/accept/reject lifecycle, shared views, annual panel, combined net summary, shared budget, debts, and notification management.

This is the main architectural split in the app.

6. Persistence is backed by Supabase. The repo includes app/lib/supabase.ts for client access and app/lib/supabaseAdmin.ts for privileged server-side operations, plus SQL schema files in supabase/. That suggests the app uses Supabase Postgres as the system of record, with some routes requiring elevated access for administrative actions or password/email flows.

7. Authentication and authorization are handled across the app by session utilities and middleware. The presence of middleware.ts, app/lib/session.ts, and the session/profile routes indicates route protection, user identity propagation, and request-time access checks are central to the architecture.

8. Notifications are a first-class backend subsystem. Debt alerts are sent through app/api/debts/notify and app/api/cron/debts-notify, with the README describing Vercel Cron integration and anti-spam tracking via a notifications table. Email delivery is abstracted behind app/lib/mailer.ts.

9. Reporting and analytics are implemented as server-backed summary endpoints plus client chart components. Examples include annual panels, net summary, monthly income/savings views, investment analytics, and budget distribution charts. The UI generally fetches aggregated data from API routes rather than computing everything client-side.

10. There is also a data export path: app/api/export/csv produces CSV output from financial data, which means the backend exposes a reporting boundary separate from the dashboard views.

11. Shared UI infrastructure lives in app/components/ and the various lib/ helpers. These include global loading, headers, access inputs/cards, fetch-header installers, and navigation blockers, which support the app shell and cross-cutting UX behavior rather than a single business domain.

12. Deployment/runtime assumptions matter here: the app is designed for Vercel, with cron support declared in vercel.ts and environment variables for Supabase, session secrets, cron authorization, and optional mail/reset flows. The repo is therefore a serverless Next.js app with Supabase as the main backend service and Vercel as the hosting/scheduling layer.