Tech Stack
Runtime & Language
| Technology | Version | Usage |
|---|---|---|
| Node.js | 22+ | Runtime |
| TypeScript | 5.x | Language (strict mode) |
| pnpm | 10+ | Package manager with workspaces |
Backend
| Technology | Version | Usage |
|---|---|---|
| Fastify | 5.x | HTTP server |
| tRPC | 11.x | Type-safe API layer |
| TypeORM | 0.3.x | Database ORM |
| PostgreSQL | 16 | Primary database (with TimescaleDB + pgvector extensions) |
| Redis | 7 | Caching and sessions |
| Zod | 3.x | Schema validation |
| Pino | — | Structured logging |
| JWT | — | Authentication + refresh tokens |
| bcrypt / bcryptjs | — | Password hashing |
| FCM + Web Push | — | Push notifications |
Frontend
| Technology | Version | Usage |
|---|---|---|
| Alpine.js | 3.14 | Reactive UI (all apps) |
| Vite | 6.x | Build tool and dev server |
| Tailwind CSS | 4.0 | Utility-first CSS |
| Capacitor | 8.x | Mobile app (iOS + Android) |
| Cropper.js | 1.6 | Image cropping (Employee App) |
| mermaid | 11.x | Diagrams in docs |
Docs
| Technology | Version | Usage |
|---|---|---|
| VitePress | 1.6 | Documentation site |
| vitepress-plugin-mermaid | 2.x | Diagram rendering |
Infrastructure
| Technology | Usage |
|---|---|
| Docker Compose | Container orchestration (dev) |
| nginx | Docker reverse proxy + docs hosting |
| pgAdmin 4 | Database management UI |
| Husky | Git hooks |
| lint-staged | Pre-commit formatting |
| Biome 2.x | Linting and formatting |
Build & Testing
| Technology | Usage |
|---|---|
| Vitest | Test runner |
| tsup | Library bundling (SDK, core sub-paths, components) |
| tsc | Type checking and some builds |
| Commander.js | CLI framework (hereby command) |
| turbo | Monorepo task orchestration |
Frontend Architecture
All Alpine.js apps share the same stack:
Alpine.js 3.14 (reactive components)
+ @hereby/sdk (tRPC client)
+ @hereby/components (auth UI + NotificationBell)
+ Tailwind CSS 4.0 (styling)
+ Vite 6.0 (build + HMR)Custom Vite Plugin
All apps use a custom htmlInclude() Vite plugin that processes <!-- include "path" --> directives for HTML composition, enabling modular view/component templates.
SDK Integration
The SDK is registered as an Alpine.js plugin, creating a $store.hereby store with:
- Authentication state
- Timezone-aware formatters (
formatDate,formatTime,formatDateISO,todayLocal) - SDK client instance
- Permission checking helpers
- Login / logout methods
Core Package (@hereby/core)
Browser-safe sub-path exports built with tsup:
@hereby/core/date— date formatters (ESM+CJS, zero deps)@hereby/core/constants— permission constants, insurance rates (ESM+CJS)@hereby/core/errors— error classes (ESM+CJS)- Root
@hereby/core— everything including schemas (CJS only, depends on zod/pino)
TypeScript Configuration
json
{
"strict": true,
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"strictPropertyInitialization": false,
"target": "ES2022",
"module": "ESNext"
}- Strict mode: No implicit any, strict null checks
- Decorators: Required for TypeORM entities
- PascalCase: Types, interfaces, classes
- camelCase: Variables, functions
- Consistent array syntax: shorthand
T[]
Biome Configuration
- Formatter: 2 spaces, LF line endings, 100-char line width
- Linter: Strict rules for complexity, correctness, security, style, a11y
- Sorted imports: Enforced across all packages
- Auto-fix:
pnpm lint:fix - Pre-commit hook: via Husky + lint-staged