app/CLAUDE.md

CLAUDE.md — boha-app-ts

Business management system for a Czech company, rewritten from PHP to TypeScript/Node.js. Handles attendance, invoicing, leave/trips, projects, vehicles, and HR operations.

---

Tech Stack

Layer	Technology
Runtime	Node.js, TypeScript 5.9.3 (strict)
HTTP Framework	Fastify 5.8.2
ORM	Prisma 6.19.2 → MySQL
Auth	JWT (HS256, 15 min) + TOTP 2FA (RFC 6238, otpauth) + bcryptjs
Validation	Zod 4.3.6
Frontend	React 18.3.1 + Vite 8.0.0
Testing	Vitest 4.1.0 + Supertest
PDF	Puppeteer 24.x
Email	nodemailer 8.x
Cron	node-cron 4.x

---

Project Structure

src/
├── server.ts           # Fastify server entry point — plugins, routes, error handler
├── routes/admin/       # HTTP route handlers (one file per entity)
├── services/           # Business logic (no classes, exported functions, uses Prisma directly)
├── schemas/            # Zod validation schemas (one file per entity)
├── middleware/         # auth.ts (requireAuth, requirePermission, optionalAuth)
│                       # security.ts (CSP, HSTS, security headers)
├── utils/              # totp.ts, pdf.ts, email.ts, audit.ts, formatters, etc.
├── config/             # env.ts (config singleton, Date.toJSON override)
├── types/              # index.ts (AuthData, JwtPayload, ApiResponse, re-exports from Prisma)
├── admin/              # React 18 frontend (57 .tsx files)
│   ├── AdminApp.tsx    # Router + lazy-loaded pages
│   ├── contexts/       # AuthContext, AlertContext
│   ├── components/     # Layout, modals, tables, editors
│   ├── pages/          # One file per page/feature
│   ├── hooks/          # useApiCall, useListData, useTableSort, etc.
│   └── utils/          # api.ts (fetch wrapper with token refresh), formatters, helpers
└── __tests__/          # Vitest tests (auth, numbering)

prisma/
├── schema.prisma       # 32 models, MySQL, snake_case columns
└── migrations/         # Applied migrations

dist/                   # Compiled server (CommonJS, ES2022)
dist-client/            # Built frontend (Vite, ES2020)

---

Commands

# Development
npm run dev             # Starts server in watch mode (manage frontend separately)
npm run dev:server      # tsx watch src/server.ts
npm run dev:client      # Vite dev server

# Build
npm run build           # Build server + client
npm run build:server    # tsc -p tsconfig.server.json → dist/
npm run build:client    # vite build → dist-client/

# Run (production)
npm start               # node dist/server.js

# Tests
npm test                # vitest run (single pass)
npm run test:watch      # vitest watch

# Database
npx prisma migrate dev                              # Create migration from schema changes + apply to dev
npx prisma migrate dev --name <descriptive_name>    # Named migration
npx prisma migrate deploy                           # Apply pending migrations to production
npx prisma generate                                 # Regenerate Prisma client after schema changes
npx prisma studio                                   # DB browser GUI
npx prisma db seed                                  # (Re)seed the dev database
npx prisma migrate diff --from-url <url> --to-schema-datamodel prisma/schema.prisma --script  # Preview SQL before prod deploy
npx prisma migrate resolve --applied <migration>    # Mark migration as applied without running SQL

Do not start the dev server. The user manages it separately.

Before running prisma migrate dev or prisma db push, ask the user to stop their dev server and wait for confirmation. Migrations can conflict with an active database connection from the running server.

---

Environment Variables

Required:

DATABASE_URL=mysql://user:pass@host:3306/dbname
JWT_SECRET=<64-char hex string>
TOTP_ENCRYPTION_KEY=<64-char hex string>

Optional (with defaults):

PORT=3001                          # Production port (dev default: 3050, hardcoded in server.ts)
HOST=127.0.0.1
APP_ENV=local|production           # Default: local. Controls CSP, CORS, HSTS
ACCESS_TOKEN_EXPIRY=900            # 15 minutes
REFRESH_TOKEN_SESSION_EXPIRY=3600  # 1 hour
REFRESH_TOKEN_REMEMBER_EXPIRY=2592000  # 30 days
NAS_PATH=Z:/02_PROJEKTY            # Network share for project files
MAX_UPLOAD_SIZE=52428800           # 50MB
CONTACT_EMAIL_TO=
CONTACT_EMAIL_FROM=
SMTP_FROM=
LEAVE_NOTIFY_EMAIL=
APP_URL=                           # Used in email links
CORS_ORIGINS=                      # Comma-separated, production only

Use .env for dev, .env.test for tests.

---

Architecture & Key Patterns

Request Flow

Request → CORS → Cookie → Rate-limit → Security headers
       → requirePermission() or requireAuth()
       → Zod schema validation (parseBody helper)
       → Route handler
       → Service function
       → Prisma
       → success(reply, data) or error(reply, message, status)

Response Format

All responses use this shape:

// Success
{ success: true, data: T, message?: string, pagination?: {...} }

// Error
{ success: false, error: string }

Use the success() and error() helpers in routes — never write raw reply.send().

Service Pattern

Services are plain exported async functions, no classes:

// src/services/foo.service.ts
export async function getFoo(id: number) {
  const result = await prisma.foo.findUnique({ where: { id } });
  if (!result) return { error: "Not found", status: 404 };
  return { data: result };
}

// src/routes/admin/foo.ts
const result = await getFoo(id);
if ("error" in result) return error(reply, result.error, result.status ?? 400);
return success(reply, result.data);

Error Handling

• Routes map service errors to HTTP responses using the pattern above.
• Global error handler in server.ts catches all unhandled exceptions; returns 500 with Czech message.
• Never silently swallow errors. Even if a failure is non-fatal, log it: app.log.error(e, 'context').
• Error messages are in Czech (this is intentional — user-facing messages, Czech company).

Permissions

// Route-level guard
fastify.addHook("preHandler", requirePermission("invoices.view"));
// or multiple
fastify.addHook(
  "preHandler",
  requirePermission("invoices.view", "invoices.edit"),
);

// Admin role bypasses all permission checks
// Permissions follow the pattern: "entity.action" (e.g., "users.create", "invoices.delete")

Audit Logging

Call logAudit() from src/utils/audit.ts whenever data is created/updated/deleted. Pass oldData and newData so the diff is stored. Audit failures are non-fatal.

Validation

Use Zod schemas from src/schemas/. All route bodies must be validated:

const body = parseBody(FooSchema, request.body);
if ("error" in body) return error(reply, body.error, 400);

---

Date & Timezone Handling (Critical Gotcha)

src/config/env.ts sets process.env.TZ = 'Europe/Prague' and overrides Date.prototype.toJSON() to return local time (not UTC). This means:

• JSON.stringify(new Date()) returns local Czech time, not UTC.
• All API responses with Date fields will contain local time strings.
• Prisma stores dates as UTC internally, but they read back as local due to the TZ setting.
• Never assume UTC when working with Date objects in this codebase.
• When writing new date comparisons or DB queries, use new Date() (already local) — do not manually offset.
• The override exists for PHP migration compatibility and Czech date display.

---

TOTP / 2FA

• Secret stored AES-256-GCM encrypted in users.totp_secret.
• Supports two encoding formats: PHP legacy (base64 iv+cipher+tag) and TS (hex).
• Backup codes stored as encrypted JSON array in users.totp_backup_codes.
• When company_settings.require_2fa = true, all users must enroll before accessing the app.
• Login flow: password → if 2FA enabled → issue loginToken (5 min, single-use) → TOTP verify → issue access + refresh tokens.

---

Testing

Tests live in src/__tests__/. They use Vitest + Supertest against a real test database (.env.test).

• Test coverage is minimal: only auth and numbering are tested.
• Use buildApp() helper to spin up the Fastify instance for tests.
• Tests use vitest.config.ts with environment: 'node' and 15s timeout.
• Do not mock Prisma — tests hit a real database to catch schema/query bugs.

When adding new features, add tests in src/__tests__/. Name test files <feature>.test.ts.

---

Frontend Conventions

• Pages are lazy-loaded via React.lazy() in AdminApp.tsx.
• Auth state lives in AuthContext; use useAuth() hook to access it.
• Alerts/toasts use AlertContext; use useAlert() to show them.
• API calls go through src/admin/utils/api.ts which handles token refresh automatically (deduplicates concurrent refresh calls).
• Custom hooks: useApiCall, useListData, useTableSort, useDebounce, useModalLock.
• Styling: CSS files in src/admin/ — no CSS-in-JS, no Tailwind. Use CSS variables.

Query Invalidation Convention

Mutations must invalidate the full domain of any entity they touch. Prefer broad invalidation:

• ["users"] over ["users", "list"]
• ["trips"] over ["trips", "vehicles"]

Reason: React Query's invalidateQueries uses prefix matching, so ["trips"] matches all ["trips", ...] sub-queries. This means new queries are automatically invalidated without updating every mutation handler. Inactive queries are only marked stale, not refetched, so the performance cost is minimal. Optimize to targeted keys only when profiling shows a problem.

When entity A embeds/references entity B, A's mutation handlers invalidate B's domain:

• User CRUD invalidates ["trips"] and ["attendance"] (both embed user data)
• Vehicle CRUD invalidates ["trips"] (trips reference vehicles)
• Invoice CRUD invalidates ["orders"] (orders reference invoices)

---

Frontend — MUI Migration (in progress)

The admin frontend is being migrated off ~7,100 lines of hand-written CSS onto MUI (Material UI v7) — a "Soft-SaaS shell + dense tables" look, dark/light preserved, incremental and always shippable.

• Spec: docs/superpowers/specs/2026-06-06-css-mui-migration-design.md. Per-phase plans: docs/superpowers/plans/2026-06-06-mui-migration-phase-*.md.
• Progress is tracked in agent memory (project_mui_migration.md — what's merged, what's next). Keep it updated as each phase merges. Memory practice generally: durable, non-obvious facts about ongoing work / decisions / gotchas belong in the agent memory store (one fact per file, indexed in MEMORY.md), not left only in chat.
• Migrating a page: mirror src/admin/pages/Vehicles.tsx (the pilot). Import only from the src/admin/ui/ kit — never @mui/* directly in pages. Preserve ALL data logic verbatim (hooks, mutations, invalidate arrays, validation, permissions); change only presentation; drop the page's admin-* CSS usage. Per page: plan → subagent-driven build → spec + code-quality review → user visual check → merge.
• Kit (src/admin/ui/): AppShell, Button, Card, TextField, Select (string-based — convert ids at the boundary), DateField (date-fns v4, dd.MM.yyyy, cs), Modal, ConfirmDialog (optional children + content freeze), DataTable (sortable via sortKey/sortBy/onSort), Pagination, Tabs/TabPanel, StatusChip, CheckboxField, SwitchField, Field, Alert. Theme + tokens in src/admin/theme.ts; one data-theme attribute drives MUI and legacy CSS. Dev-only /ui-kit showcase route.
• Gates every step: npx tsc -b --noEmit (NOT -p tsconfig.json — that's a vacuous solution file that checks nothing), npm run build, npx vitest run.
• Dialog gotchas (solved in the kit — don't reintroduce): dialogs lock <html> via useDialogScrollLock (MUI only locks <body>, and html{overflow-x:hidden} makes <html> the scroll container); Modal/ConfirmDialog freeze title/label/loading through the close fade (derive-state-from-props) so nothing flashes during the transition. Login renders OUTSIDE the AppShell (sibling route).

---

Database Conventions

• All models use snake_case column names; Prisma maps to camelCase in TypeScript.
• Soft-delete via is_deleted boolean (not all tables, check schema).
• Timestamps: created_at, updated_at (auto-managed by Prisma).
• Number sequences (number_sequences table) manage invoice/quotation numbering — never hardcode numbering logic.
• All significant tables have audit log entries. Check audit_logs model for the schema.

---

Database Migrations (Critical Workflow)

Golden rule: NEVER use prisma db push. It bypasses migration history and causes drift between the schema and migration tracking. Always use prisma migrate dev for every schema change.

Every database change or manipulation must be a tracked Prisma migration. This includes:

• Schema changes (tables, columns, indexes, constraints) — via prisma migrate dev
• Permission/role/seed data changes — via a migration that does the INSERTs/DELETEs explicitly
• Lookup data, default settings, or any other row-level baseline that production needs
• Backfills, data fixes, and one-shot corrections that should be in sync across environments

What is NOT acceptable:

• Running raw SQL against production (mysql -e "...", npx prisma db execute, pm2 exec)
• npx prisma db seed as the only way to populate data (seed is dev-only convenience; prod must run the same SQL via a migration)
• "I'll fix it in the seed file" or "I'll add a row manually" without a migration to back it

The reason: every change to the production database must be reviewable, reversible, and reproducible from a fresh checkout. External SQL commands and seed-only changes cause drift — prod and dev diverge, rollback gets harder with every manual change, and the next deploy surprises us.

If you need to insert/update/seed data on production, write a migration. The migration's migration.sql is a normal SQL file — INSERT INTO ..., UPDATE ..., DELETE ... are all valid. Prisma will run it via prisma migrate deploy like any other migration.

Making schema changes

1. Edit prisma/schema.prisma
2. npx prisma migrate dev --name descriptive_name
   → This creates a migration in prisma/migrations/ AND applies it to dev DB
3. npx prisma generate
4. Commit BOTH schema.prisma AND the new migration folder
   git add prisma/schema.prisma prisma/migrations/

Verifying before production deploy

# Preview what SQL will run on production (no changes applied)
npx prisma migrate diff \
  --from-url "mysql://user:pass@prod:3306/app" \
  --to-schema-datamodel prisma/schema.prisma \
  --script

# Empty output = no diff. If it shows SQL, review it before deploying.

Deploying migrations to production

The release process runs prisma migrate deploy on production. This applies only pending migrations — safe, idempotent.

If migrations get out of sync (drift)

# Diff production DB against local schema to find drift
npx prisma migrate diff \
  --from-url "mysql://prod" \
  --to-schema-datamodel prisma/schema.prisma \
  --script

# If drift is safe (CREATE only, no DROPs): apply with db push ONCE, then baseline
# If drift includes DROPs: investigate before touching production

Baselinining a database that has no migrations

If production was synced with db push and has no _prisma_migrations table:

# 1. Create initial migration locally
npx prisma migrate dev --name init

# 2. Copy to production and mark as applied (no SQL runs)
scp -r prisma/migrations user@prod:/var/www/app-ts/prisma/
ssh user@prod
cd /var/www/app-ts
npx prisma migrate resolve --applied <migration_name>

---

Conventions (enforced — verified by the 2026-06-06 audit)

These are the unified rules across the codebase. Follow them for new code; the audit found and fixed the deviations. Full report: docs/codebase-audit-2026-06-06.md.

Routes

• Responses: always success(reply, data[, status, message]) / error(reply, msg, status) / the paginated helper. Never raw reply.send({ success: true, ... }). (Some legacy files still do — convert when you touch them.)
• Route ids: parse numeric params with parseId((request.params as any).id, reply) then if (id === null) return;. Do not use raw parseInt (it yields NaN, not a 400).
• Bodies: validate every body with parseBody(Schema, request.body) → if ("error" in body) return error(reply, body.error, 400).
• Permissions: guard with requirePermission / requireAnyPermission. The admin shortcut is authData.roleName === "admin". ⚠️ AuthData has roleName, not role (role only exists on JwtPayload). Don't type authData as any — it hides exactly this bug.
• Audit: call logAudit on every create/update/delete (and on security-relevant actions like session/token termination) with oldValues/newValues.

Services

• Plain exported async functions; return { data } or { error, status } (preferred over discriminated unions). Services own Prisma; routes stay thin.
• Respect soft-delete (is_deleted: false) in reads where the model has it.

Schemas (Zod 4)

• Use Zod 4 idioms: z.strictObject({...}) / z.looseObject({...}) (not deprecated .strict() / .passthrough()).
• Shared coercion helpers (number-from-form, nullable-number, boolean-from-form) belong in src/schemas/common.ts — don't copy-paste the z.union([z.number(), z.string()]).transform(Number) idiom (it's duplicated ~150× today; consolidating is a tracked follow-up). New number coercions should guard against NaN.
• User-facing messages in Czech; identifiers/keys in English.

Frontend

• Query invalidation: invalidate the broad domain key (["offers"], not ["offers","list"]). Prefix-matching covers sub-queries.
• Single source of truth for shared maps: audit entity_type → Czech label lives in src/admin/lib/entityTypeLabels.ts and MUST be keyed to the server's EntityType values (add the new key there when you add an entity type). Plan categories come from the DB via lib/queries/plan.ts. Don't duplicate label maps across files or across server/client.
• Prefer deriving state over useEffect; use React Query for fetching, not effects.

Dates (two deliberate regimes — don't "fix" either)

• Plan module does all date-only math in UTC (setUTCDate, toISOString().slice(0,10)) because its columns are @db.Date (UTC-midnight). Correct and stable.
• Attendance/leave writes @db.Date at local noon (new Date(y, m, d, 12, 0, 0)).
• Frontend "today" / date-string round-trips: use utils/date.ts localDateStr (server) / normalizeDateStr (client). Never use new Date().toISOString().split("T")[0] for "today" — it's the UTC date and is a day early during the late-evening Prague window.

---

Known Issues & Gotchas

1. Date.prototype.toJSON override — global monkey-patch in src/config/env.ts. Side-effects on third-party libraries that serialize dates. Do not remove without migrating all date serialization.

2. CJS/ESM mismatch in tests — Server compiles to CommonJS (tsconfig.server.json), but Vitest runs in ESM by default. The vitest.config.ts resolves this, but be careful when adding dependencies that only support ESM.

3. Mixed error patterns — Some services return { error, status }, others return discriminated unions { type: 'success' | 'error' }. Prefer { error, status } for consistency with existing routes.

4. Never swallow errors — log at minimum; never use empty catch blocks. The service layer logs via console.* (there is no request-scoped pino logger in services). The NAS managers' previously-silent filesystem catches are now logged. One exception: a catch that handles an expected condition (e.g. ENOENT used as an existence check) may stay silent only with a comment saying so.

5. HTML sanitization is in place — keep applying it — Rich-text fields (invoice notes, quotation scope, order notes) ARE sanitized: server-side DOMPurify (jsdom) plus a cleanQuillHtml regex pass at all three PDF routes, and the frontend sanitizes before every dangerouslySetInnerHTML (InvoiceDetail, OrderDetail). (The old "sanitization gap" note was stale — verified by the 2026-06-06 audit.) When you add ANY new rich-text/HTML field, apply the same sanitization on BOTH the PDF path and the render path.

6. Puppeteer PDF generation — Runs a headless browser. Input to the HTML template must be sanitized. Do not pass unsanitized user data into PDF templates.

7. NAS_PATH file access — Project file uploads write to a network share path. In dev, this path may not be mounted. Features using NAS_PATH will fail gracefully (or not) if the path is unavailable.

8. Prisma client regeneration — After any schema change and migration, run npx prisma generate. The generated client is not committed to git.

9. No CSRF tokens — CSRF protection relies on SameSite=Strict cookies + CORS. Do not weaken CORS configuration.

10. Czech locale hardcoded — Error messages, month names, and some business logic strings are Czech. This is intentional.

11. Seed file is dev-only — prisma/seed.ts is for local dev convenience. It is not the production data source. Any data the production database must have (permissions, default roles, baseline rows) belongs in a migration's migration.sql, not in the seed file. npx prisma db seed must never be run against production.

---

Release Process

1. Bump version in package.json
2. npm run build
3. Commit and tag (git tag -a vX.Y.Z)
4. Push to Gitea (git push origin master && git push origin vX.Y.Z)
5. Create tarball: tar -czf app-ts-X.Y.Z.tar.gz dist dist-client prisma package.json package-lock.json scripts
6. Deploy via SSH to production server (boha_admin@192.168.50.100):
   • Path: /var/www/app-ts
   • Remove old files: rm -rf dist dist-client prisma scripts package.json package-lock.json
   • Copy tarball to server: scp app-ts-X.Y.Z.tar.gz boha_admin@192.168.50.100:/tmp/
   • Extract tarball: tar -xzf /tmp/app-ts-X.Y.Z.tar.gz
   • Install dependencies: npm install --omit=dev
   • Apply Prisma migrations: npx prisma migrate deploy
   • Restart: pm2 restart app-ts --update-env

Hotfixing a migration that was added after the tarball was built

If you write a new prisma/migrations/<timestamp>_* folder after the release tarball has already been built and shipped, that migration is NOT in the tarball and prisma migrate deploy on prod will report "No pending migrations". The release tarball re-build re-runs the whole release, but for a one-off hotfix you can ship just the new migration folder:

# Local
cd prisma/migrations
tar -czf /tmp/warehouse_perms_migration.tar.gz <timestamp>_<name>/
scp /tmp/warehouse_perms_migration.tar.gz boha_admin@192.168.50.100:/tmp/

# On prod
ssh boha_admin@192.168.50.100
cd /var/www/app-ts/prisma/migrations
sudo -u boha_admin tar -xzf /tmp/warehouse_perms_migration.tar.gz
cd /var/www/app-ts
npx prisma migrate deploy
pm2 restart app-ts --update-env

The migration is still tracked in git and applied via prisma migrate deploy — the only thing the tarball is doing is delivering the migration.sql to prod, which is the same mechanism the main release uses. This is preferred over running raw SQL on prod (which the policy in "Database Migrations" forbids).

Do not push directly to production or restart services without confirmation.