diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..bcaa9d7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+- `npm run dev` - Start development server (Next.js)
+- `npm run build` - Build production version  
+- `npm start` - Start production server
+- `npm run prettier` - Format code with Prettier
+- `npm run prettier:check` - Check code formatting
+- `npm run seed` - Seed database with initial data
+
+## Deployment Commands
+
+- `./build.sh` - Build Docker image for deployment
+- `./deploy.sh` - Deploy Docker service to production
+- `./debug-deploy.sh` - Deploy with debug configuration
+
+## 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 `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 `app/lib/actions/` and follow the pattern:
+```typescript
+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 `messages/` directory. The middleware handles both auth and i18n routing.
+
+### Key Files & Responsibilities
+
+- `middleware.ts` - Handles authentication and i18n routing, defines public pages
+- `app/lib/auth.ts` - NextAuth configuration, `withUser` HOF for user context
+- `app/lib/dbClient.ts` - MongoDB connection with development/production handling
+- `app/lib/actions/` - Server actions for data mutations (locations, bills, months)
+- `app/i18n.ts` - Internationalization configuration (Croatian default)
+- `next.config.js` - Standalone build config with `serverActions.allowedOrigins` for Docker deployment
+
+### 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
\ No newline at end of file