CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

BizWiz is an Invoice Bank Statement Processor - a full-stack financial management application built with Next.js 15.1.0 that helps businesses process and match invoices with bank transactions automatically. The application features multi-tenant organization support with role-based access control.

Essential Commands

Development

pnpm dev - Start development server on port 5001
pnpm build - Build for production
pnpm start - Start production server on port 5001

Code Quality

pnpm lint - Run ESLint checks
pnpm test - Run unit tests with Jest
pnpm test:watch - Run unit tests in watch mode
pnpm test:coverage - Run unit tests with coverage
pnpm cypress - Open Cypress for E2E testing
pnpm cypress:headless - Run Cypress tests headlessly
pnpm test:e2e - Run full E2E test suite with server

Database

pnpm prisma generate - Generate Prisma client
pnpm prisma db push - Push schema to database
pnpm prisma migrate dev - Run database migrations
pnpm prisma studio - Open Prisma Studio

Architecture

Tech Stack

Framework: Next.js 15.1.0 with App Router
Language: TypeScript (strict mode)
Database: PostgreSQL with Prisma ORM
Authentication: NextAuth.js with Prisma adapter
Styling: TailwindCSS with Radix UI components
AI Integration: OpenAI API for PDF data extraction
Storage: Linode S3-compatible object storage

Backend Architecture

API Routes: Next.js API Router pattern (app/api/)
Layered Architecture: Controllers → Services (lib/services/) → Repositories (lib/repositories/)
Multi-tenancy: Organization-scoped data access with role-based permissions (OWNER, ADMIN, USER)
Authentication: NextAuth.js with custom middleware for route protection

Frontend Architecture

Next.js App Router: File-based routing with server components by default
Component Organization: Feature components in app/components/, UI primitives in components/ui/
Form Handling: React Hook Form with Zod validation
State Management: Local state with hooks, Context API for authentication

Database Models

Core entities: User, Organisation, Invoice, BankTransaction, ServiceAccount, Payslip with proper relationships and organization-scoped access.

Critical Development Process Rules - FOLLOW THESE EXACTLY WITH EVERY TASK

Key Conventions

CRITICAL: You MUST read and follow ALL coding conventions and guidelines specified in these files:

ARCHITECTURE.md - Project architecture documentation. This is the most important file to read.
CONVENTIONS.md - Core development process rules that must be followed for every task
CONVENTIONS-BACKEND.md - Complete backend development standards and best practices
CONVENTIONS-FRONTEND.md - Complete frontend development standards and best practices

Before starting any coding task, always read the relevant CONVENTIONS files to ensure full compliance with the project's coding standards.

Testing Strategy

Unit Tests: Jest configuration with jsdom for React components
E2E Tests: Cypress with base URL http://localhost:5001 (opens in a new tab)
Critical Flows: Authentication, invoice processing, user management
All major functionality must have both unit and E2E test coverage

Security Considerations

All user input must be validated using Zod schemas. There must always be a validation error if the input is invalid.
Role-based access control (OWNER, ADMIN, USER). Only users with the appropriate role should have access to certain features or data. If it is unclear what the access control should be, please ask for clarification
NextAuth.js with JWT sessions
Environment variable management for secrets
All API routes must be protected with middleware to ensure only authorized users can access them.
All API routes must explicitly check for session token and make sure user is authenticated and has adequate permissions before proceeding.

Development Workflow

Before starting any coding task, always read the relevant CONVENTIONS files to ensure full compliance with the project's coding standards.
Ensure you have full understanding of the project's architecture and requirements before starting any coding task
Update relevant documentation files per conventions
Run linting and tests before committing
Ensure all tests pass and build succeeds

Important Files

CONVENTIONS.md - Core development rules (must follow)
CONVENTIONS-BACKEND.md - Backend development standards
CONVENTIONS-FRONTEND.md - Frontend development standards
SPECIFICATION.md - Application requirements and API definitions
ROADMAP.md - Project roadmap and task status
prisma/schema.prisma - Database schema
cypress/e2e/ - End-to-end tests
__tests__/ - Unit tests

Claude Memories

You never have to start dev server on your own

Architecture Conventions Backend