How vimalsaraswat/money-forge works
Project type and purpose
• MoneyForge is a full-stack personal finance management web application built on Next.js (App Router).
• It combines React Server Components, Server Actions, a type-safe PostgreSQL database (via Drizzle ORM), and multiple external services (AI, email, cloud storage).
File structure
• app/: Next.js App Router pages, layouts, loading/fallback UI, RSC entry points, parallel intercept routes for AI chat.
• actions/: Server Action functions (business logic) invoked directly from RSC or form submissions (CRUD, AI prompts, alerts).
• components/: Shadcn UI–based React components (UI primitives, modals, forms, charts).
• db/: Drizzle ORM setup—schema definitions, query functions, DB client.
• config/ & templates/: Constants, AI prompts, email templates.
• providers/: React Context providers (AI, Theme, Session).
• lib/: Utility wrappers for Cloudinary, Nodemailer, helpers.
• auth/ & app/api/auth/: NextAuth.js configuration and route handlers.
README insights
• Emphasis on RSC + Server Actions for colocation of UI and backend logic.
• Use of Google Gemini via Vercel AI SDK for conversational financial assistance.
• NextAuth.js (Google provider) for authentication.
• Framer Motion, Recharts, Tailwind CSS, Shadcn UI for dynamic, responsive UI.
• Nodemailer for budget alert emails, Cloudinary for image uploads.
• Client Browser (UI Layer)
• Next.js RSC pages & React components (app/, components/)
• Charting & animations (Recharts, Framer Motion)
• Next.js Server (App Router)
• Server Components rendering
• Server Actions (actions/) for mutations & business rules
• API Routes (app/api/auth/[...nextauth]) for authentication
• Business Logic & Services
• AI service integration (Vercel AI SDK → Google Gemini)
• Email service (Nodemailer + templates/)
• Image storage (Cloudinary via lib/cloudinary)
• Data Layer
• Drizzle ORM client (db/drizzle.ts)
• Schema & queries (db/tables/, db/queries/)
• PostgreSQL database
• External Integrations
• Google OAuth (NextAuth.js)
• Google Gemini LLM (via Vercel AI SDK)
• Cloudinary (image uploads)
• SMTP server (budget alert emails)
Relationships & interactions
• User request → Next.js Router → RSC/Page component
• Page invokes Server Action → executes code in actions/ → calls Drizzle ORM → reads/writes PostgreSQL
• For AI chat: Server Component calls createAI/getMutableAIState → streams response from Google Gemini → UI updates
• Budget alerts: Scheduled or triggered action → lib/mail sends email using templates → user receives notification
• Authentication flows through NextAuth.js API routes → session stored and consumed by providers/session
Architectural patterns & principles
• Colocated UI & backend logic using Next.js Server Actions
• Domain-driven structure: actions/, db/queries/, components/ grouped by feature
• Provider pattern for cross-cutting concerns (AI, theme, session)
• Type safety across stack (TypeScript, Zod, Drizzle ORM)
• Parallel/Intercepted routes for modals & nested flows (AI chat in @ai folder)
• UI components (blue)
• Server logic (green)
• Data layer (orange)
• External services (purple)
Detailed breakdown of components
• UI Layer: app/layout.tsx, app/page.tsx, components/ui/*, providers/theme-provider
• Auth: NextAuth.js route, auth/config.ts, providers/session
• Business Actions: actions/transaction.ts, actions/budget.ts, actions/ai/chat.tsx
• DB: db/drizzle.ts, db/schema.ts, db/queries/*.ts
• AI: providers/ai-provider.tsx, config/prompts.ts
• Email: lib/mail.ts, templates/budget-alert.ts
• Storage: lib/cloudinary.ts
• Charts & visuals: components/dashboard/*
Detail
• Don’t omit any folder that represents a distinct capability (e.g., hooks/, config/).
• How Server Actions eliminate separate REST layers by embedding logic in the server component runtime.
• How state management flows through Vercel AI SDK hooks (useActionState, getMutableAIState).