Coding Conventions

Drill-down dari Technical Standards. Kalau standards ngasih ringkasan satu baris per-stack, halaman ini isinya aturan konkret yang dipakai pas nulis kode. Source of truth tetap AGENTS.md tiap repo — halaman ini nyalin yang paling sering kepake biar gampang di-scan.

Prinsip lintas-layer: match konvensi lokal (conformance > selera), perubahan kecil & reviewable, jangan refactor di luar scope ticket, jangan nambah dependency tanpa approval.

Frontend

Repo: haer-platform-web (Next.js App Router + Turborepo) & haer-claims-mobile (Expo / React Native).

TypeScript

Hindari any — prefer unknown lalu narrow.
ESLint bersih (--max-warnings=0) + Prettier. Pre-commit jalanin lint-staged.
Komentar cuma buat workaround atau business logic kritis, pakai JSDoc di parent function — bukan inline. Kode harus self-documenting.

Arsitektur & imports

page.tsx tipis — cuma mount feature module. Jangan pindahin ownership antara apps/web dan packages/*.
Import feature package cuma lewat entrypoint publik (@haer/feature-* atau subpath yang didokumentasiin). @haer/feature-*/src/* dilarang.
Nambah packages/* baru = tiga edit terkoordinasi (kalau nggak, Docker build production gagal walau local pnpm build lolos):
1. apps/web/next.config.mjs → tambah ke transpilePackages.
2. Dockerfile → tambah baris COPY packages/<name>/package.json.
3. pnpm install biar pnpm-lock.yaml kerekam. Verifikasi lewat clean build, bukan cuma local.

Urutan reuse: export @haer/ui → komponen packages/ui/src/app-base/* → bikin app-base baru.
Pakai token semantik (tokens.css / design-system.css). Nggak ada literal warna / spacing / tipografi / z-index kalau token-nya udah ada.
Handle state loading / empty / error / success eksplisit (skeleton / spinner dari design system). Hormati prefers-reduced-motion; prefer transform + opacity.
Baca /DESIGN.md sebelum bikin atau ubah UI.

Data & kalkulasi

Semua math uang / business logic di backend. Frontend cuma format (currency, tanggal) — jangan hitung sendiri.
Call backend dari browser lewat apps/web/src/lib/api/api-client.ts + /api/proxy; dari server lewat backend-server.ts. Kontrak lintas-package taruh di packages/types.

Backend

haer-platform-api (NestJS / TypeScript)

Pola module / controller / service / DTO.
Entity TypeORM = source of truth schema. synchronize: false selalu, di semua environment.
Migrasi: generate lawan scratch DB lokal yang bersih, jangan pernah lawan DB remote/shared. Pair migrasi Postgres + Oracle di PR yang sama. Jangan pernah edit migrasi yang udah ke-merge — bikin yang baru.
Auth (Zitadel JWT) & tenant resolve server-side; jangan percaya tenant/user/role dari client.

haer-platform-bgjobs (Go)

Idiomatik Go, go vet bersih, error di-wrap dengan konteks.
Migrasi pakai golang-migrate (up / down / up di DB bersih).

haer-connector (Python 3.12)

ruff strict (lint + format). FastAPI + SQLAlchemy 2 async.

Lintas backend

Kontrak API entity-based, ikut konvensi OData / REST.
Perubahan kontrak (endpoint / shape / auth berubah) wajib ditulis di PR bagian “API contract impact” + kabarin konsumer (web & mobile). Lihat merge order.
Validasi input di trust boundary (route handler, handler backend). Audit log buat CREATE / UPDATE / DELETE di data tenant. Nggak ada PII di log.

Scripts

Repo: scripts + tooling .claude/ di tiap repo.

Prefix semua command CLI dengan rtk (Rust Token Killer) — kalau ada filter dipakai, kalau nggak passthrough. Aman selalu. Termasuk di dalam chain &&: rtk git add . && rtk git commit.
rtk output itu ringkasan buat dibaca manusia, bukan input mesin. Jangan pipe rtk git diff > x.patch — bukan patch valid.
Verifikasi test scoped ke file yang berubah (--changed / --filter / go test ./internal/<pkg>/), bukan full suite. Full run = laptop nge-lag.
Shell script tetep POSIX-friendly dan idempoten kalau bisa.

Source of truth: AGENTS.md tiap repo, .ai/instructions/* (haer-platform-web), dan docs/engineering-development-standard.md.