Monorepo Architecture

Project Structure

Complete directory map of the Staffora monorepo with explanations for each major component.

Monorepo Overview

Staffora is a Bun monorepo with three packages: api, web, and shared. Infrastructure is managed via Docker Compose.

@staffora/api

Elysia.js backend

Depends on @staffora/shared

@staffora/web

React frontend

Depends on @staffora/shared

@staffora/shared

Types & utilities

No internal dependencies

Full Directory Tree

The complete monorepo layout with inline descriptions.

staffora/
├── package.json # Root monorepo config (Bun workspaces) ├── CLAUDE.md # AI coding assistant context ├── README.md # Getting started guide │ ├── packages/ │   ├── api/ # @staffora/api — Elysia.js backend │   │   ├── package.json # Backend dependencies │   │   ├── tsconfig.json
│   │   └── src/ │   │       ├── app.ts # App entry: plugin registration, Route mounts per module │   │       ├── worker.ts # Background worker: Redis Streams consumer │   │       ├── plugins/ # Middleware plugins │   │       │   ├── auth-better.ts # Better Auth + session caching + API keys + CSRF │   │       │   ├── db.ts # PostgreSQL (postgres.js) connection │   │       │   ├── cache.ts # Redis (ioredis) connection │   │       │   ├── rbac.ts # Permission guards │   │       │   ├── tenant.ts # Multi-tenant RLS context │   │       │   ├── audit.ts # Mutation audit logging │   │       │   ├── metrics.ts # Prometheus metrics │   │       │   ├── errors.ts # Global error handler │   │       │   ├── rate-limit.ts # Redis rate limiting │   │       │   └── idempotency.ts # Duplicate request prevention │   │       ├── modules/ # Feature modules │   │       │   ├── hr/ # Core HR (employees, org, positions) │   │       │   ├── payroll/ # Payroll runs, tax, journal entries │   │       │   ├── absence/ # Leave management │   │       │   ├── time/ # Time & attendance │   │       │   ├── talent/ # Performance reviews, goals │   │       │   ├── recruitment/ # Hiring pipeline │   │       │   ├── lms/ # Learning management │   │       │   ├── cases/ # Employee relations │   │       │   ├── workflows/ # Workflow engine │   │       │   ├── benefits/ # Benefits administration │   │       │   ├── documents/ # Document management │   │       │   ├── security/ # RBAC, users, audit │   │       │   ├── analytics/ # Reporting & dashboards │   │       │   ├── dsar/ # GDPR requests │   │       │   ├── sso/ # SAML/OIDC SSO │   │       │   ├── pension/ # Auto-enrolment │   │       │   ├── onboarding/ # Employee onboarding │   │       │   └── ... # Additional modules │   │       ├── jobs/ # Background job workers │   │       │   ├── outbox.ts # Transactional outbox processor │   │       │   ├── notifications.ts
│   │       │   ├── pdf-generation.ts
│   │       │   ├── export.ts
│   │       │   └── analytics.ts
│   │       ├── lib/ # Shared utilities │   │       ├── db/ # Migration runner │   │       ├── scripts/ # CLI tools (bootstrap-root) │   │       └── test/ # Test files │   │           ├── unit/
│   │           ├── integration/
│   │           ├── e2e/
│   │           ├── security/
│   │           ├── performance/
│   │           └── chaos/
│   │ │   ├── web/ # @staffora/web — React frontend │   │   ├── package.json
│   │   ├── react-router.config.ts # SSR mode config │   │   ├── tailwind.config.js
│   │   ├── vite.config.ts
│   │   └── app/ │   │       ├── routes.ts # Route configuration │   │       ├── routes/ │   │       │   ├── (auth)/ # Login, forgot-password │   │       │   ├── (app)/ # Employee-facing app │   │       │   │   ├── dashboard/
│   │       │   │   ├── employees/
│   │       │   │   ├── leave/
│   │       │   │   ├── time/
│   │       │   │   ├── payroll/
│   │       │   │   ├── talent/
│   │       │   │   ├── recruitment/
│   │       │   │   ├── lms/
│   │       │   │   ├── benefits/
│   │       │   │   ├── cases/
│   │       │   │   ├── documents/
│   │       │   │   ├── reports/
│   │       │   │   ├── me/ # Employee self-service │   │       │   │   └── manager/ # Manager portal │   │       │   └── (admin)/ # Admin routes │   │       ├── components/ │   │       │   ├── ui/ # Primitives (button, input, modal, table, etc.) │   │       │   ├── auth/ # LoginForm, AuthGuard │   │       │   ├── charts/ # AreaChart, BarChart, LineChart, PieChart │   │       │   ├── analytics/ # ExecutiveDashboard, KPICard │   │       │   ├── employee/ # EmployeeQuickView, GlobalSearch │   │       │   ├── benefits/ # EnrollmentWizard, PlanCard │   │       │   ├── reports/ # ChartBuilder, FilterBuilder, ColumnConfig │   │       │   ├── org-chart/ # OrgChartViewer │   │       │   ├── competencies/ # CompetencyCard, GapChart │   │       │   ├── security/ # SecureField (field-level permissions) │   │       │   └── succession/ # SuccessionPlanCard │   │       ├── hooks/ # Custom React hooks │   │       ├── lib/ # API client, auth, query, theme, utils │   │       └── __tests__/ # Vitest tests │   │ │   └── shared/ # @staffora/shared — Types & utilities │       ├── package.json
│       └── src/ │           ├── types/ # TypeScript types per domain │           ├── schemas/ # Zod schemas │           ├── state-machines/ # Employee, leave, case, workflow, performance, recruitment │           ├── constants/ # App-wide constants │           ├── errors/ # Error codes and messages │           └── utils/ # Date handling, effective dating, Bradford factor, crypto │ ├── migrations/ # Sequential PostgreSQL SQL migrations │ ├── docker/ │   ├── docker-compose.yml # Main: PostgreSQL, Redis, PgBouncer, API, Web │   ├── docker-compose.scale.yml # Horizontal scaling │   ├── docker-compose.monitoring.yml # Prometheus + Grafana │   ├── docker-compose.logging.yml # Loki + Promtail │   ├── .env.example # Full environment variable reference │   ├── nginx/ # Nginx load balancer config │   ├── postgres/ # PostgreSQL init scripts │   ├── redis/ # Redis config │   └── pgbouncer/ # PgBouncer config │ ├── Docs/ # ~200 markdown documentation files │   ├── architecture/ # ADRs, database guide, permissions │   ├── audit/ # Security audit, compliance, tech debt │   ├── guides/ # Getting started, deployment, frontend │   └── patterns/ # Security, state machines, effective dating │ ├── tests/ # Top-level integration tests │ └── .github/ # 8 CI/CD workflows + Dependabot

Package Dependencies

How the three packages relate to each other.

@staffora/api

Elysia.js backend

@staffora/web

React frontend

@staffora/shared

Types, schemas, state machines, utilities

@staffora/api depends on @staffora/shared

@staffora/web depends on @staffora/shared

@staffora/shared has no internal dependencies

Key Files Quick Reference

The most important files to know when working with Staffora.

File	Purpose
`packages/api/src/app.ts`	API entry point -- all plugin and route registration
`packages/api/src/worker.ts`	Background worker entry point
`packages/api/src/plugins/auth-better.ts`	Complete auth subsystem
`packages/web/app/routes.ts`	All frontend route definitions
`packages/shared/src/state-machines/`	All state machine definitions
`docker/docker-compose.yml`	Full infrastructure definition
`docker/.env.example`	All configuration variables
`migrations/`	Complete DB schema history (sequential migration files)