Architecture

Hereby is a monorepo built with pnpm workspaces, organized into modular packages, production applications, and operator tools.

System Diagram

Packages

Package	Description
@hereby/database	TypeORM entities (66), migrations (90), seeds (16)
@hereby/api	Fastify 5 + tRPC 11 server with 38 routers
@hereby/core	Shared types, 35 Zod schemas, 16 enum files, Pino logger, utilities
@hereby/sdk	TypeScript SDK with 37 service classes (ESM/CJS/browser)
@hereby/cli	Commander.js CLI tool (hereby command)
@hereby/components	Alpine.js components (AuthGate, LoginForm, RegisterForm, ChangePasswordForm, NotificationBell)
@hereby/code-modules	Source calculator modules (payroll allowance/deduction)
@hereby/secom-puller	Secom fingerprint event puller service
@hereby/static	Design tokens + shared styles/assets
@hereby/test	Vitest integration test suite

Applications

App	Port	Description
HR System	4000	Payroll management with grid editing, memos, keyboard shortcuts, grade promotion
Admin Panel	4001	Employees, teams, roles, leaves, hospital settings
Employee App	4002	Mobile/web (Capacitor iOS + Android) for all employees
Nurse Scheduler	4003	Monthly scheduling with AI auto-generation
Internal Approval	4004	Approval workflows for leave/overtime/incentives/documents
General Affairs	4005	Training, recurring tasks, notices
Management Dashboard	4006	Labor cost, claims, staffing, incentive trends
Inventory	4007	Items, categories, expiration, refunds
Module Manager	4010	Module registry and calculator configuration
Importer	CLI	Excel data importer (47 sheets)

Tools

Tool	Port	Description
System Admin	4100 / 4101	Organization provisioning, admin accounts, cross-org attendance — standalone Fastify + Alpine.js, direct PostgreSQL, IP allowlist + JWT

Key Design Principles

Multi-tenancy

All queries include organizationId filtering. Each entity belongs to exactly one organization.

Soft Deletes

All entities use deletedAt timestamps. No hard deletes.

Audit Trail

All entities extend BaseEntity with createdAt, updatedAt, deletedAt fields.

Append-only Meta Tables

Append-only meta tables use chainId + version + supersededAt to preserve history across edits. Pricing config (item code, source module, rates, multipliers, unit prices) lives on sheet column metadata + the org parameter store; see Payroll Schema Refactor.

Type Safety

tRPC provides end-to-end type safety from database entities through API to frontend SDK calls.

Permission Model

Scoped Role-Based Access Control (RBAC):

• Permissions: resource:action.scope (self / team / all)
• Default roles: SUPER_ADMIN, HR_ADMIN, TEAM_LEADER, EMPLOYEE, PAYROLL_ADMIN, GENERAL_AFFAIRS_ADMIN
• Team-level overrides via TeamPermission

Payroll Code Modules

Sheet-driven payroll calculation:

• @hereby/code-modules holds one pure compute(inputs, parameters) per SourceModule (overtime, insurance, tax bracket, …) with its parameter schema, defaults and key descriptions
• sheet-rows/compute.ts loads each module's inputs from the source tables for the sheet period (loadInputsByModule), runs compute() per row, and the sheet "✓ 커밋" writes AllowanceRecord / DeductionRecord
• The same module code runs in the browser (hr-system commit-compute.ts) for previews, so API and UI agree by construction
• Parameter schemas are exposed for UI generation via moduleRegistry.list

Notification System

• Event + Delivery split: NotificationEvent (1 per event) → NotificationDelivery (1 per recipient × channel)
• Sparse preference matrix: NotificationPreference(employeeId, eventType, channel, enabled)
• Mute rules by employee, team, or event type
• Multi-channel: in-app, push (FCM + Web Push), email, SMS

Data Flow

Standard Request

Payroll Sheet Commit Flow

Folder Structure

hereby-dhub/
├── packages/
│   ├── database/            # TypeORM entities, migrations, seeds
│   ├── api/                 # Fastify + tRPC routers, sheet compute
│   ├── core/                # Shared types, enums, schemas, utilities
│   ├── sdk/                 # TypeScript SDK services
│   ├── cli/                 # CLI tool
│   ├── components/          # Alpine.js shared components
│   ├── database/            # TypeORM entities, migrations, seeds
│   ├── code-modules/        # Payroll compute modules (pure, browser + Node)
│   ├── secom-puller/        # Secom fingerprint event puller
│   ├── static/              # Design tokens + shared styles/assets
│   └── test/                # Vitest integration tests
├── apps/
│   ├── hr-system/           # HR/Payroll (port 4000)
│   ├── admin/               # Admin panel (port 4001)
│   ├── employee-app/        # Capacitor mobile + web (port 4002)
│   ├── nurse-scheduler/     # Scheduling (port 4003)
│   ├── team-manager/        # Approvals (port 4004)
│   ├── general-affairs/     # 총무 (port 4005)
│   ├── management-dashboard/  # 경영 대시보드 (port 4006)
│   ├── inventory/           # 재고 관리 (port 4007)
│   ├── module-manager/      # Module health (port 4010)
│   └── importer/            # Excel CLI
├── tools/
│   └── system-admin/        # Platform operator console
├── docker/                  # PostgreSQL, Redis, pgAdmin
├── docs/                    # VitePress documentation
└── scripts/                 # Deployment and provisioning scripts