evidencija-rezija/CLAUDE.md

CLAUDE.md

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

Repository Structure

This is a multi-project repository containing:

• web-app/: Next.js 14 utility bills tracking application
• docker-stack/: Docker Compose configurations and deployment scripts
• housekeeping/: Database backup and maintenance scripts

Each project is self-contained with its own dependencies.

Development Commands

All commands should be run from within the respective project directory.

Web App (cd web-app):

• npm install - Install dependencies
• npm run dev - Start development server
• npm run build - Build production version
• npm start - Start production server
• npm run prettier - Format code
• npm run seed - Seed database with initial data

Housekeeping (cd housekeeping):

• ./db-backup--standalone.sh - Run standalone database backup
• ./db-backup--swarm.sh - Run swarm database backup
• ./db-dump--standalone.sh - Run standalone database dump
• See housekeeping/README.md for more details

Deployment Commands

Building Docker Image (cd web-app):

• ./build.sh <version> - Build Docker image

Deploying (cd docker-stack):

• ./deploy-standalone.sh <version> - Deploy with docker-compose (standalone)
• ./deploy-swarm.sh <version> - Deploy with Docker Swarm

Architecture Overview

This is a Next.js 14 utility bills tracking application ("Evidencija Režija") with the following key components:

Tech Stack

• Framework: Next.js 14 with App Router and standalone output for Docker
• Authentication: NextAuth v5 with Google OAuth
• Database: MongoDB with connection pooling
• Internationalization: next-intl (Croatian/English)
• Styling: Tailwind CSS with DaisyUI components
• Deployment: Docker with MongoDB 4.4.27 (AVX compatibility)

Core Architecture Patterns

Multi-user Data Isolation: All database operations use the withUser higher-order function from web-app/app/lib/auth.ts:102 to automatically inject authenticated user ID into queries, ensuring data isolation between users.

Server Actions Pattern: Form handling uses Next.js Server Actions with Zod validation. Actions are defined in web-app/app/lib/actions/ and follow the pattern:

export const actionName = withUser(async (user: AuthenticatedUser, ...args) => {
  // Server action implementation with automatic user context
});

Internationalization: Uses next-intl with locale-based routing. Messages are in web-app/messages/ directory. The middleware handles both auth and i18n routing.

Key Files & Responsibilities

• web-app/middleware.ts - Handles authentication and i18n routing, defines public pages
• web-app/app/lib/auth.ts - NextAuth configuration, withUser HOF for user context
• web-app/app/lib/dbClient.ts - MongoDB connection with development/production handling
• web-app/app/lib/actions/ - Server actions for data mutations (locations, bills, months)
• web-app/app/i18n.ts - Internationalization configuration (Croatian default)
• web-app/next.config.js - Standalone build config with serverActions.allowedOrigins for Docker deployment
• housekeeping/ - Database backup and maintenance scripts

Database Schema

• Collections: Locations, Bills, Months (year-month periods)
• User Association: All documents include userId field for multi-tenant isolation
• Database Name: "utility-bills"

Docker Deployment Notes

• Uses standalone Next.js build for Docker optimization
• MongoDB 4.4.27 required for older CPU compatibility (no AVX instructions)
• HOSTNAME=0.0.0.0 with serverActions.allowedOrigins config to handle reverse proxy headers
• Environment variables: MONGODB_URI, GOOGLE_ID, GOOGLE_SECRET, AUTH_SECRET

Barcode/QR Code Feature

• Uses @zxing/library and @zxing/browser for PDF document scanning
• Heavy barcode decoding operations should be moved to background threads if performance issues arise
• PDF processing with pdfjs-dist for utility bill scanning

Testing & Code Quality

• ESLint with Next.js and Prettier configurations
• No specific test framework configured - check with user before assuming testing approach