36accc3b30
Created dedicated workspace for Docker deployment configurations and scripts. Improves organization by grouping all deployment-related files together. ## New Structure - docker-stack/: Docker Compose files and deployment scripts - docker-compose-standalone.yaml - docker-compose-swarm.yml - docker-compose-debug.yml - deploy-standalone.sh - deploy-swarm.sh - README.md (deployment documentation) - package.json ## Changes - Moved all docker-compose YAML files to docker-stack/ - Moved deploy scripts to docker-stack/ - Updated VS Code workspace to include docker-stack - Updated documentation (README, CLAUDE.md) ## Deployment Workflow 1. Build: `cd web-app && ./build.sh 2.20.0` 2. Deploy: `cd docker-stack && ./deploy-standalone.sh 2.20.0` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
# 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:
|
|
```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 `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 |