Skip to Content
Engineering HandbookArchitecture & Systems

Architecture & Systems

System map

internal HTTPsocket emitZitadel · auth / JWThaer-platform-webNext.jshaer-claims-mobileExpo / RNhaer-connectorPythonhaer-platform-apiNestJS + TypeORMhaer-claims-apiGo / Fiberhaer_connector DBhaer-platform-bgjobsGo workersPostgresMCP toolsAI

Responsibilities by repo

  • haer-platform-web — frontend web: route orchestration, layout, auth/tenant, plumbing API. Turborepo (apps/web + packages/*).
  • haer-platform-api — backend transaksional utama: REST API, data transaksional, migration DB (TypeORM). Bukan heavy-lifting.
  • haer-claims-api (Go/Fiber) — domain klaim & expense: CRUD + submission claim, line item, receipt/OCR intake, transisi status (draft → submitted → approved/rejected). golang-migrate.
  • haer-claims-mobile — app mobile: file klaim/mileage/travel/split, approve/reject, notifikasi, browse benefit. Manggil haer-platform-api + haer-claims-api.
  • haer-platform-bgjobs — background workers (Go): notif-engine (notif email/socket), import-worker (import karyawan), location-sync (master lokasi). Heavy-lifting async.
  • haer-connector — integration layer source-agnostic: ingest data HR → model kanonik Person/Signal → expose ke AI agent via MCP. Python/FastAPI + AI.

Repo haer-claims-api  (Go API) muncul di peta karena web & mobile manggil dia, walau di luar 5 repo fokus handbook ini.

Ownership & cross-folder rules

  • Satu repo, satu tim. Default single-folder change; jangan ngedit repo lain kecuali ticket integration.
  • Kontrak berubah → notify konsumer (web, mobile) di PR yang sama.
  • Merge order: backend/API → web/mobile → deploy/auth. Lihat Engineering Process.

haer-platform-web internal boundaries (monorepo)

  • Jangan pindah ownership antara apps/web dan packages/*.
  • page.tsx tipis — cuma mount feature module. Route bucket tetap: (marketing), (auth), [tenant], platform-admin.
  • Feature package cuma di-import lewat public entrypoint (@haer/feature-*); import internal src/* dilarang.
  • Nambah packages/* butuh 3 edit terkoordinasi (transpilePackages di next.config.mjs, COPY di Dockerfile stage deps, pnpm install) — kalau nggak, clean build Docker gagal walau pnpm build lokal lolos. Verifikasi pakai clean build beneran, bukan cuma lokal.

Auth

Semua surface yang di-protect di-scope by tenant + role via Zitadel (JWT). Verifikasi token & resolusi tenant selalu server-side. Detail auth ada di haer-platform-api/docs/AUTH.md + docs/SSO.md.

Source: workspace CLAUDE.md (folder ownership, cross-folder rules) + AGENTS.md tiap repo.

Coding ConventionsData & Migrations