ExpenseFlow — Frontend (Next.js)

A production-ready, TypeScript-based frontend for ExpenseFlow: an expense-tracking web application built with Next.js (App Router), TanStack Query, Zod, and Tailwind CSS. Designed for clarity, developer ergonomics, and easy integration with a FastAPI backend.

• Status: Active development
• Tech: Next.js 16+, React, TypeScript, Tailwind CSS, Axios, TanStack Query

--

Quick Start

Prerequisites

• Node.js 18+ and npm or pnpm
• Running backend (see docs/API_DOCS.md)

Getting running locally

npm install
cp .env.example .env.local    # create env from example (or create .env.local)
# set NEXT_PUBLIC_API_URL in .env.local
npm run dev

Build for production

npm run build
npm run start

Useful commands

• npm run dev — start dev server
• npm run build — build app
• npm run lint — run linter
• npm run format — run formatter

--

What this repository contains

High-level responsibilities

• app/ — Next.js App Router routes, layouts, and global UI
• components/ — Reusable UI components (auth, category, layout, ui primitives)
• lib/ — Low-level helpers (axios client, auth helpers, validations)
• hooks/ — Custom React hooks and React Query wrappers
• services/ — Thin API clients calling the backend
• providers/ — App-wide providers (Auth, Query, Theme)
• docs/ — API docs and design notes

See docs/API_DOCS.md for backend contract details.

--

Architecture overview

• Routing: Next.js App Router with nested layouts for (auth) and (dashboard) areas.
• Auth: Edge middleware checks token cookie and redirects to /login when required.
• Data: TanStack React Query for fetching/caching; services encapsulate HTTP calls using an axios instance with auth interceptors.
• Validation: Zod schemas live under lib/validations and are used with React Hook Form.
• Styling: Tailwind CSS tokens are defined in app/globals.css and shared UI primitives live in components/ui.

--

Developer workflow & conventions

1. Add types in types/ for new domain entities.
2. Add Zod schema under lib/validations and plug into forms with zodResolver.
3. Add service methods in services/ (pure async API calls using shared axios).
4. Expose data through a hook in hooks/ using React Query for caching and mutations.
5. Create presentational components under components/ and assemble pages in app/.

Testing & format

• Follow existing lint/format scripts in package.json.

--

Visual / Theming notes

• Global CSS and Tailwind tokens: app/globals.css — adjust color tokens and utilities here.
• Theme provider: providers/ThemeProvider.tsx (if present) controls light/dark modes; update CSS variables accordingly.

--

Contributing

1. Fork and create a topic branch
2. Open a PR with a clear summary and screenshots for UI changes
3. Keep changes focused and add tests for logic where applicable

--

Where to look next

• Authentication flow: middleware.ts and lib/auth.ts
• API client & interceptors: lib/axios.ts and services/
• Layouts and global UI: app/layout.tsx, components/layout, components/ui

--

License

MIT

--

If you'd like, I can now:

• polish developer docs under docs/
• propose UI improvements and a Tailwind theme
• implement a visual refresh (components + globals.css)

Tell me which of those to do next.