PayLens / engineering

Built to make compensation data clear, auditable, and operational.

A technical walkthrough of the product decisions, performance work, security model, and deployment topology behind PayLens.

Next.js 16Next.js 16NestJS 12NestJS 12PostgreSQLPostgreSQLRedis / BullMQRedis / BullMQCloudflare R2Cloudflare R2 · OpenTelemetry

Fast path

Reviewer quick access

Production endpoints and source repositories, grouped for a short review.

Reviewer demo · email verified

Company:
Demo Company · Tenant Owner
Password:
ThereWeGoAgain@123

Intentionally public evaluation workspace — do not store real or sensitive information in this tenant. The same credentials can be populated directly from the login screen using “Use Demo Account”.

Open Demo Login

Synthetic / demo data

Try PayLens with 10,000 Employees

A ready-to-import synthetic technology-company workforce for reviewing the full import, directory, search, and export path.

10,000 Employee Demo Dataset

Synthetic technology-company workforce

10,000 Employees20 DepartmentsCSV~1.3 MB

Sign in with the reviewer demo account above, then import this file into Demo Company to quickly populate PayLens for evaluation. The dataset contains synthetic names and @novastack.example email addresses; it is for product evaluation only and does not send external email. The demo seed itself never prepopulates employees — the import is the product workflow under review.

Why there is no Organization column

The import file intentionally has no Organization ID. PayLens never trusts CSV data to choose a tenant: the authenticated session and active organization determine where imported employees belong.

Authenticated user → active Membership → active Organization → uploaded Employee data

System shape

Live architecture

Frontend and backend are independently deployed applications connected through a versioned REST API and secure cookies.

Browser

React client and secure cookie session

Next.js frontend

Next.js frontend

App Router, React Query, Zustand

NestJS API

NestJS API

REST, RBAC, business modules

PostgreSQLPrisma

PostgreSQL / Prisma

RedisBullMQ

Redis / BullMQ workers

Cloudflare R2

R2 via FileStorageService

Google OIDCSMTPOpenAI

OIDC, SMTP, OpenAI, OTLP

The browser calls the NestJS API over REST. PostgreSQL owns durable relational state; Redis and BullMQ carry background transfer work; a provider-neutral storage boundary currently targets Cloudflare R2.

Signals without coupling

OpenTelemetry, Prometheus, Grafana, and Loki

OpenTelemetry is optional: PayLens keeps serving requests and Pino keeps writing to stdout when the collector, Loki, Tempo, Prometheus, or Grafana is unavailable.

Application logs

Signal 01

Application logs

Pino writes every sanitized event to stdout first, then makes an asynchronous OTLP copy for Loki when a collector is configured.

PINO → STDOUT + LOKI

Distributed traces

Signal 02

Distributed traces

HTTP, service, Prisma, Redis, BullMQ, and SMTP spans travel through OTLP to Tempo with trace correlation preserved.

OTEL → TEMPO

Service metrics

Signal 03

Service metrics

HTTP count, error, and duration metrics reach the collector. Prometheus scrapes its exporter; Grafana turns them into dashboards and alerts.

OTEL → PROMETHEUS

ONE OPTIONAL OTLP CONNECTION

PAYLENS API → OTLP / 4318 → COLLECTOR → LOKI · TEMPO · PROMETHEUS → GRAFANA

01 · Point PayLens at the collector

Deploy an OpenTelemetry Collector reachable from the API and give it its OTLP HTTP endpoint. This is the only PayLens telemetry setting required for traces, metrics, and the secondary log sink.

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318

02 · Route and visualize the signals

  1. A. Configure the collector to receive OTLP/HTTP on port 4318 and export logs to Loki and traces to Tempo.
  2. B. Enable the collector's Prometheus exporter and have Prometheus scrape that exporter endpoint. PayLens deliberately does not expose a separate in-process /metrics scrape endpoint.
  3. C. Add Loki, Tempo, and Prometheus as Grafana data sources. Search a Pino event by requestIdor traceId, then open its Tempo trace or Prometheus chart.

Failure isolation: OTLP uses bounded asynchronous batches with timeouts. A full queue or unreachable collector may drop only the remote copy and produces throttled diagnostics; it never blocks HTTP, seed execution, or terminal logging. Secrets are sanitized before either sink receives an event.

irtuyfjkikm

Product surface

What PayLens does

Multi-tenant operations

Organizations, active membership roles, secure switching, credential auth, verification, recovery, and Google OIDC.

Workforce records

Tenant-scoped employee directory, departments, profiles, and guarded CRUD.

Compensation integrity

Current pay, effective-dated history, decimal precision, audit timeline, idempotent retries, and version conflict protection.

Employee data transfer

CSV/XLSX import and export through background jobs, review/apply, pause/resume/cancel, and private artifacts.

Tools with intent

Technology stack

The stack favors one durable tool per responsibility rather than a broad dependency collection.

Next.js

Frontend

Next.js + React

App Router and TypeScript provide the product shell; React Query makes server state authoritative; Zustand holds small client-only concerns; Axios owns HTTP; Radix/Tailwind/Lucide keep accessible primitives consistent.

Component system

The internal PayLens showcase validates reusable primitives, theme states, typography, controls, surfaces, and feedback patterns so product screens do not drift into one-off styling.

Explore the PayLens Component Showcase
NestJSPostgreSQL

Backend

NestJS + PostgreSQL

NodeNext ESM NestJS modules provide REST and Swagger. Prisma 6.19 maps relational state. Redis/ioredis/BullMQ run asynchronous work. Pino plus OpenTelemetry preserve observability without coupling request success to telemetry.

ExcelJS and CSV parsers handle interchange; Argon2id, secure cookies, Helmet, throttling, and Google OIDC support protected access.

OpenAI

Advisory intelligence

OpenAI

Used only during Employee Import to suggest mappings for unresolved Department labels after deterministic matching is exhausted. It is not tenant authority and never writes employee data directly.

Invite member flow

  1. 01

    Open Members in the active workspace.

  2. 02

    Choose Invite member and assign a role.

  3. 03

    PayLens sends the recipient an invitation link.

  4. 04

    Recipient signs in or creates an account, then accepts.

  5. 05

    A scoped Organization Membership grants the chosen role.

This is optional for a reviewer, but it demonstrates that PayLens is genuinely multi-user and tenant-scoped—not a single-user employee database.

Multi-user workspace

Collaborating in a workspace

A workforce record and a person who can sign in are deliberately separate concepts.

Employees are not application users

An Employee is workforce data. A workspace User and OrganizationMembership represent a trusted collaborator who can sign in and manage that organization. Importing 10,000 Employees never creates 10,000 login accounts.

Explicit invitations, scoped authority

An organization administrator can invite an HR administrator, HR manager, or another organization administrator. The recipient authenticates or creates an account, accepts the invitation, receives an OrganizationMembership, and their role determines access.

Organization admin → invitation → recipient auth → acceptance → membership → role-based access

Performance decisions

Engineering optimizations

01

Tenant-first search

Decision: A tenant predicate precedes employee prefix search, using PostgreSQL functional B-tree and text_pattern_ops indexes where appropriate.

Impact: Search stays scoped and predictable as the directory grows.

02

Keyset pagination

Decision: Directory and history navigation use cursors rather than a growing OFFSET scan.

Impact: Stable large-data traversal without offset cost growth.

03

Bounded data transfer

Decision: Import/export workers use fixed batches, batched employee-number/email lookup maps, sequential NDJSON parts, and durable checkpoints.

Impact: No unbounded row memory or per-row lookup loop.

04

Async workers + R2 staging

Decision: BullMQ runs long CSV/XLSX work outside requests. Database state points to normalized R2 chunks before streamed final artifact generation.

Impact: Pause, retry, resume, and worker restart resilience without large Redis payloads.

05

Financial precision

Decision: Money crosses the API as decimal strings, persists as Decimal(19,2), and is handled with BigNumber on the client.

Impact: No JavaScript floating-point salary arithmetic.

06

Server-authoritative UI

Decision: React Query refetches jobs and entities after navigation or refresh; local UI state is never the transfer lifecycle source of truth.

Impact: Reliable recovery and less stale client state.

Boundary first

Security and multi-tenancy

The active membership and active organization are server-side authority. Client-supplied organization identity never grants access.

Tenant isolation

Employee, Department, Compensation, Import, and Export access is scoped to the active organization.

RBAC and session authority

Role checks operate on the active membership; secure cookie sessions rotate and revoke safely.

Private files

The bucket remains private. Requester-and-tenant scoped records issue short-lived signed upload/download URLs.

Advisory only

AI-assisted Employee Import

OpenAI is optional, advisory intelligence for the narrow case where deterministic Department matching cannot confidently resolve a human-entered label.

OpenAI

For example, Engg can be suggested as the tenant’s existing Engineering Department. PayLens normalizes the label and attempts an exact tenant-scoped match first; only unresolved or ambiguous Department labels and relevant existing Department names may be sent for a suggestion. Employee names, emails, numbers, compensation data, and complete CSV/XLSX files are not required for this task.

The suggestion appears in import review. User-approved validation resolves the final Department, and the apply phase uses that approved mapping. OpenAI does not select a tenant and does not directly mutate the database.

01

Imported Department label

02

Normalize + exact tenant match

03

OpenAI advisory suggestion only when unresolved

04

Review / resolve existing or new Department

05

Apply approved import

Deterministic first: exact normalized matches are cheaper, reproducible, lower latency, easier to test, and do not need an LLM.

Fail-soft by design: OPENAI_API_KEY is optional. If it is disabled, unavailable, times out, or returns unusable output, validation continues and unresolved mappings stay visible for manual resolution or creation.

Privacy boundary: PayLens does not expose employee personal data to OpenAI. It does not send employee names, work emails, employee numbers, compensation data, or complete CSV/XLSX files. Department-name suggestions need only unresolved Department labels and relevant existing Department names.

The advisory model is configurable through OPENAI_MODEL; no key or fixed model name is published here.

Scope discipline

What I deliberately did not build

REST, not GraphQL

Resource-oriented contracts and Swagger already fit the scope.

Modular monolith, not microservices

The operational distribution tax is not justified; workers can separate later.

BullMQ, not Kafka

Retries, pause/resume, and background jobs fit Redis/BullMQ directly.

Polling, not WebSockets

Human-scale transfer progress works reliably with short React Query polling.

PostgreSQL search, not Elasticsearch

Tenant-scoped prefix search is well served by indexed Postgres.

No FX conversion

Cross-currency salary aggregation would be misleading without a rate model.

Deterministic-first matching, not AI-first matching

Normalized tenant matches are reproducible and inexpensive. OpenAI is an optional advisory fallback for ambiguous Department labels; sending every import row to an LLM would add cost, latency, data exposure, and an unnecessary external dependency.

Independent deployables

Deployment topology

Frontend

Next standalone / Node 22

A separate non-root Node 22 bookworm-slim image runs the Next standalone output on port 3000. NEXT_PUBLIC_API_BASE_URL is a build-time public value.

Open frontend

Backend

Nest runtime / Node 24

A separate non-root Node 24 bookworm-slim image runs compiled NestJS on port 4000. Its entrypoint applies checked-in Prisma migrations before boot; PostgreSQL and Redis stay external. The OpenTelemetry loader is active.

Safe configuration

Environment variables

Frontend

NEXT_PUBLIC_API_BASE_URL is the browser-reachable API base including /api/v1. It is build-time and public: never put secrets in NEXT_PUBLIC_*.


NEXT_PUBLIC_API_BASE_URL=http://localhost:4000/api/v1
VariablePurposeContractSafe example
NODE_ENV / PORTRuntime mode and HTTP portRequiredproduction / 4000
DATABASE_URLPostgreSQL connection stringSECRET · requiredpostgresql://user:***@host/db
REDIS_URLRedis and BullMQ connectionSECRET · requiredredis://host:6379
FRONTEND_URLAllowed browser originRequiredhttps://paylens.shiplogly.com
AUTH_ACCESS_TOKEN_SECRETSession/JWT signing authoritySECRET · required32+ character placeholder
AUTH_COOKIE_SAME_SITECookie cross-site policyOptionallax
SMTP_URL / EMAIL_FROMProduction transactional emailSMTP_URL SECRET · production requiredsmtps://user:***@smtp
GOOGLE_CLIENT_ID / SECRET / CALLBACKGoogle OIDC, all-or-noneSecret group · optionalhttps://api.example.com/api/v1/auth/google/callback
OTEL_EXPORTER_OTLP_ENDPOINTOptional telemetry collectorOptionalhttp://localhost:4318
FILE_STORAGE_*Private S3-compatible artifactsEndpoint/key/secret/bucket all-or-none; production requiredhttps://storage.example.com
OPENAI_API_KEYEnables optional AI-assisted Department mapping during Employee ImportSECRET · optional***
OPENAI_MODELSelects the advisory mapping modelConfiguration · optionalConfigured by deployment
SEED_REVIEWER_DEMOEnables the public reviewer demo account bootstrap during deploymentBoolean · default false · not a secretfalse
REVIEWER_DEMO_PASSWORDPassword hashed into the reviewer demo User; required when SEED_REVIEWER_DEMO is trueCredential · disclosed to reviewers on this pageThereWeGoAgain@123

Reproducible setup

Local development

Prerequisites: Git, npm, PostgreSQL, Redis, and preferably Node 22 for frontend / Node 24 for backend.

Backend

git clone https://github.com/nandymandy1/paylens-server.git
cd paylens-server
npm ci
cp .env.example .env
npm run prisma:generate
npm run prisma:migrate
npm run seed
npm run dev

Configure DATABASE_URL, REDIS_URL, FRONTEND_URL, and a 32+ character auth secret. SMTP is optional locally; file storage is needed only when testing transfers.

Frontend

git clone https://github.com/nandymandy1/paylens-app.git
cd paylens-app
npm ci
cp .env.example .env.local
# NEXT_PUBLIC_API_BASE_URL=http://localhost:4000/api/v1
npm run dev

Open http://localhost:3000. Swagger is available locally at http://localhost:4000/api/docs.

Confidence

Quality, schema, and seed data

Frontend gates

npm run format:check
npm run lint
npm run typecheck
npm run test
npm run build

Backend gates

npm run format:check
npm run lint
npm run typecheck
npm run prisma:validate
npm run test
npm run test:integration
npm run test:e2e
npm run build

Prisma migrations are checked in and deployment uses prisma migrate deploy, never db push. The narrow reviewer bootstrap (seed:reviewer-demo) may run on boot when explicitly enabled; the full engineering seed (seed, seed:verify, seed:rollback) exercises multi-tenancy, large employee directories, departments, and safe demo flows without publishing account credentials.

CLI demo data

Seed 10,000 employees — and roll them back safely

SEED-R1 creates a deterministic local evaluation dataset. It is intentionally refused when NODE_ENV is production.

Create and verify

Run the local seed

# In paylens-server; never use NODE_ENV=production
export SEED_DEMO_PASSWORD='choose-a-local-demo-password'
npm run prisma:migrate
npm run seed
npm run seed:verify

The canonical paylens-demo workspace receives 10,000 employees and 16 Departments. The full deterministic seed also includes 30 organizations and 35 controlled portal users for realistic multi-tenant review.

Remove only SEED-R1 data

Run the guarded rollback

# In paylens-server
npm run seed:rollback

This is not a database reset. It removes only deterministic SEED-R1-owned rows; foreign rows or reserved-namespace collisions fail the operation safely rather than being deleted.

Deterministic + idempotent

Stable generated IDs, a fixed as-of date, ownership checks, and reconcile-on-rerun behavior.

Bounded database I/O

Employees, compensation, history, reconciliation, and rollback use 500-row batches.

Traceable verification

Each phase and batch emits timing spans; verification checks expected rows and a fingerprint.

Dependency-safe rollback

Sessions are blocked and revoked, then history → compensation → employees → departments → memberships/users → organizations.

Rollback deletes high-volume rows in 500-row bounded batches, checks that each major phase is empty before continuing, and does not wrap the entire deletion in one giant transaction. The advisory lock prevents a seed and rollback from running together.

A · Reviewer account bootstrap

npm run seed:reviewer-demo creates only Demo Company, the verified Demo User, and the owner membership. It is create-once and idempotent: reruns never touch reviewer workspace data. The assessment deployment runs it automatically through SEED_REVIEWER_DEMO=true.

B · Engineering local dataset

npm run seed builds the full deterministic development and test dataset (30 organizations, 10,000 employees). It remains blocked from NODE_ENV=production and never runs during deployment.

Reviewer path

Suggested 5-minute review

  1. 01Open /docs and review the architecture and technology stack.
  2. 02Open the login page, click “Use Demo Account”, and sign in with the public reviewer credentials.
  3. 03Create or select an organization workspace.
  4. 04Download the 10,000 Employee synthetic CSV.
  5. 05Open Employees → Import and upload the CSV.
  6. 06Review validation, Department resolution, and the Action Center progress.
  7. 07Confirm the import, then browse, search, and filter the Employee Directory.
  8. 08Review Departments, an Employee Profile, and Compensation safeguards.
  9. 09Export the dataset back to CSV or XLSX if desired.
  10. 010Optionally invite a second workspace user from Members to observe role-based access.
  11. 011Open Swagger, then inspect the frontend and backend repositories.
  12. 012Review engineering optimizations and deterministic-first AI trade-offs.
PayLens Action Center showing an employee import validating at 49 percent
Follow an import or export from the Action Center in the dashboard header. Active transfers show their current phase, live progress, and available pause or cancel actions; completed transfers remain available in Recent for download or review.

Builder

About the engineer

Narendra Maurya

Narendra Maurya

Full-stack and platform engineer focused on backend systems, product infrastructure, distributed workloads, product implementation, developer education, and media/localization experimentation.

Beyond PayLens

Other work

Engineering / products

Signalog

Customer feedback and product-operations platform combining bug reporting, feature requests, changelog/reactions, and automatic technical context capture.

Visit Signalog

Engineering / products

I-DACS / W.A.G.E.S.

Industrial infrastructure and resource-intelligence work spanning water, air, gas, electricity, steam, telemetry ingestion, integrations, automation, visualization, and edge workflows.

Visit I-DACS

Media / localization

From Networks

A media/localization platform exploring Hindi-language adaptation, multilingual audiences, creator partnerships, content production workflows, and distribution operations.

Visit From Networks

Media / education

The Codebook Inc.

Programming-focused YouTube channel publishing software development tutorials and technical educational content.

Watch The Codebook

PayLens engineering

Ready for a closer look?