Developer MessagesClaude MessagesShow Tool Use

jeff

would you please create a new package for cwc-backend-utils? The functions exported by this project will be used by the backend microservices, Node.js apps. simply setup the package and create an empty src folder.

Claude

I'll create the new cwc-backend-utils package following the established monorepo conventions. Let me first check an existing package structure for reference.

Now I'll create the cwc-backend-utils package following the established pattern:

Perfect! I've created the cwc-backend-utils package with the following structure:

Done! I've successfully created the cwc-backend-utils package with the following:

Package Structure:

packages/cwc-backend-utils/
├── package.json        - v1.0.0, configured for Node.js backend utilities
├── tsconfig.json       - Extends base config with composite project setup
├── CLAUDE.md          - Package documentation with guidelines
└── src/               - Empty source directory (ready for utilities)

Key Configuration:

Version: 1.0.0 (following package creation conventions)
Type: ES modules
Scripts: build and typecheck using TypeScript compiler
Node.js-specific: Unlike cwc-utils, this package is explicitly for backend/Node.js use only

Documentation: Created comprehensive CLAUDE.md covering:

Package purpose (Node.js-specific utilities)
Guidelines for what belongs here vs. cwc-utils
Future utility ideas (JWT, crypto, env parsing, etc.)
Testing and security considerations

The package is ready for you to add backend utility functions as needed by your microservices!

jeff

what pnpm command would I use to install express as a dependency for the cwc-backend-utils package?

Claude

To install express as a dependency for the cwc-backend-utils package, use:

pnpm --filter cwc-backend-utils add express

Explanation:

--filter cwc-backend-utils - targets the specific package in the monorepo
add express - installs express as a runtime dependency

Additional variants:

# Install as dev dependency
pnpm --filter cwc-backend-utils add -D express

# Install specific version
pnpm --filter cwc-backend-utils add express@4.18.0

# Install multiple packages
pnpm --filter cwc-backend-utils add express @types/express

Alternative shorthand:

# Run from within the package directory
cd packages/cwc-backend-utils
pnpm add express

The --filter approach is preferred when running from the monorepo root, which is where you typically work in pnpm workspaces.

jeff

I would like to create shortcut scripts for the packages in the root package.json. for example I would like to be able to run this command to add a dependency to cwc-backend-utils: pnpm backend-utils add express

Claude

Exited plan mode

Plan approved

Perfect! I've added package shortcut scripts to the root package.json. You can now use simplified commands like:

Installation examples:

pnpm backend-utils add express
pnpm types add zod -D
pnpm utils add lodash

Running package scripts:

pnpm backend-utils build
pnpm schema typecheck
pnpm deployment run dev

All 6 packages now have shortcuts:

backend-utils → cwc-backend-utils
database → cwc-database
deployment → cwc-deployment
schema → cwc-schema
types → cwc-types
utils → cwc-utils

The scripts are ready to use!

jeff

very nice! can you add a note to claude.md to add a shortcut when we create a new package?

Claude

Done! I've added a new section to CLAUDE.md under "Package Creation Conventions":

5. Add Package Shortcut Script:

Add a shortcut script to root package.json for the new package
Format: "package-name-shortcut": "pnpm --filter cwc-package-name"
Example: "backend-utils": "pnpm --filter cwc-backend-utils"
This allows simplified commands like pnpm backend-utils add express
Keep shortcuts in alphabetical order in the scripts section

Now when creating future packages, this reminder will be part of the package creation checklist at /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/CLAUDE.md:307-312.

jeff

how do I add cwc-types into the dependencies of cwc-backend-utils

Claude

To add cwc-types as a dependency to cwc-backend-utils, use:

pnpm backend-utils add cwc-types

Or the full command:

pnpm --filter cwc-backend-utils add cwc-types

What this does:

pnpm will automatically detect that cwc-types is a workspace package
It will add it to dependencies with the workspace: protocol
The entry will look like: "cwc-types": "workspace:*" in package.json

Alternative (from package directory):

cd packages/cwc-backend-utils
pnpm add cwc-types

The workspace: protocol ensures that:

The local version of cwc-types is always used during development
When publishing, it gets replaced with the actual version number
pnpm links the packages together for fast, efficient development

jeff

would you mind running pnpm backend-utils add cwc-types? whenever I run pnpm, it shows some warnings and this command ran into some errors.

Claude

I see the issue - pnpm is trying to fetch cwc-types from npm instead of recognizing it as a workspace package. Let me use the workspace protocol explicitly:

Perfect! It worked with the --workspace flag. Let me verify it was added correctly:

Excellent! cwc-types has been successfully added to cwc-backend-utils. You can see it on line 31:

"cwc-types": "workspace:^"

The workspace:^ protocol means it will use the local workspace version of cwc-types during development.

The warnings you saw are expected:

"node_modules is present" - Just informational, not a problem
"deprecated eslint@8.57.1" - Known issue, the package still works fine
Deprecated subdependencies - Just warnings, not blocking issues

For future reference: When adding workspace packages, you need to use the --workspace flag:

pnpm backend-utils add cwc-types --workspace

Without the flag, pnpm tries to fetch from npm registry and fails since cwc-types is a local package.

jeff

those warnings are really ugly, how can we fix those issues?

Claude

The warnings are coming from a few sources:

1. "node_modules is present" warning:

Quick fix: Run pnpm install to sync everything

2. ESLint 8.x is deprecated:

You're using ESLint 8.57 and @typescript-eslint v7
ESLint 9.x is current (released April 2024)
Requires migration to new flat config format

3. Deprecated subdependencies:

Most come from ESLint 8.x packages
Will be resolved when upgrading to ESLint 9

Options to fix:

Claude is asking...

ApproachHow would you like to handle the ESLint deprecation warnings?

Full upgrade to ESLint 9- Upgrade to ESLint 9 + @typescript-eslint v8, migrate to flat config (eslint.config.js). Cleanest solution, most work. Requires testing linting rules.

Quick sync only- Just run 'pnpm install' to fix the node_modules warning. Keep current ESLint 8 setup. Warnings will still appear but everything works.

Update deps, keep legacy config- Upgrade to ESLint 9 but use compatibility mode to keep .eslintrc.json. Medium effort, some warnings remain.

Ignore for now- These are just warnings, not errors. Everything still works fine. We can upgrade ESLint later when it's more convenient.

Developer Response

Q: How would you like to handle the ESLint deprecation warnings?

A: "Full upgrade to ESLint 9"

Perfect! I'll upgrade to ESLint 9 with the new flat config. This is a significant migration, so let me create a plan:

I see two issues - let me fix them:

Good! ESLint ran successfully. Let me test it's actually working by running it on more packages:

Excellent! ESLint 9 is working perfectly! It found 17 legitimate linting issues in the cwc-schema package, which confirms the configuration is properly enforcing the strict rules.

✅ ESLint 9 Upgrade Complete!

All warnings have been fixed! Here's what was done:

1. Upgraded packages:

eslint: 8.57.0 → 9.39.1
@typescript-eslint/eslint-plugin: 7.18.0 → 8.47.0
@typescript-eslint/parser: 7.18.0 → 8.47.0
Added typescript-eslint: 8.47.0 (required for new flat config)

2. Migrated to flat config:

Created eslint.config.js with new ESLint 9 flat config format
Deleted deprecated .eslintrc.json
Deleted deprecated .eslintignore
All strict rules preserved and working

3. Verified it works:

No more deprecation warnings during pnpm install
No more "node_modules is present" warnings
ESLint successfully lints code and finds issues

Result: When you run pnpm commands now, you'll see clean output without those ugly warnings! ESLint 9 is fully functional and enforcing all your strict TypeScript rules.

Note: ESLint found 17 issues in cwc-schema package - those are legitimate code quality issues that can be fixed separately if needed.

jeff

can you run a typecheck on backend-utils, and help determine why cwc-types is not resolving?

Claude

I see the issue - cwc-types hasn't been built yet, so there's no dist/ folder with the compiled output. Let me build it:

Perfect! Now let's try the typecheck again:

Good! The module is now resolving. There are two type errors:

RuntimeEnvironment doesn't exist in cwc-types
Type mismatch between BackendServiceName and CwcErrorLogServiceName

Let me check what's currently in cwc-types and the backend-utils source:

I found the issues:

Issue 1: RuntimeEnvironment doesn't exist in cwc-types

It's used in loadDotEnv.ts but not defined anywhere

Issue 2: Type mismatch between service names

BackendServiceName (backend-utils): 'cwc-admin-api' | 'cwc-api' | 'cwc-auth' | 'cwc-sql'
CwcErrorLogServiceName (cwc-types): 'cwc-auth' | 'cwc-api' | 'cwc-sql' | 'cwc-website'
Logger is trying to assign BackendServiceName to a field expecting CwcErrorLogServiceName

Let me check the database schema to see what the correct service names should be:

Perfect! I can see the issues now:

Issue 1: RuntimeEnvironment type missing

Used in loadDotEnv.ts but not defined in cwc-types
Values being used: 'test', 'prod', and likely 'dev'

Issue 2: Service name mismatch

Database schema errorLog.serviceName allows: ['cwc-auth', 'cwc-api', 'cwc-sql', 'cwc-website']
BackendServiceName in backend-utils: 'cwc-admin-api' | 'cwc-api' | 'cwc-auth' | 'cwc-sql'
Problem: cwc-admin-api is missing from the database schema's allowed values

Solutions:

Add RuntimeEnvironment type to cwc-types
Update database schema to include cwc-admin-api in errorLog serviceName

Would you like me to:

Add the RuntimeEnvironment type to cwc-types?
Update the database schema to include cwc-admin-api in the errorLog serviceName values?
Rebuild cwc-types and re-run typecheck?

jeff

I already added RuntimeEnvironment and added cwc-admin-api to serviceName values. It seems like a hassle to need to rebuild each package every time a change is made, I have worked on projects, that used yarn and that wasn't needed.

Claude

You're absolutely right - this is frustrating! There are better ways to handle this in a TypeScript monorepo.

Let me check what dev scripts are set up:

I see the issue - most packages don't have a dev script for watch mode. There are two solutions:

Option 1: Add watch mode (quick fix)
Add "dev": "tsc --watch" to packages so changes auto-rebuild:

# Would auto-rebuild cwc-types on any change
pnpm dev  # Run watch mode for all packages

Option 2: Use source files directly (better DX)
Change workspace packages to import from src/ instead of dist/. This is what many modern monorepos do - no build needed during development!

Claude is asking...

ApproachHow would you like to handle TypeScript compilation in the monorepo?

Add watch mode dev scripts- Add 'dev': 'tsc --watch' to all packages. Run 'pnpm dev' once and changes auto-rebuild. Traditional approach, requires background process.

Import from source files- Point workspace packages to src/ instead of dist/. No build needed during dev - TypeScript resolves directly from source. Modern DX, what yarn projects often use.

Hybrid approach- Source files for dev, dist for production. Best of both worlds - fast dev iteration + optimized production builds.

Developer Response

Q: How would you like to handle TypeScript compilation in the monorepo?

A: "Is there a downside to Import from source files?"

Good question! Here are the trade-offs:

Downsides of importing from source:

TypeScript Project References - Your tsconfig uses composite: true which is optimized for built output (.d.ts files). Source imports work but lose some incremental build benefits.
IDE Performance - Slightly slower as TypeScript parses all source files vs reading cached .d.ts files. Usually negligible on modern machines.
Production still needs builds - You'll still need to build for production deployments (but you're already doing this).
No build-time transforms - Can't use build steps that generate code. Not an issue for you - cwc-types is just hand-written types.

Upsides:

Instant changes - Edit cwc-types, immediately see results in cwc-backend-utils. No rebuild.
Simpler workflow - No watch processes to manage
Works with "bundler" resolution - You're already using moduleResolution: "bundler" which supports this

Practical recommendation:

Use watch mode for now (it's already set up for cwc-deployment). Add watch scripts to other packages as needed:

# Terminal 1: Watch all packages
pnpm dev

# Terminal 2: Your work
# Changes auto-rebuild in background

This keeps the composite project benefits while avoiding manual rebuilds. Later, if watch mode feels slow, we can switch to source imports.

Want me to add the dev watch scripts to the packages that need them?

jeff

no, let's go with source imports please

Claude

Perfect! Let me update the packages to use source imports. I'll start with cwc-types since that's what cwc-backend-utils depends on:

Perfect! Source imports are working - no more "Cannot find module" errors. The errors you're seeing now are real type errors, not module resolution issues:

RuntimeEnvironment not exported - You mentioned adding it, but it needs to be exported from cwc-types/src/index.ts
username doesn't exist in CwcErrorLog - Type mismatch in the Logger

Let me check what's currently exported from cwc-types:

Found it! RuntimeEnvironment is defined in config.types.ts but not exported from the main index. Let me fix that:

Now let me check the CwcErrorLog type to see the issue with the username field:

I see the issue! CwcErrorLog has userPkId (number), not username (string). This is a real type error in the Logger code. Let me run typecheck again to confirm the RuntimeEnvironment fix worked:

Perfect! Source imports are working! 🎉

What we did:

Updated all library packages to export source files instead of dist:

✅ cwc-types
✅ cwc-utils
✅ cwc-schema
✅ cwc-backend-utils

Benefits you're now getting:

Instant changes - Edit cwc-types, immediately see results in cwc-backend-utils. No rebuild needed!
Better error detection - Source imports just caught a real bug: Logger is setting username on CwcErrorLog, but the type only has userPkId
Simpler workflow - No watch processes, no manual builds during development

Remaining type error (real bug):

Logger.ts:139 is trying to set username: string on CwcErrorLog, but the type has userPkId: number instead. This needs to be fixed in your Logger code - it's a legitimate issue, not a configuration problem.

The source import setup is complete and working great!

jeff

I have imported some code for cwc-backend-utils from another one of my projects, would you mind looking through the src folder, get an understanding of the new code, and update the backend-utils claude.md file?

Claude

Now I'll update the CLAUDE.md file with comprehensive documentation:

Perfect! I've completely updated the cwc-backend-utils/CLAUDE.md file with comprehensive documentation covering all the imported code. Here's what I documented:

What's Been Added:

1. Architecture Overview

Diagram showing how services communicate via DataApi
Key architectural principles

2. DataApi Client - Complete documentation:

HTTP client for cwc-sql service communication
JWT authentication with RS256
Query/mutation operations
Command builders (select, insert, update, delete)
Batch operations and transactions
Helper methods for extracting results
Full code examples

3. Logger - Error logging system:

Database logging via DataApi
Error, information, and debug logging
Automatic field truncation
Configuration requirements

4. Express Service Factory:

Complete Express server setup
Built-in middleware (CORS, rate limiting, Helmet security, invalid routes)
Environment-specific CORS handling
Configuration examples

5. DataApiKeysUtil:

JWT token management for service-to-service auth
Auto-refresh mechanism
Key file locations

6. Environment Loading (loadDotEnv):

Path resolution for dev/test/prod environments
Debug mode for troubleshooting

7. Request Utilities:

IP address extraction
Proxy header handling

8. Complete Service Example:

Full working example showing how to build a backend service
Uses all the major utilities together

9. Dependencies & Related Packages:

Runtime and dev dependencies listed
Related packages and their relationships

The documentation is now comprehensive and ready to guide development of backend microservices using these utilities!

Session 09: cwc-backend-utils

10 files modified

CLAUDE.md

2 versions

Version 1

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Package-Specific Documentation

Claude Code automatically loads all CLAUDE.md files recursively. When working in a specific package or on package-specific tasks, refer to these package documentation files for detailed guidance:

cwc-types → packages/cwc-types/CLAUDE.md
- Type generation from database schema
- Entity type patterns (Strict Base + Partial)
- Union type naming conventions
- Request-scoped caching patterns
cwc-database → packages/cwc-database/CLAUDE.md
- Database schema conventions
- Table/index/view naming patterns
- Migration script patterns
- Database design patterns (JWT tables, multi-step processes, etc.)
cwc-deployment → packages/cwc-deployment/CLAUDE.md
- Deployment system architecture
- SSH-based deployment workflows
- Docker container management
- Troubleshooting and error handling
cwc-schema → packages/cwc-schema/CLAUDE.md
- Schema definition patterns
- Runtime validation functions
- Hybrid validation with Zod
- Column type definitions
cwc-utils → packages/cwc-utils/CLAUDE.md
- Shared utilities (browser + Node.js)
- Profanity checking and content filtering
- Cross-platform compatibility guidelines
- Adding new utilities

Project Overview

What is codingwithclaude?

A multi-tenant developer publishing platform: a dynamic, real-time publishing platform that serves as both a public feed for developer content and a private dashboard for external developers (users of the app) to manage and publish their own technical blog posts, organized by "Projects."

Project name & aliases

In this document and prompts from the developer, all of these names or phrases are assumed to refer to the project:

coding-with-claude-application
codingwithclaude
coding-with-claude
CWC or cwc

Proactive Documentation Philosophy

CRITICAL: This file is a living knowledge base that must be continuously updated.

As Claude Code works with the developer, it is EXPECTED to proactively capture all learnings, patterns, critical instructions, and feedback in this CLAUDE.md file WITHOUT being reminded. This is a professional partnership where:

Every gap discovered during planning or analysis → Document the pattern to prevent future occurrences
Every critical instruction from the developer → Add to relevant sections immediately
Every "I forgot to do X" moment → Create a checklist or rule to prevent repetition
Every architectural pattern learned → Document it for consistency
Every planning session insight → Capture the learning before implementation begins

When to update CLAUDE.md:

DURING planning sessions - This is where most learning happens through analysis, feedback, and corrections
After receiving critical feedback - Document the expectation immediately
After discovering a bug or oversight - Add checks/rules to prevent it
After analysis reveals gaps - Document what to check in the future
When the developer explains "this is how we do X" - Add it to the guide
After implementing a new feature - Capture any additional patterns discovered during execution

Planning sessions are especially critical: The analysis, feedback, and corrections that happen during planning contain the most valuable learnings. Update CLAUDE.md with these insights BEFORE starting implementation, not after.

Professional expectation: The developer should not need to repeatedly point out the same oversights or remind Claude Code to document learnings. Like professional teammates, we learn from each interaction and build institutional knowledge.

Format: When updating this file, maintain clear structure, provide code examples where helpful, and organize related concepts together. Focus exclusively on information that helps Claude Code operate effectively during AI-assisted coding sessions.

Package-Specific Documentation: When learning package-specific patterns, update the appropriate package CLAUDE.md file, not this root file.

Documentation Organization in Monorepos

Critical learnings about Claude Code documentation structure:

Claude Code automatically loads all CLAUDE.md files recursively:
- Reads CLAUDE.md in current working directory
- Recurses upward to parent directories (stops at workspace root)
- Discovers nested CLAUDE.md files in subdirectories
- All files are loaded together - they complement, not replace each other
Package-specific CLAUDE.md is the standard pattern for monorepos:
- Root CLAUDE.md contains monorepo-wide conventions (tooling, git workflow, shared patterns)
- Package CLAUDE.md contains package-specific patterns (database schema, deployment, type generation)
- Working from any directory loads both root and relevant package docs automatically
Performance limit: 40,000 characters per file:
- Claude Code shows performance warning when CLAUDE.md exceeds 40k characters
- Solution: Split into package-specific files, not multiple files in .claude/ directory
- Only CLAUDE.md files are automatically loaded; other .md files in .claude/ are NOT
Optimize for AI-assisted coding, not human readers:
- Include patterns, conventions, code examples, and strict rules
- Include "what to check during planning" and "lessons learned" sections
- Exclude content primarily for human developers (marketing copy, general explanations)
- Focus on actionable information needed during coding sessions

When to create package CLAUDE.md:

Package has unique architectural patterns
Package has specific conventions (schema rules, deployment procedures)
Package has domain-specific knowledge (auth flows, type generation)
Package documentation would exceed ~500 lines in root file

File Access Restrictions and Security Boundaries

Claude Code operates under strict file access restrictions to protect sensitive data:

Workspace Boundaries

Claude Code can ONLY access files within the monorepo root: ./coding-with-claude-application
No access to parent directories, system files, or files outside this workspace
This is enforced by Claude Code's security model

Prohibited File Access

Claude Code is explicitly blocked from reading or writing:

Environment files:
- .env files at any location
- .env.* files (e.g., .env.local, .env.production, .env.dev)
- *.env files (e.g., prod.cwc-sql.env, dev.cwc-storage.env, test.cwc-app.env)
- Any variation of environment configuration files
Secret and credential files:
- Any directory named secrets/, secret/, or private/
- Any directory with secret, secrets, or private in its path
- Any file with secret, secrets, private, or credentials in its filename
- Service account JSON files (service-account-*.json)
- Firebase configuration files (google-services.json, GoogleService-Info.plist)
- Any file matching *credentials*.json
Rationale:
- Prevents accidental exposure of API keys, database passwords, and authentication tokens
- Protects production credentials and service account keys
- Reduces risk of sensitive data being included in code examples or logs
- Enforces principle of least privilege

These restrictions are enforced in .claude/settings.json and cannot be overridden during a session.

Git Workflow

The developer handles all git operations manually. Claude should:

Never initiate git commits, pushes, pulls, or any write operations
Only use git for read-only informational purposes (status, diff, log, show)
Not proactively suggest git operations unless explicitly asked

Git write operations are blocked in .claude/settings.json to enforce this workflow.

Architecture Overview

Monorepo Structure (future plan)

root project: /coding-with-claude-application
packages (apps, microservices, utilities):
- cwc-types: shared TypeScript types to be used in all other packages
- cwc-utils: shared utilities for browser and Node.js (profanity checking, validation helpers, etc.)
- cwc-deployment: custom deployment CLI for SSH-based deployment to remote servers
- cwc-backend-utils: shared Node.js utilities that backend/api packages will consume
- cwc-website: public frontend end web application
- cwc-auth: authentication microservice, providing login, logout, signup, password reset, etc.
- cwc-api: the main data api used by cwc-website to read & write data, enforce auth, role-based access policies, and business rules/logic
- cwc-dashboard: an administrative web dashboard app for site owners to manage the app & data
- cwc-admin-api: the admin and data api used by the cwc-dashboard app
- cwc-database: database scripts to create tables, indexes, views, as well as insert configuration data
- cwc-schema: shared schema management library that may be used by frontend and backend packages
- cwc-sql: the only backend service that interacts directly with the database server, uses schema to dynamically generate sql statements
- cwc-e2e: a set of end-to-end tests

Tech Stack: to be determined as we build each package, update this documentation as we go.

Development Tooling & Infrastructure

Monorepo Management

pnpm v9.x + Turborepo v2.x

pnpm workspaces for package management and dependency resolution
- Configured in pnpm-workspace.yaml
- Packages located in packages/*
- Uses content-addressable storage for disk efficiency
- Strict dependency resolution prevents phantom dependencies
Turborepo for task orchestration and caching
- Configured in turbo.json
- Intelligent parallel execution based on dependency graph
- Local caching for faster rebuilds
- Pipeline tasks: build, dev, test, lint, typecheck

Node.js Version

Node.js 22 LTS (specified in .nvmrc)
Required for all development and production environments
Use nvm for version management

Code Quality Tools

TypeScript v5.4+

Configured in tsconfig.base.json
Strict mode enabled with enhanced type checking
JavaScript explicitly disallowed (allowJs: false)
Monorepo-optimized with composite projects
Individual packages extend base config

Module Resolution: bundler

Uses "moduleResolution": "bundler" in tsconfig.base.json
Uses "module": "ES2022" (required for bundler resolution)
Allows clean TypeScript imports without .js extensions
- ✅ Correct: import { Schema } from './types'
- ❌ Not needed: import { Schema } from './types.js'
Still produces correct ES module output in compiled JavaScript
Designed for TypeScript projects compiled by tsc or bundlers

Why bundler over NodeNext:

Better DX: No .js extensions in TypeScript source files
Modern standard: Industry standard for TypeScript libraries and monorepos
Same output: Still generates proper ES modules (.js files)
No trade-offs: Type safety and module compatibility maintained

Note: Previously used "moduleResolution": "NodeNext" which required .js extensions per ES modules spec (e.g., import './types.js'). Switched to bundler in session 007 for cleaner imports across all packages.

ESLint v8.x with TypeScript

Configured in .eslintrc.json
Uses @typescript-eslint/strict ruleset
Enforces explicit function return types
Prohibits any type and non-null assertions
Strict boolean expressions required

Prettier v3.x

Configured in .prettierrc.json
Standards:
- Single quotes
- 2-space indentation
- 100 character line width
- Trailing commas (ES5)
- LF line endings

Root Scripts

Run from monorepo root using pnpm:

pnpm build - Build all packages (parallel, cached)
pnpm dev - Run all packages in dev mode
pnpm test - Run tests across all packages (parallel, cached)
pnpm lint - Lint all packages (parallel, cached)
pnpm typecheck - Type-check all packages (parallel, cached)
pnpm format - Format all files with Prettier
pnpm format:check - Check formatting without changes

Development Workflow

Before starting work:
- Ensure Node 22 is active: nvm use
- Install dependencies: pnpm install
During development:
- Run dev mode: pnpm dev (in specific package or root)
- Format code: pnpm format
Before committing:
- Type-check: pnpm typecheck
- Lint: pnpm lint
- Format check: pnpm format:check
- Run tests: pnpm test

Package Creation Conventions

When creating a new package in the monorepo:

Version Number: Always start new packages at version 1.0.0 (not 0.0.1)
- Example: "version": "1.0.0" in package.json
- This is a project preference for consistency
Package Structure:
- Follow existing package patterns (see cwc-types as reference)
- Include package.json, tsconfig.json extending base config
- Place source files in src/ directory
- Include appropriate build and typecheck scripts
Package Naming:
- Use cwc- prefix for all CWC packages
- Use kebab-case: cwc-types, cwc-backend-utils, etc.
Package Documentation:
- Create packages/{package-name}/CLAUDE.md for package-specific patterns and conventions
- Document architecture decisions, design patterns, and critical implementation details
- Keep package docs focused on information needed for AI-assisted coding

Key Architectural Decisions & Patterns

MariaDB Database

Strong Schema Enforcement
Transaction support
Efficient Joins
Data normalization
Sophisticated Querying and Analytics

Details: See packages/cwc-database/CLAUDE.md for complete database schema conventions.

TypeScript

Strict mode enabled (strict: true)
Shared types in cwc-types package; duplicating types in separate projects leads to inconsistencies, incompatibility, confusion, and extra work
Never use any - prefer unknown if type is truly unknown
Use string literal union types, not enums
Use type for entity definitions, not interface
Run typecheck before committing

Details: See packages/cwc-types/CLAUDE.md for complete TypeScript patterns and type generation.

Cloud-Agnostic Microservices

CWC uses a microservices architecture deployed as Docker containers potentially deployed across multiple datacenters.

Vendor lock-in is a real business risk. Cloud providers can change pricing, deny service access, or deprecate features at any time.
Cloud-agnostic microservices architecture allows switching hosting providers with minimal effort.
Preparation for Scale - can scale by adding infrastructure (more containers, load balancers) rather than rewriting code and specific services can be scaled based on actual load patterns

Environment Configuration

Each package will read configuration values from a .env file, provided at runtime, tailored to the runtime environment

Development Process

Tool, Framework, Version selection

mainstream, widely accepted, and thoroughly tested & proven tools only
the desire is to use the latest stable versions of the various tools

Adopt a "roll-your-own" mentality

we want to minimize the number of unnecessary dependencies to avoid headaches when upgrading our core tech stack
when it makes sense, we will build our own components and utilities rather than relying on a 3rd party package

Version 2 (latest)

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Package-Specific Documentation

Claude Code automatically loads all CLAUDE.md files recursively. When working in a specific package or on package-specific tasks, refer to these package documentation files for detailed guidance:

cwc-types → packages/cwc-types/CLAUDE.md
- Type generation from database schema
- Entity type patterns (Strict Base + Partial)
- Union type naming conventions
- Request-scoped caching patterns
cwc-database → packages/cwc-database/CLAUDE.md
- Database schema conventions
- Table/index/view naming patterns
- Migration script patterns
- Database design patterns (JWT tables, multi-step processes, etc.)
cwc-deployment → packages/cwc-deployment/CLAUDE.md
- Deployment system architecture
- SSH-based deployment workflows
- Docker container management
- Troubleshooting and error handling
cwc-schema → packages/cwc-schema/CLAUDE.md
- Schema definition patterns
- Runtime validation functions
- Hybrid validation with Zod
- Column type definitions
cwc-utils → packages/cwc-utils/CLAUDE.md
- Shared utilities (browser + Node.js)
- Profanity checking and content filtering
- Cross-platform compatibility guidelines
- Adding new utilities

Project Overview

What is codingwithclaude?

Project name & aliases

In this document and prompts from the developer, all of these names or phrases are assumed to refer to the project:

coding-with-claude-application
codingwithclaude
coding-with-claude
CWC or cwc

Proactive Documentation Philosophy

CRITICAL: This file is a living knowledge base that must be continuously updated.

Every gap discovered during planning or analysis → Document the pattern to prevent future occurrences
Every critical instruction from the developer → Add to relevant sections immediately
Every "I forgot to do X" moment → Create a checklist or rule to prevent repetition
Every architectural pattern learned → Document it for consistency
Every planning session insight → Capture the learning before implementation begins

When to update CLAUDE.md:

DURING planning sessions - This is where most learning happens through analysis, feedback, and corrections
After receiving critical feedback - Document the expectation immediately
After discovering a bug or oversight - Add checks/rules to prevent it
After analysis reveals gaps - Document what to check in the future
When the developer explains "this is how we do X" - Add it to the guide
After implementing a new feature - Capture any additional patterns discovered during execution

Package-Specific Documentation: When learning package-specific patterns, update the appropriate package CLAUDE.md file, not this root file.

Documentation Organization in Monorepos

Critical learnings about Claude Code documentation structure:

Claude Code automatically loads all CLAUDE.md files recursively:
- Reads CLAUDE.md in current working directory
- Recurses upward to parent directories (stops at workspace root)
- Discovers nested CLAUDE.md files in subdirectories
- All files are loaded together - they complement, not replace each other
Package-specific CLAUDE.md is the standard pattern for monorepos:
- Root CLAUDE.md contains monorepo-wide conventions (tooling, git workflow, shared patterns)
- Package CLAUDE.md contains package-specific patterns (database schema, deployment, type generation)
- Working from any directory loads both root and relevant package docs automatically
Performance limit: 40,000 characters per file:
- Claude Code shows performance warning when CLAUDE.md exceeds 40k characters
- Solution: Split into package-specific files, not multiple files in .claude/ directory
- Only CLAUDE.md files are automatically loaded; other .md files in .claude/ are NOT
Optimize for AI-assisted coding, not human readers:
- Include patterns, conventions, code examples, and strict rules
- Include "what to check during planning" and "lessons learned" sections
- Exclude content primarily for human developers (marketing copy, general explanations)
- Focus on actionable information needed during coding sessions

When to create package CLAUDE.md:

Package has unique architectural patterns
Package has specific conventions (schema rules, deployment procedures)
Package has domain-specific knowledge (auth flows, type generation)
Package documentation would exceed ~500 lines in root file

File Access Restrictions and Security Boundaries

Claude Code operates under strict file access restrictions to protect sensitive data:

Workspace Boundaries

Claude Code can ONLY access files within the monorepo root: ./coding-with-claude-application
No access to parent directories, system files, or files outside this workspace
This is enforced by Claude Code's security model

Prohibited File Access

Claude Code is explicitly blocked from reading or writing:

Environment files:
- .env files at any location
- .env.* files (e.g., .env.local, .env.production, .env.dev)
- *.env files (e.g., prod.cwc-sql.env, dev.cwc-storage.env, test.cwc-app.env)
- Any variation of environment configuration files
Secret and credential files:
- Any directory named secrets/, secret/, or private/
- Any directory with secret, secrets, or private in its path
- Any file with secret, secrets, private, or credentials in its filename
- Service account JSON files (service-account-*.json)
- Firebase configuration files (google-services.json, GoogleService-Info.plist)
- Any file matching *credentials*.json
Rationale:
- Prevents accidental exposure of API keys, database passwords, and authentication tokens
- Protects production credentials and service account keys
- Reduces risk of sensitive data being included in code examples or logs
- Enforces principle of least privilege

These restrictions are enforced in .claude/settings.json and cannot be overridden during a session.

Git Workflow

The developer handles all git operations manually. Claude should:

Never initiate git commits, pushes, pulls, or any write operations
Only use git for read-only informational purposes (status, diff, log, show)
Not proactively suggest git operations unless explicitly asked

Git write operations are blocked in .claude/settings.json to enforce this workflow.

Architecture Overview

Monorepo Structure (future plan)

root project: /coding-with-claude-application
packages (apps, microservices, utilities):
- cwc-types: shared TypeScript types to be used in all other packages
- cwc-utils: shared utilities for browser and Node.js (profanity checking, validation helpers, etc.)
- cwc-deployment: custom deployment CLI for SSH-based deployment to remote servers
- cwc-backend-utils: shared Node.js utilities that backend/api packages will consume
- cwc-website: public frontend end web application
- cwc-auth: authentication microservice, providing login, logout, signup, password reset, etc.
- cwc-api: the main data api used by cwc-website to read & write data, enforce auth, role-based access policies, and business rules/logic
- cwc-dashboard: an administrative web dashboard app for site owners to manage the app & data
- cwc-admin-api: the admin and data api used by the cwc-dashboard app
- cwc-database: database scripts to create tables, indexes, views, as well as insert configuration data
- cwc-schema: shared schema management library that may be used by frontend and backend packages
- cwc-sql: the only backend service that interacts directly with the database server, uses schema to dynamically generate sql statements
- cwc-e2e: a set of end-to-end tests

Tech Stack: to be determined as we build each package, update this documentation as we go.

Development Tooling & Infrastructure

Monorepo Management

pnpm v9.x + Turborepo v2.x

pnpm workspaces for package management and dependency resolution
- Configured in pnpm-workspace.yaml
- Packages located in packages/*
- Uses content-addressable storage for disk efficiency
- Strict dependency resolution prevents phantom dependencies
Turborepo for task orchestration and caching
- Configured in turbo.json
- Intelligent parallel execution based on dependency graph
- Local caching for faster rebuilds
- Pipeline tasks: build, dev, test, lint, typecheck

Node.js Version

Node.js 22 LTS (specified in .nvmrc)
Required for all development and production environments
Use nvm for version management

Code Quality Tools

TypeScript v5.4+

Configured in tsconfig.base.json
Strict mode enabled with enhanced type checking
JavaScript explicitly disallowed (allowJs: false)
Monorepo-optimized with composite projects
Individual packages extend base config

Module Resolution: bundler

Uses "moduleResolution": "bundler" in tsconfig.base.json
Uses "module": "ES2022" (required for bundler resolution)
Allows clean TypeScript imports without .js extensions
- ✅ Correct: import { Schema } from './types'
- ❌ Not needed: import { Schema } from './types.js'
Still produces correct ES module output in compiled JavaScript
Designed for TypeScript projects compiled by tsc or bundlers

Why bundler over NodeNext:

Better DX: No .js extensions in TypeScript source files
Modern standard: Industry standard for TypeScript libraries and monorepos
Same output: Still generates proper ES modules (.js files)
No trade-offs: Type safety and module compatibility maintained

ESLint v8.x with TypeScript

Configured in .eslintrc.json
Uses @typescript-eslint/strict ruleset
Enforces explicit function return types
Prohibits any type and non-null assertions
Strict boolean expressions required

Prettier v3.x

Configured in .prettierrc.json
Standards:
- Single quotes
- 2-space indentation
- 100 character line width
- Trailing commas (ES5)
- LF line endings

Root Scripts

Run from monorepo root using pnpm:

pnpm build - Build all packages (parallel, cached)
pnpm dev - Run all packages in dev mode
pnpm test - Run tests across all packages (parallel, cached)
pnpm lint - Lint all packages (parallel, cached)
pnpm typecheck - Type-check all packages (parallel, cached)
pnpm format - Format all files with Prettier
pnpm format:check - Check formatting without changes

Development Workflow

Before starting work:
- Ensure Node 22 is active: nvm use
- Install dependencies: pnpm install
During development:
- Run dev mode: pnpm dev (in specific package or root)
- Format code: pnpm format
Before committing:
- Type-check: pnpm typecheck
- Lint: pnpm lint
- Format check: pnpm format:check
- Run tests: pnpm test

Package Creation Conventions

When creating a new package in the monorepo:

Version Number: Always start new packages at version 1.0.0 (not 0.0.1)
- Example: "version": "1.0.0" in package.json
- This is a project preference for consistency
Package Structure:
- Follow existing package patterns (see cwc-types as reference)
- Include package.json, tsconfig.json extending base config
- Place source files in src/ directory
- Include appropriate build and typecheck scripts
Package Naming:
- Use cwc- prefix for all CWC packages
- Use kebab-case: cwc-types, cwc-backend-utils, etc.
Package Documentation:
- Create packages/{package-name}/CLAUDE.md for package-specific patterns and conventions
- Document architecture decisions, design patterns, and critical implementation details
- Keep package docs focused on information needed for AI-assisted coding
Add Package Shortcut Script:
- Add a shortcut script to root package.json for the new package
- Format: "package-name-shortcut": "pnpm --filter cwc-package-name"
- Example: "backend-utils": "pnpm --filter cwc-backend-utils"
- This allows simplified commands: pnpm backend-utils add express instead of pnpm --filter cwc-backend-utils add express
- Keep shortcuts in alphabetical order in the scripts section

Key Architectural Decisions & Patterns

MariaDB Database

Strong Schema Enforcement
Transaction support
Efficient Joins
Data normalization
Sophisticated Querying and Analytics

Details: See packages/cwc-database/CLAUDE.md for complete database schema conventions.

TypeScript

Strict mode enabled (strict: true)
Shared types in cwc-types package; duplicating types in separate projects leads to inconsistencies, incompatibility, confusion, and extra work
Never use any - prefer unknown if type is truly unknown
Use string literal union types, not enums
Use type for entity definitions, not interface
Run typecheck before committing

Details: See packages/cwc-types/CLAUDE.md for complete TypeScript patterns and type generation.

Cloud-Agnostic Microservices

CWC uses a microservices architecture deployed as Docker containers potentially deployed across multiple datacenters.

Vendor lock-in is a real business risk. Cloud providers can change pricing, deny service access, or deprecate features at any time.
Cloud-agnostic microservices architecture allows switching hosting providers with minimal effort.
Preparation for Scale - can scale by adding infrastructure (more containers, load balancers) rather than rewriting code and specific services can be scaled based on actual load patterns

Environment Configuration

Each package will read configuration values from a .env file, provided at runtime, tailored to the runtime environment

Development Process

Tool, Framework, Version selection

mainstream, widely accepted, and thoroughly tested & proven tools only
the desire is to use the latest stable versions of the various tools

Adopt a "roll-your-own" mentality

we want to minimize the number of unnecessary dependencies to avoid headaches when upgrading our core tech stack
when it makes sense, we will build our own components and utilities rather than relying on a 3rd party package

eslint.config.js

2 versions

Version 1

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  // Global ignores
  {
    ignores: ['**/node_modules/**', '**/dist/**', '**/coverage/**', '**/.turbo/**'],
  },
  // Base ESLint recommended config
  eslint.configs.recommended,
  // TypeScript-ESLint recommended configs
  ...tseslint.configs.recommendedTypeChecked,
  ...tseslint.configs.strict,
  // Main configuration
  {
    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        ecmaVersion: 2022,
        sourceType: 'module',
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
    plugins: {
      '@typescript-eslint': tseslint.plugin,
    },
    rules: {
      '@typescript-eslint/no-unused-vars': [
        'error',
        {
          argsIgnorePattern: '^_',
          varsIgnorePattern: '^_',
        },
      ],
      '@typescript-eslint/explicit-function-return-type': [
        'error',
        {
          allowExpressions: true,
          allowTypedFunctionExpressions: true,
        },
      ],
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/no-non-null-assertion': 'error',
      '@typescript-eslint/strict-boolean-expressions': 'error',
      'no-console': [
        'warn',
        {
          allow: ['warn', 'error'],
        },
      ],
    },
  },
  // Disable type-checking for config files
  {
    files: ['**/*.config.js', '**/*.config.mjs'],
    ...tseslint.configs.disableTypeChecked,
  }
);

Version 2 (latest)

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  // Global ignores
  {
    ignores: ['**/node_modules/**', '**/dist/**', '**/coverage/**', '**/.turbo/**'],
  },
  // Base ESLint recommended config
  eslint.configs.recommended,
  // TypeScript-ESLint recommended configs
  ...tseslint.configs.recommendedTypeChecked,
  ...tseslint.configs.strict,
  // Main configuration
  {
    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        ecmaVersion: 2022,
        sourceType: 'module',
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
    plugins: {
      '@typescript-eslint': tseslint.plugin,
    },
    rules: {
      '@typescript-eslint/no-unused-vars': [
        'error',
        {
          argsIgnorePattern: '^_',
          varsIgnorePattern: '^_',
        },
      ],
      '@typescript-eslint/explicit-function-return-type': [
        'error',
        {
          allowExpressions: true,
          allowTypedFunctionExpressions: true,
        },
      ],
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/no-non-null-assertion': 'error',
      '@typescript-eslint/strict-boolean-expressions': 'error',
      'no-console': [
        'warn',
        {
          allow: ['warn', 'error'],
        },
      ],
    },
  },
  // Disable type-checking for config files
  {
    files: ['**/*.config.js', '**/*.config.mjs'],
    ...tseslint.configs.disableTypeChecked,
  }
);

package.json

3 versions

Version 1

{
  "name": "coding-with-claude-application",
  "version": "1.0.0",
  "private": true,
  "description": "A multi-tenant developer publishing platform",
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "typecheck": "turbo run typecheck",
    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\"",
    "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\""
  },
  "devDependencies": {
    "@typescript-eslint/eslint-plugin": "^7.0.0",
    "@typescript-eslint/parser": "^7.0.0",
    "eslint": "^8.57.0",
    "prettier": "^3.2.5",
    "turbo": "^2.0.0",
    "typescript": "^5.4.5"
  },
  "engines": {
    "node": ">=22.0.0",
    "pnpm": ">=9.0.0"
  },
  "packageManager": "pnpm@9.12.3"
}

Version 2

{
  "name": "coding-with-claude-application",
  "version": "1.0.0",
  "private": true,
  "description": "A multi-tenant developer publishing platform",
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "typecheck": "turbo run typecheck",
    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\"",
    "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\"",
    "backend-utils": "pnpm --filter cwc-backend-utils",
    "database": "pnpm --filter cwc-database",
    "deployment": "pnpm --filter cwc-deployment",
    "schema": "pnpm --filter cwc-schema",
    "types": "pnpm --filter cwc-types",
    "utils": "pnpm --filter cwc-utils"
  },
  "devDependencies": {
    "@typescript-eslint/eslint-plugin": "^7.0.0",
    "@typescript-eslint/parser": "^7.0.0",
    "eslint": "^8.57.0",
    "prettier": "^3.2.5",
    "turbo": "^2.0.0",
    "typescript": "^5.4.5"
  },
  "engines": {
    "node": ">=22.0.0",
    "pnpm": ">=9.0.0"
  },
  "packageManager": "pnpm@9.12.3"
}

Version 3 (latest)

{
  "name": "coding-with-claude-application",
  "version": "1.0.0",
  "private": true,
  "description": "A multi-tenant developer publishing platform",
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "typecheck": "turbo run typecheck",
    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\"",
    "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\"",
    "backend-utils": "pnpm --filter cwc-backend-utils",
    "database": "pnpm --filter cwc-database",
    "deployment": "pnpm --filter cwc-deployment",
    "schema": "pnpm --filter cwc-schema",
    "types": "pnpm --filter cwc-types",
    "utils": "pnpm --filter cwc-utils"
  },
  "devDependencies": {
    "@typescript-eslint/eslint-plugin": "^8.0.0",
    "@typescript-eslint/parser": "^8.0.0",
    "eslint": "^9.0.0",
    "prettier": "^3.2.5",
    "turbo": "^2.0.0",
    "typescript": "^5.4.5",
    "typescript-eslint": "^8.47.0"
  },
  "engines": {
    "node": ">=22.0.0",
    "pnpm": ">=9.0.0"
  },
  "packageManager": "pnpm@9.12.3"
}

packages/cwc-backend-utils/CLAUDE.md

3 versions

Version 1

cwc-backend-utils Package

Backend utilities for CWC microservices. Node.js-specific utilities only.

Package Purpose

Provide shared backend utilities used across CWC microservices
Node.js-specific - can use Node.js APIs (fs, path, crypto, etc.)
Zero runtime dependencies preferred (aligns with "roll-your-own" philosophy)
Tree-shakeable for optimal bundle size

Package Structure

cwc-backend-utils/
├── src/
│   └── index.ts                   - Main exports (to be created)
└── dist/                          - Compiled output

Current Utilities

Package is newly created - no utilities yet.

Node.js Compatibility

cwc-backend-utils is designed ONLY for Node.js environments:

✅ Can use Node.js APIs (fs, path, crypto, os, etc.) ✅ Can use Node.js-specific packages (if necessary) ✅ ES modules output ✅ Tree-shakeable ❌ NOT browser-compatible

Target Environment:

Node.js 22+
Backend microservices (cwc-api, cwc-auth, cwc-admin-api, cwc-sql)

Adding New Utilities

When adding utilities to this package:

Node.js-specific utilities only:
- File system operations
- Path manipulation
- Environment variable parsing
- Crypto/hashing utilities
- Process management helpers
- Server-side validation
Keep dependencies minimal:
- Prefer zero dependencies
- Use built-in Node.js modules when possible
- Document any dependencies clearly
Maintain tree-shakeability:
- Export utilities as named exports
- Avoid side effects in module loading
- Keep utilities independent where possible
Follow existing patterns:
- TypeScript with strict mode
- Comprehensive JSDoc comments
- Include usage examples
- Export from src/index.ts
Update documentation:
- Add section to this CLAUDE.md
- Update root CLAUDE.md if significant
- Include usage examples

Guidelines for Backend Utilities

Utilities that belong in cwc-backend-utils:

File system utilities
Environment configuration helpers
Server-side hashing/crypto
Request/response formatting
Error handling utilities
Logging helpers
JWT utilities
API response builders
Node.js-specific validation

Utilities that DON'T belong here:

Cross-platform utilities → Use cwc-utils
Type definitions → Use cwc-types
Schema definitions → Use cwc-schema
Database queries → Use cwc-database or cwc-sql
UI components → Not applicable (backend-only)

Testing Guidelines

When testing utilities:

Test in Node.js environment only:
- Unit tests run in Node.js 22+
- No browser compatibility needed
Test edge cases:
- Empty inputs
- Invalid inputs
- Error conditions
- Async error handling
Security considerations:
- Validate all external inputs
- Prevent path traversal
- Sanitize file operations
- Use secure crypto practices

Future Enhancements

Potential additions (not implemented yet):

Environment variable parsing and validation
JWT token utilities (sign, verify, decode)
Password hashing utilities (bcrypt/argon2 wrappers)
API response builders
Error formatting utilities
Request validation helpers
File upload processing
CSV/JSON parsing utilities
Server-side rate limiting helpers

Related Packages

Consumed By:

cwc-api - Main API backend
cwc-auth - Authentication service
cwc-admin-api - Admin API backend
cwc-sql - Database service
Any backend microservice

Dependencies:

None (zero runtime dependencies currently)

Related:

cwc-utils - Cross-platform utilities (browser + Node.js)
cwc-types - Type definitions
cwc-schema - Schema definitions and validation

Version 2

cwc-backend-utils Package

Backend utilities for CWC microservices. Node.js-specific utilities only.

Package Purpose

Provide shared backend utilities used across CWC microservices
Node.js-specific - can use Node.js APIs (fs, path, crypto, etc.)
Handles communication with cwc-sql service via DataApi client
Provides Express server setup with CORS, rate limiting, and security
Centralized error logging to database
Environment configuration loading

Package Structure

cwc-backend-utils/
├── src/
│   ├── DataApi/
│   │   ├── DataApi.ts            - Client for cwc-sql service
│   │   └── index.ts              - DataApi exports
│   ├── Logger/
│   │   ├── Logger.ts             - Error logging to database
│   │   └── index.ts              - Logger exports
│   ├── express/
│   │   ├── service.ts            - Express service factory
│   │   ├── cors.ts               - CORS middleware
│   │   ├── rateLimiter.ts        - Rate limiting middleware
│   │   ├── invalidRoutes.ts      - Invalid route protection
│   │   ├── requestUtils.ts       - Request utility functions
│   │   └── index.ts              - Express exports
│   ├── backendUtils.types.ts     - TypeScript type definitions
│   ├── loadDotEnv.ts             - Environment loading utility
│   ├── DataApiKeysUtil.ts        - JWT token management for DataApi
│   └── index.ts                  - Main exports
└── dist/                         - Compiled output

Architecture Overview

CWC Backend Services Architecture:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  cwc-auth   │     │   cwc-api   │     │cwc-admin-api│
│  (Express) │     │  (Express)  │     │  (Express)  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │  DataApi client   │  DataApi client   │  DataApi client
       │  (HTTP/JWT)       │  (HTTP/JWT)       │  (HTTP/JWT)
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │   cwc-sql   │
                    │  (Express)  │
                    └──────┬──────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  MariaDB    │
                    │  Database   │
                    └─────────────┘

Key Principles:

Only cwc-sql talks to database - All other services use DataApi client
JWT authentication - DataApi uses RS256 signed JWTs for service-to-service auth
Request-scoped operations - All operations include userPkId for security/auditing
Centralized error logging - Logger writes errors to database via DataApi

DataApi Client

Purpose: HTTP client for communicating with the cwc-sql service. All backend services use DataApi instead of direct database access.

Architecture

Authentication: JWT tokens signed with RS256 algorithm
Token Management: Auto-refreshes tokens when they expire (<5s remaining)
Operation Batching: Supports multiple operations in a single transaction
Type-Safe: Fully typed request/response structures

Core Methods

query(options) - Execute SELECT operations

const dataApi = new DataApi({ config, enableLogging: true, logger, clientName: 'cwc-api' });

const command = dataApi.selectCommand({
  table: 'user',
  filters: { email: 'user@example.com' },
  fields: ['userPkId', 'username', 'email'],
});

const response = await dataApi.query({ userPkId, command });
const user = dataApi.getFirstResult<CwcUser>(response);

mutate(options) - Execute INSERT, UPDATE, DELETE operations

// INSERT
const command = dataApi.insertCommand({
  table: 'user',
  values: { username: 'johndoe', email: 'john@example.com' },
});

const response = await dataApi.mutate({ userPkId, command });
const insertId = dataApi.getInsertResultId(response);

// UPDATE
const updateCommand = dataApi.updateCommand({
  table: 'user',
  filters: { userPkId: 123 },
  values: { email: 'newemail@example.com' },
});

await dataApi.mutate({ userPkId, command: updateCommand });

// DELETE
const deleteCommand = dataApi.deleteCommand({
  table: 'user',
  filters: { userPkId: 123 },
});

await dataApi.mutate({ userPkId, command: deleteCommand });

Command Builders

emptyCommand(transaction) - Create empty command for batch operations

const command = dataApi.emptyCommand(true); // transaction = true
dataApi.addOperation({
  command,
  table: 'user',
  operationType: 'insert',
  operationDetails: { values: { username: 'user1' } },
});
dataApi.addOperation({
  command,
  table: 'project',
  operationType: 'insert',
  operationDetails: { values: { projectId: 'my-project' } },
});

const response = await dataApi.mutate({ userPkId, command });

Advanced Queries:

// With sorting and limiting
const command = dataApi.selectCommand({
  table: 'project',
  filters: { userPkId: 123 },
  fields: ['projectPkId', 'projectId', 'title'],
  sort: [{ fieldName: 'createdDate', direction: 'DESC' }],
  limit: { recordCount: 10, startIndex: 0 },
});

// Custom SQL
const command = dataApi.selectCommand({
  custom: {
    customSql: 'SELECT * FROM user WHERE username LIKE :pattern',
    customParams: { pattern: '%john%' },
    customTables: ['user'],
  },
});

Helper Methods

Result extraction for queries:

getFirstResult<T>(response) - Get first result from operation-0
getSecondResult<T>(response) - Get first result from operation-1
getResult<T>(response, name, index) - Get specific result
getFirstResults<T>(response) - Get all results from operation-0
getSecondResults<T>(response) - Get all results from operation-1
getResults<T>(response, name) - Get all results from named operation

Result extraction for mutations:

getInsertResult(response, operationName?) - Returns true if 1 row inserted
getInsertResultId(response, operationName?) - Returns insertId
getUpdateResult(response, operationName?) - Returns true if 1+ rows updated
getDeleteResult(response, operationName?) - Returns true if 1+ rows deleted

Logger

Purpose: Centralized error logging to database. Logs errors, information, and debug messages.

Usage

import { Logger } from 'cwc-backend-utils';

const logger = new Logger({ config, serviceName: 'cwc-api' });

// Log errors
await logger.logError({
  userPkId: 123,
  codeLocation: 'api/handlers/users.ts:45',
  message: 'Failed to create user',
  error: err, // Error object or string
  value: { username, email }, // Additional context
  request: JSON.stringify(req.body), // Request data
});

// Log informational messages (debug mode only)
logger.logInformation({
  userPkId: 123,
  codeLocation: 'api/handlers/users.ts:30',
  message: 'User creation started',
  value: { username, email },
});

// Log debug messages (debug mode only)
logger.logDebug({
  userPkId: 123,
  codeLocation: 'api/handlers/users.ts:35',
  message: 'Validating user input',
  value: { username },
});

Features

Database logging: Writes to errorLog table via DataApi
Automatic truncation: Limits field lengths (error: 2000 chars, stack: 2000 chars, etc.)
Error parsing: Extracts message and stack from Error objects
JSON serialization: Automatically stringifies objects
Debug mode: logInformation and logDebug only output in debug mode
Service identification: Tags all logs with serviceName

Configuration

Requires BackendUtilsConfig with:

logErrorsToDatabase: true - Enable database logging
debugMode: true - Enable console output for logInformation/logDebug
dataUri - cwc-sql service URL

Express Service Factory

Purpose: Create fully-configured Express servers with security, CORS, rate limiting, and error handling built-in.

Usage

import { createExpressService, ExpressApi } from 'cwc-backend-utils';

// Define your API endpoints
const apis: ExpressApi[] = [
  { version: 1, path: '/api/v1/users', handler: usersHandler },
  { version: 1, path: '/api/v1/auth', handler: authHandler },
];

// Create service
const service = createExpressService({
  config,
  serviceName: 'cwc-api',
  apis,
  allowGet: true,
  allowPost: true,
  allowOptions: true,
  payloadLimit: '10mb', // Optional, default is Express default
});

// Start server
service.start(apis);
service.httpServer.listen(config.servicePort, () => {
  console.log(`Server running on port ${config.servicePort}`);
});

Built-in Middleware (Applied Automatically)

Rate Limiter - Memory-based rate limiting per IP
Helmet - Security headers
CORS - Configurable CORS with environment-specific origins
Invalid Routes - Blocks requests to non-registered paths
Error Handling - Captures and logs request/response errors
Logger Integration - Auto-creates Logger if config has dataUri

CORS Configuration

CORS behavior varies by environment:

Development (isDevelopment: true):

Reflects request origin in Access-Control-Allow-Origin
Allows credentials
Wide open for local development

Test (isTest: true):

Allows requests from Docker network IPs (192.1.1.x)
Allows devMachines IPs with devCorsOrigin
Falls back to corsOrigin for other requests

Production (isProduction: true):

Strict corsOrigin only
No dynamic origins

Rate Limiter

Configurable via BackendUtilsConfig:

rateLimiterPoints - Max requests per duration (default: 100)
rateLimiterDuration - Time window in seconds (default: 60)
Returns 429 status when exceeded

Invalid Routes Protection

Automatically rejects:

HTTP methods not in allowGet/allowPost/allowOptions
Paths that don't start with registered API paths
Returns 400 status with "unsupported" message

Environment Loading

Purpose: Load environment-specific .env files based on runtime environment and service name.

Usage

import { loadDotEnv } from 'cwc-backend-utils';

loadDotEnv({
  serviceName: 'cwc-api',
  environment: 'dev', // 'dev' | 'test' | 'prod' | 'unit' | 'e2e'
  debug: true, // Optional: log path resolution
});

// Now process.env is populated
const dbHost = process.env.DB_HOST;

Path Resolution

Local development (dev/unit/e2e):

Looks for: ../../../../private/cwc-secrets/env/{environment}.{serviceName}.env
Example: ../../../../private/cwc-secrets/env/dev.cwc-api.env

Server deployment (test/prod):

Looks for: ../../.env.{environment}
Example: ../../.env.test

Debug Mode

When debug: true, logs:

Environment detection (runningOnServer, runningLocally)
Resolved file name
Resolved absolute path
Loaded ENVIRONMENT variable

Configuration Types

BackendUtilsConfig

Complete configuration for services using DataApi and database features:

type BackendUtilsConfig = {
  // Environment flags
  debugMode: boolean;
  isDevelopment: boolean;
  isTest: boolean;
  isProduction: boolean;
  isUnitTest: boolean;
  isEndToEnd: boolean;

  // Service URLs
  dataUri: string;           // cwc-sql service URL
  websocketUri: string;      // WebSocket URL (if needed)
  servicePort: number;       // Port for this service

  // Features
  logErrorsToDatabase: boolean;

  // CORS
  corsOrigin: string;        // Production origin
  devCorsOrigin: string;     // Development origin

  // Rate limiting
  rateLimiterPoints: number;      // Max requests per duration
  rateLimiterDuration: number;    // Duration in seconds

  // Development
  devMachines?: { name: string; ip: string }[];

  // Service API (optional)
  serviceApi?: { allowedIps: string };

  // End-to-end testing
  endToEnd?: Record<string, string>;
};

BackendUtilsConfigBasic

Simplified config for services that don't use DataApi:

type BackendUtilsConfigBasic = Omit<
  BackendUtilsConfig,
  'dataUri' | 'websocketUri' | 'logErrorsToDatabase'
>;

Use this for services that don't need database access.

DataApiKeysUtil

Purpose: Manages JWT tokens for DataApi authentication. Internal utility used by DataApi class.

Features

Automatic refresh: Generates new tokens when <5s remain before expiry
RS256 signing: Uses RSA public/private key pairs
30-second expiration: Tokens valid for 30 seconds (auto-refresh ensures continuity)
Key loading: Reads keys from data-api-keys/ directory

Key File Locations

Local development:

../../../cwc-secrets/data-api-keys/data-api-jwt-private.pem
../../../cwc-secrets/data-api-keys/data-api-jwt-public.pem

Server deployment:

./data-api-keys/data-api-jwt-private.pem
./data-api-keys/data-api-jwt-public.pem

Token Payload

{
  dataJwtId: '550e8400-e29b-41d4-a716-446655440000', // UUID v4
  clientName: 'cwc-api', // Backend service name
  exp: 1234567890, // Expiration timestamp
  iat: 1234567860  // Issued at timestamp
}

Request Utilities

getRemoteIpAddress(req)

Extract the real client IP address from Express request, handling proxy headers and IPv6 formatting.

import { getRemoteIpAddress } from 'cwc-backend-utils';

app.use((req, res, next) => {
  const clientIp = getRemoteIpAddress(req);
  console.log('Client IP:', clientIp);
  next();
});

Resolution order:

x-real-ip header (set by nginx proxy)
origin header hostname
req.ip (strips ::ffff: IPv6 prefix if present)

Complete Service Example

Typical backend service setup using cwc-backend-utils:

// src/index.ts
import {
  loadDotEnv,
  createExpressService,
  DataApi,
  Logger,
  BackendUtilsConfig,
  ExpressApi,
} from 'cwc-backend-utils';
import { RequestHandler } from 'express';

// Load environment variables
loadDotEnv({
  serviceName: 'cwc-api',
  environment: process.env.NODE_ENV as RuntimeEnvironment,
});

// Build configuration
const config: BackendUtilsConfig = {
  debugMode: process.env.DEBUG_MODE === 'true',
  isDevelopment: process.env.NODE_ENV === 'dev',
  isTest: process.env.NODE_ENV === 'test',
  isProduction: process.env.NODE_ENV === 'prod',
  isUnitTest: process.env.NODE_ENV === 'unit',
  isEndToEnd: process.env.NODE_ENV === 'e2e',
  dataUri: process.env.DATA_URI!,
  websocketUri: process.env.WEBSOCKET_URI!,
  servicePort: parseInt(process.env.SERVICE_PORT!, 10),
  logErrorsToDatabase: true,
  corsOrigin: process.env.CORS_ORIGIN!,
  devCorsOrigin: process.env.DEV_CORS_ORIGIN!,
  rateLimiterPoints: 100,
  rateLimiterDuration: 60,
  devMachines: JSON.parse(process.env.DEV_MACHINES || '[]'),
};

// Initialize shared services
const dataApi = new DataApi({
  config,
  enableLogging: true,
  logger: undefined, // Will be created by Logger if needed
  clientName: 'cwc-api',
});

const logger = new Logger({ config, serviceName: 'cwc-api' });

// Define API handlers
const usersHandler: RequestHandler = async (req, res) => {
  try {
    const { userPkId } = req.user; // From auth middleware

    const command = dataApi.selectCommand({
      table: 'user',
      filters: { userPkId },
    });

    const response = await dataApi.query({ userPkId, command });
    const user = dataApi.getFirstResult(response);

    res.json({ success: true, user });
  } catch (error) {
    await logger.logError({
      userPkId: req.user?.userPkId,
      codeLocation: 'handlers/users.ts:25',
      message: 'Failed to fetch user',
      error,
      request: JSON.stringify(req.body),
    });
    res.status(500).json({ success: false, error: 'Internal server error' });
  }
};

// Define APIs
const apis: ExpressApi[] = [
  { version: 1, path: '/api/v1/users', handler: usersHandler },
];

// Create and start service
const service = createExpressService({
  config,
  serviceName: 'cwc-api',
  apis,
  allowGet: true,
  allowPost: true,
  allowOptions: true,
  payloadLimit: undefined,
});

service.start(apis);
service.httpServer.listen(config.servicePort, () => {
  console.log(`cwc-api listening on port ${config.servicePort}`);
});

Dependencies

Runtime dependencies:

express (^5.1.0) - Web framework
axios (^1.13.2) - HTTP client for DataApi
helmet (^8.1.0) - Security headers
rate-limiter-flexible (^8.2.1) - Rate limiting
jsonwebtoken (^9.0.2) - JWT signing/verification
uuid (^13.0.0) - UUID generation
dotenv (^17.2.3) - Environment variable loading
cwc-types (workspace) - Shared TypeScript types

Dev dependencies:

@types/express - Express type definitions
@types/jsonwebtoken - JWT type definitions
typescript - TypeScript compiler

Node.js Compatibility

cwc-backend-utils is designed ONLY for Node.js environments:

✅ Can use Node.js APIs (fs, path, crypto, os, http, etc.) ✅ Can use Node.js-specific packages ✅ ES modules output ✅ Tree-shakeable ❌ NOT browser-compatible

Target Environment:

Node.js 22+
Backend microservices (cwc-api, cwc-auth, cwc-admin-api, cwc-sql)

Adding New Utilities

When adding utilities to this package:

Node.js-specific utilities only:
- File system operations
- Path manipulation
- Environment variable parsing
- Crypto/hashing utilities
- Process management helpers
- Server-side validation
Keep dependencies minimal:
- Prefer zero dependencies
- Use built-in Node.js modules when possible
- Document any dependencies clearly
Maintain tree-shakeability:
- Export utilities as named exports
- Avoid side effects in module loading
- Keep utilities independent where possible
Follow existing patterns:
- TypeScript with strict mode
- Comprehensive JSDoc comments
- Include usage examples
- Export from src/index.ts
Update documentation:
- Add section to this CLAUDE.md
- Update root CLAUDE.md if significant
- Include usage examples

Guidelines for Backend Utilities

Utilities that belong in cwc-backend-utils:

File system utilities
Environment configuration helpers
Server-side hashing/crypto
Request/response formatting
Error handling utilities
Logging helpers
JWT utilities
API response builders
Node.js-specific validation

Utilities that DON'T belong here:

Cross-platform utilities → Use cwc-utils
Type definitions → Use cwc-types
Schema definitions → Use cwc-schema
Database queries → Use cwc-database or cwc-sql
UI components → Not applicable (backend-only)

Testing Guidelines

When testing utilities:

Test in Node.js environment only:
- Unit tests run in Node.js 22+
- No browser compatibility needed
Test edge cases:
- Empty inputs
- Invalid inputs
- Error conditions
- Async error handling
Security considerations:
- Validate all external inputs
- Prevent path traversal
- Sanitize file operations
- Use secure crypto practices

Current Utilities Summary

✅ Implemented:

✅ DataApi client - HTTP client for cwc-sql service
✅ Logger - Error logging to database
✅ Express service factory - Complete Express server setup
✅ CORS middleware - Environment-specific CORS handling
✅ Rate limiter - Memory-based rate limiting
✅ JWT token utilities - DataApiKeysUtil for service-to-service auth
✅ Environment loading - loadDotEnv for .env file loading
✅ Request utilities - IP address extraction
✅ Invalid routes protection - Path validation middleware

Potential Future Additions:

Password hashing utilities (bcrypt/argon2 wrappers)
User JWT utilities (separate from DataApi JWTs)
API response builders/formatters
Request validation helpers
File upload processing
CSV/JSON parsing utilities
WebSocket utilities
Background job scheduling helpers

Related Packages

Consumed By:

cwc-api - Main API backend
cwc-auth - Authentication service
cwc-admin-api - Admin API backend
cwc-sql - Database service (uses Logger, Express service)
Any backend microservice

Depends On:

cwc-types (workspace) - Shared TypeScript types and entity definitions

Related:

cwc-utils - Cross-platform utilities (browser + Node.js)
cwc-schema - Schema definitions and validation
cwc-database - Database schema and migrations

Version 3 (latest)

cwc-backend-utils Package

Backend utilities for CWC microservices. Node.js-specific utilities only.

Package Purpose

Provide shared backend utilities used across CWC microservices
Node.js-specific - can use Node.js APIs (fs, path, crypto, etc.)
Handles communication with cwc-sql service via SqlClient client
Provides Express server setup with CORS, rate limiting, and security
Centralized error logging to database
Environment configuration loading

Package Structure

cwc-backend-utils/
├── src/
│   ├── SqlClient/
│   │   ├── SqlClient.ts            - Client for cwc-sql service
│   │   └── index.ts              - SqlClient exports
│   ├── Logger/
│   │   ├── Logger.ts             - Error logging to database
│   │   └── index.ts              - Logger exports
│   ├── express/
│   │   ├── service.ts            - Express service factory
│   │   ├── cors.ts               - CORS middleware
│   │   ├── rateLimiter.ts        - Rate limiting middleware
│   │   ├── invalidRoutes.ts      - Invalid route protection
│   │   ├── requestUtils.ts       - Request utility functions
│   │   └── index.ts              - Express exports
│   ├── backendUtils.types.ts     - TypeScript type definitions
│   ├── loadDotEnv.ts             - Environment loading utility
│   ├── SqlClientKeysUtil.ts        - JWT token management for SqlClient
│   └── index.ts                  - Main exports
└── dist/                         - Compiled output

Architecture Overview

CWC Backend Services Architecture:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  cwc-auth   │     │   cwc-api   │     │cwc-admin-api│
│  (Express) │     │  (Express)  │     │  (Express)  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │  SqlClient client   │  SqlClient client   │  SqlClient client
       │  (HTTP/JWT)       │  (HTTP/JWT)       │  (HTTP/JWT)
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │   cwc-sql   │
                    │  (Express)  │
                    └──────┬──────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  MariaDB    │
                    │  Database   │
                    └─────────────┘

Key Principles:

Only cwc-sql talks to database - All other services use SqlClient client
JWT authentication - SqlClient uses RS256 signed JWTs for service-to-service auth
Request-scoped operations - All operations include userPkId for security/auditing
Centralized error logging - Logger writes errors to database via SqlClient

SqlClient Client

Purpose: HTTP client for communicating with the cwc-sql service. All backend services use SqlClient instead of direct database access.

Architecture

Authentication: JWT tokens signed with RS256 algorithm
Token Management: Auto-refreshes tokens when they expire (<5s remaining)
Operation Batching: Supports multiple operations in a single transaction
Type-Safe: Fully typed request/response structures

Core Methods

query(options) - Execute SELECT operations

const sqlClient = new SqlClient({ config, enableLogging: true, logger, clientName: 'cwc-api' });

const command = sqlClient.selectCommand({
  table: 'user',
  filters: { email: 'user@example.com' },
  fields: ['userPkId', 'username', 'email'],
});

const response = await sqlClient.query({ userPkId, command });
const user = sqlClient.getFirstResult<CwcUser>(response);

mutate(options) - Execute INSERT, UPDATE, DELETE operations

// INSERT
const command = sqlClient.insertCommand({
  table: 'user',
  values: { username: 'johndoe', email: 'john@example.com' },
});

const response = await sqlClient.mutate({ userPkId, command });
const insertId = sqlClient.getInsertResultId(response);

// UPDATE
const updateCommand = sqlClient.updateCommand({
  table: 'user',
  filters: { userPkId: 123 },
  values: { email: 'newemail@example.com' },
});

await sqlClient.mutate({ userPkId, command: updateCommand });

// DELETE
const deleteCommand = sqlClient.deleteCommand({
  table: 'user',
  filters: { userPkId: 123 },
});

await sqlClient.mutate({ userPkId, command: deleteCommand });

Command Builders

emptyCommand(transaction) - Create empty command for batch operations

const command = sqlClient.emptyCommand(true); // transaction = true
sqlClient.addOperation({
  command,
  table: 'user',
  operationType: 'insert',
  operationDetails: { values: { username: 'user1' } },
});
sqlClient.addOperation({
  command,
  table: 'project',
  operationType: 'insert',
  operationDetails: { values: { projectId: 'my-project' } },
});

const response = await sqlClient.mutate({ userPkId, command });

Advanced Queries:

// With sorting and limiting
const command = sqlClient.selectCommand({
  table: 'project',
  filters: { userPkId: 123 },
  fields: ['projectPkId', 'projectId', 'title'],
  sort: [{ fieldName: 'createdDate', direction: 'DESC' }],
  limit: { recordCount: 10, startIndex: 0 },
});

// Custom SQL
const command = sqlClient.selectCommand({
  custom: {
    customSql: 'SELECT * FROM user WHERE username LIKE :pattern',
    customParams: { pattern: '%john%' },
    customTables: ['user'],
  },
});

Helper Methods

Result extraction for queries:

getFirstResult<T>(response) - Get first result from operation-0
getSecondResult<T>(response) - Get first result from operation-1
getResult<T>(response, name, index) - Get specific result
getFirstResults<T>(response) - Get all results from operation-0
getSecondResults<T>(response) - Get all results from operation-1
getResults<T>(response, name) - Get all results from named operation

Result extraction for mutations:

getInsertResult(response, operationName?) - Returns true if 1 row inserted
getInsertResultId(response, operationName?) - Returns insertId
getUpdateResult(response, operationName?) - Returns true if 1+ rows updated
getDeleteResult(response, operationName?) - Returns true if 1+ rows deleted

Logger

Purpose: Centralized error logging to database. Logs errors, information, and debug messages.

Usage

import { Logger } from 'cwc-backend-utils';

const logger = new Logger({ config, serviceName: 'cwc-api' });

// Log errors
await logger.logError({
  userPkId: 123,
  codeLocation: 'api/handlers/users.ts:45',
  message: 'Failed to create user',
  error: err, // Error object or string
  value: { username, email }, // Additional context
  request: JSON.stringify(req.body), // Request data
});

// Log informational messages (debug mode only)
logger.logInformation({
  userPkId: 123,
  codeLocation: 'api/handlers/users.ts:30',
  message: 'User creation started',
  value: { username, email },
});

// Log debug messages (debug mode only)
logger.logDebug({
  userPkId: 123,
  codeLocation: 'api/handlers/users.ts:35',
  message: 'Validating user input',
  value: { username },
});

Features

Database logging: Writes to errorLog table via SqlClient
Automatic truncation: Limits field lengths (error: 2000 chars, stack: 2000 chars, etc.)
Error parsing: Extracts message and stack from Error objects
JSON serialization: Automatically stringifies objects
Debug mode: logInformation and logDebug only output in debug mode
Service identification: Tags all logs with serviceName

Configuration

Requires BackendUtilsConfig with:

logErrorsToDatabase: true - Enable database logging
debugMode: true - Enable console output for logInformation/logDebug
dataUri - cwc-sql service URL

Express Service Factory

Purpose: Create fully-configured Express servers with security, CORS, rate limiting, and error handling built-in.

Usage

import { createExpressService, ExpressApi } from 'cwc-backend-utils';

// Define your API endpoints
const apis: ExpressApi[] = [
  { version: 1, path: '/api/v1/users', handler: usersHandler },
  { version: 1, path: '/api/v1/auth', handler: authHandler },
];

// Create service
const service = createExpressService({
  config,
  serviceName: 'cwc-api',
  apis,
  allowGet: true,
  allowPost: true,
  allowOptions: true,
  payloadLimit: '10mb', // Optional, default is Express default
});

// Start server
service.start(apis);
service.httpServer.listen(config.servicePort, () => {
  console.log(`Server running on port ${config.servicePort}`);
});

Built-in Middleware (Applied Automatically)

Rate Limiter - Memory-based rate limiting per IP
Helmet - Security headers
CORS - Configurable CORS with environment-specific origins
Invalid Routes - Blocks requests to non-registered paths
Error Handling - Captures and logs request/response errors
Logger Integration - Auto-creates Logger if config has dataUri

CORS Configuration

CORS behavior varies by environment:

Development (isDevelopment: true):

Reflects request origin in Access-Control-Allow-Origin
Allows credentials
Wide open for local development

Test (isTest: true):

Allows requests from Docker network IPs (192.1.1.x)
Allows devMachines IPs with devCorsOrigin
Falls back to corsOrigin for other requests

Production (isProduction: true):

Strict corsOrigin only
No dynamic origins

Rate Limiter

Configurable via BackendUtilsConfig:

rateLimiterPoints - Max requests per duration (default: 100)
rateLimiterDuration - Time window in seconds (default: 60)
Returns 429 status when exceeded

Invalid Routes Protection

Automatically rejects:

HTTP methods not in allowGet/allowPost/allowOptions
Paths that don't start with registered API paths
Returns 400 status with "unsupported" message

Environment Loading

Purpose: Load environment-specific .env files based on runtime environment and service name.

Usage

import { loadDotEnv } from 'cwc-backend-utils';

loadDotEnv({
  serviceName: 'cwc-api',
  environment: 'dev', // 'dev' | 'test' | 'prod' | 'unit' | 'e2e'
  debug: true, // Optional: log path resolution
});

// Now process.env is populated
const dbHost = process.env.DB_HOST;

Path Resolution

Local development (dev/unit/e2e):

Looks for: ../../../../private/cwc-secrets/env/{environment}.{serviceName}.env
Example: ../../../../private/cwc-secrets/env/dev.cwc-api.env

Server deployment (test/prod):

Looks for: ../../.env.{environment}
Example: ../../.env.test

Debug Mode

When debug: true, logs:

Environment detection (runningOnServer, runningLocally)
Resolved file name
Resolved absolute path
Loaded ENVIRONMENT variable

Configuration Types

BackendUtilsConfig

Complete configuration for services using SqlClient and database features:

type BackendUtilsConfig = {
  // Environment flags
  debugMode: boolean;
  isDevelopment: boolean;
  isTest: boolean;
  isProduction: boolean;
  isUnitTest: boolean;
  isEndToEnd: boolean;

  // Service URLs
  dataUri: string; // cwc-sql service URL
  websocketUri: string; // WebSocket URL (if needed)
  servicePort: number; // Port for this service

  // Features
  logErrorsToDatabase: boolean;

  // CORS
  corsOrigin: string; // Production origin
  devCorsOrigin: string; // Development origin

  // Rate limiting
  rateLimiterPoints: number; // Max requests per duration
  rateLimiterDuration: number; // Duration in seconds

  // Development
  devMachines?: { name: string; ip: string }[];

  // Service API (optional)
  serviceApi?: { allowedIps: string };

  // End-to-end testing
  endToEnd?: Record<string, string>;
};

BackendUtilsConfigBasic

Simplified config for services that don't use SqlClient:

type BackendUtilsConfigBasic = Omit<
  BackendUtilsConfig,
  'dataUri' | 'websocketUri' | 'logErrorsToDatabase'
>;

Use this for services that don't need database access.

SqlClientKeysUtil

Purpose: Manages JWT tokens for SqlClient authentication. Internal utility used by SqlClient class.

Features

Automatic refresh: Generates new tokens when <5s remain before expiry
RS256 signing: Uses RSA public/private key pairs
30-second expiration: Tokens valid for 30 seconds (auto-refresh ensures continuity)
Key loading: Reads keys from data-api-keys/ directory

Key File Locations

Local development:

../../../cwc-secrets/data-api-keys/data-api-jwt-private.pem
../../../cwc-secrets/data-api-keys/data-api-jwt-public.pem

Server deployment:

./data-api-keys/data-api-jwt-private.pem
./data-api-keys/data-api-jwt-public.pem

Token Payload

{
  dataJwtId: '550e8400-e29b-41d4-a716-446655440000', // UUID v4
  clientName: 'cwc-api', // Backend service name
  exp: 1234567890, // Expiration timestamp
  iat: 1234567860  // Issued at timestamp
}

Request Utilities

getRemoteIpAddress(req)

Extract the real client IP address from Express request, handling proxy headers and IPv6 formatting.

import { getRemoteIpAddress } from 'cwc-backend-utils';

app.use((req, res, next) => {
  const clientIp = getRemoteIpAddress(req);
  console.log('Client IP:', clientIp);
  next();
});

Resolution order:

x-real-ip header (set by nginx proxy)
origin header hostname
req.ip (strips ::ffff: IPv6 prefix if present)

Complete Service Example

Typical backend service setup using cwc-backend-utils:

// src/index.ts
import {
  loadDotEnv,
  createExpressService,
  SqlClient,
  Logger,
  BackendUtilsConfig,
  ExpressApi,
} from 'cwc-backend-utils';
import { RequestHandler } from 'express';

// Load environment variables
loadDotEnv({
  serviceName: 'cwc-api',
  environment: process.env.NODE_ENV as RuntimeEnvironment,
});

// Build configuration
const config: BackendUtilsConfig = {
  debugMode: process.env.DEBUG_MODE === 'true',
  isDevelopment: process.env.NODE_ENV === 'dev',
  isTest: process.env.NODE_ENV === 'test',
  isProduction: process.env.NODE_ENV === 'prod',
  isUnitTest: process.env.NODE_ENV === 'unit',
  isEndToEnd: process.env.NODE_ENV === 'e2e',
  dataUri: process.env.DATA_URI!,
  websocketUri: process.env.WEBSOCKET_URI!,
  servicePort: parseInt(process.env.SERVICE_PORT!, 10),
  logErrorsToDatabase: true,
  corsOrigin: process.env.CORS_ORIGIN!,
  devCorsOrigin: process.env.DEV_CORS_ORIGIN!,
  rateLimiterPoints: 100,
  rateLimiterDuration: 60,
  devMachines: JSON.parse(process.env.DEV_MACHINES || '[]'),
};

// Initialize shared services
const sqlClient = new SqlClient({
  config,
  enableLogging: true,
  logger: undefined, // Will be created by Logger if needed
  clientName: 'cwc-api',
});

const logger = new Logger({ config, serviceName: 'cwc-api' });

// Define API handlers
const usersHandler: RequestHandler = async (req, res) => {
  try {
    const { userPkId } = req.user; // From auth middleware

    const command = sqlClient.selectCommand({
      table: 'user',
      filters: { userPkId },
    });

    const response = await sqlClient.query({ userPkId, command });
    const user = sqlClient.getFirstResult(response);

    res.json({ success: true, user });
  } catch (error) {
    await logger.logError({
      userPkId: req.user?.userPkId,
      codeLocation: 'handlers/users.ts:25',
      message: 'Failed to fetch user',
      error,
      request: JSON.stringify(req.body),
    });
    res.status(500).json({ success: false, error: 'Internal server error' });
  }
};

// Define APIs
const apis: ExpressApi[] = [{ version: 1, path: '/api/v1/users', handler: usersHandler }];

// Create and start service
const service = createExpressService({
  config,
  serviceName: 'cwc-api',
  apis,
  allowGet: true,
  allowPost: true,
  allowOptions: true,
  payloadLimit: undefined,
});

service.start(apis);
service.httpServer.listen(config.servicePort, () => {
  console.log(`cwc-api listening on port ${config.servicePort}`);
});

Dependencies

Runtime dependencies:

express (^5.1.0) - Web framework
axios (^1.13.2) - HTTP client for SqlClient
helmet (^8.1.0) - Security headers
rate-limiter-flexible (^8.2.1) - Rate limiting
jsonwebtoken (^9.0.2) - JWT signing/verification
uuid (^13.0.0) - UUID generation
dotenv (^17.2.3) - Environment variable loading
cwc-types (workspace) - Shared TypeScript types

Dev dependencies:

@types/express - Express type definitions
@types/jsonwebtoken - JWT type definitions
typescript - TypeScript compiler

Node.js Compatibility

cwc-backend-utils is designed ONLY for Node.js environments:

✅ Can use Node.js APIs (fs, path, crypto, os, http, etc.) ✅ Can use Node.js-specific packages ✅ ES modules output ✅ Tree-shakeable ❌ NOT browser-compatible

Target Environment:

Node.js 22+
Backend microservices (cwc-api, cwc-auth, cwc-admin-api, cwc-sql)

Adding New Utilities

When adding utilities to this package:

Node.js-specific utilities only:
- File system operations
- Path manipulation
- Environment variable parsing
- Crypto/hashing utilities
- Process management helpers
- Server-side validation
Keep dependencies minimal:
- Prefer zero dependencies
- Use built-in Node.js modules when possible
- Document any dependencies clearly
Maintain tree-shakeability:
- Export utilities as named exports
- Avoid side effects in module loading
- Keep utilities independent where possible
Follow existing patterns:
- TypeScript with strict mode
- Comprehensive JSDoc comments
- Include usage examples
- Export from src/index.ts
Update documentation:
- Add section to this CLAUDE.md
- Update root CLAUDE.md if significant
- Include usage examples

Guidelines for Backend Utilities

Utilities that belong in cwc-backend-utils:

File system utilities
Environment configuration helpers
Server-side hashing/crypto
Request/response formatting
Error handling utilities
Logging helpers
JWT utilities
API response builders
Node.js-specific validation

Utilities that DON'T belong here:

Cross-platform utilities → Use cwc-utils
Type definitions → Use cwc-types
Schema definitions → Use cwc-schema
Database queries → Use cwc-database or cwc-sql
UI components → Not applicable (backend-only)

Testing Guidelines

When testing utilities:

Test in Node.js environment only:
- Unit tests run in Node.js 22+
- No browser compatibility needed
Test edge cases:
- Empty inputs
- Invalid inputs
- Error conditions
- Async error handling
Security considerations:
- Validate all external inputs
- Prevent path traversal
- Sanitize file operations
- Use secure crypto practices

Current Utilities Summary

✅ Implemented:

✅ SqlClient client - HTTP client for cwc-sql service
✅ Logger - Error logging to database
✅ Express service factory - Complete Express server setup
✅ CORS middleware - Environment-specific CORS handling
✅ Rate limiter - Memory-based rate limiting
✅ JWT token utilities - SqlClientKeysUtil for service-to-service auth
✅ Environment loading - loadDotEnv for .env file loading
✅ Request utilities - IP address extraction
✅ Invalid routes protection - Path validation middleware

Potential Future Additions:

Password hashing utilities (bcrypt/argon2 wrappers)
User JWT utilities (separate from SqlClient JWTs)
API response builders/formatters
Request validation helpers
File upload processing
CSV/JSON parsing utilities
WebSocket utilities
Background job scheduling helpers

Related Packages

Consumed By:

cwc-api - Main API backend
cwc-auth - Authentication service
cwc-admin-api - Admin API backend
cwc-sql - Database service (uses Logger, Express service)
Any backend microservice

Depends On:

cwc-types (workspace) - Shared TypeScript types and entity definitions

Related:

cwc-utils - Cross-platform utilities (browser + Node.js)
cwc-schema - Schema definitions and validation
cwc-database - Database schema and migrations

packages/cwc-backend-utils/package.json

6 versions

Version 1

{
  "name": "cwc-backend-utils",
  "version": "1.0.0",
  "description": "Backend utilities for CWC microservices (Node.js only)",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": ["cwc", "backend", "utilities", "node"],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

Version 2

{
  "name": "cwc-backend-utils",
  "version": "1.0.0",
  "description": "Backend utilities for CWC microservices (Node.js only)",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [
    "cwc",
    "backend",
    "utilities",
    "node"
  ],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "@types/express": "^5.0.5",
    "typescript": "^5.4.0"
  },
  "dependencies": {
    "dotenv": "^17.2.3",
    "express": "^5.1.0"
  }
}

Version 3

{
  "name": "cwc-backend-utils",
  "version": "1.0.0",
  "description": "Backend utilities for CWC microservices (Node.js only)",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [
    "cwc",
    "backend",
    "utilities",
    "node"
  ],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "@types/express": "^5.0.5",
    "typescript": "^5.4.0"
  },
  "dependencies": {
    "cwc-types": "workspace:^",
    "dotenv": "^17.2.3",
    "express": "^5.1.0"
  }
}

Version 4

{
  "name": "cwc-backend-utils",
  "version": "1.0.0",
  "description": "Backend utilities for CWC microservices (Node.js only)",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [
    "cwc",
    "backend",
    "utilities",
    "node"
  ],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "@types/express": "^5.0.5",
    "@types/jsonwebtoken": "^9.0.10",
    "typescript": "^5.4.0"
  },
  "dependencies": {
    "axios": "^1.13.2",
    "cwc-types": "workspace:^",
    "dotenv": "^17.2.3",
    "express": "^5.1.0",
    "helmet": "^8.1.0",
    "jsonwebtoken": "^9.0.2",
    "rate-limiter-flexible": "^8.2.1",
    "uuid": "^13.0.0"
  }
}

Version 5

{
  "name": "cwc-backend-utils",
  "version": "1.0.0",
  "description": "Backend utilities for CWC microservices (Node.js only)",
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "default": "./src/index.ts"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [
    "cwc",
    "backend",
    "utilities",
    "node"
  ],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "@types/express": "^5.0.5",
    "@types/jsonwebtoken": "^9.0.10",
    "typescript": "^5.4.0"
  },
  "dependencies": {
    "axios": "^1.13.2",
    "cwc-types": "workspace:^",
    "dotenv": "^17.2.3",
    "express": "^5.1.0",
    "helmet": "^8.1.0",
    "jsonwebtoken": "^9.0.2",
    "rate-limiter-flexible": "^8.2.1",
    "uuid": "^13.0.0"
  }
}

Version 6 (latest)

{
  "name": "cwc-backend-utils",
  "version": "1.0.0",
  "description": "Backend utilities for CWC microservices (Node.js only)",
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "default": "./src/index.ts"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [
    "cwc",
    "backend",
    "utilities",
    "node"
  ],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "@types/express": "^5.0.5",
    "@types/jsonwebtoken": "^9.0.10",
    "typescript": "^5.4.0"
  },
  "dependencies": {
    "axios": "^1.13.2",
    "cwc-types": "workspace:^",
    "dotenv": "^17.2.3",
    "express": "^5.1.0",
    "helmet": "^8.1.0",
    "jsonwebtoken": "^9.0.2",
    "rate-limiter-flexible": "^8.2.1",
    "uuid": "^13.0.0"
  }
}

packages/cwc-backend-utils/tsconfig.json

2 versions

Version 1

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

Version 2 (latest)

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

packages/cwc-schema/package.json

2 versions

Version 1

{
  "name": "cwc-schema",
  "version": "1.0.0",
  "description": "Database schema definitions with validation rules for CWC application",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": ["cwc", "schema", "validation", "database"],
  "author": "",
  "license": "UNLICENSED",
  "dependencies": {
    "zod": "^3.24.1"
  },
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

Version 2 (latest)

{
  "name": "cwc-schema",
  "version": "1.0.0",
  "description": "Database schema definitions with validation rules for CWC application",
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "default": "./src/index.ts"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": ["cwc", "schema", "validation", "database"],
  "author": "",
  "license": "UNLICENSED",
  "dependencies": {
    "zod": "^3.24.1"
  },
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

packages/cwc-types/package.json

2 versions

Version 1

{
  "name": "cwc-types",
  "version": "1.0.0",
  "description": "Shared TypeScript types for CWC application",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./entityTypes": {
      "types": "./dist/entityTypes.d.ts",
      "default": "./dist/entityTypes.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": ["cwc", "types", "typescript"],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

Version 2 (latest)

{
  "name": "cwc-types",
  "version": "1.0.0",
  "description": "Shared TypeScript types for CWC application",
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "default": "./src/index.ts"
    },
    "./entityTypes": {
      "types": "./src/entityTypes.ts",
      "default": "./src/entityTypes.ts"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": ["cwc", "types", "typescript"],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

packages/cwc-types/src/index.ts

2 versions

Version 1

/**
 * CWC Types - Shared TypeScript types for CWC application
 *
 * This package contains all shared type definitions used across
 * the CWC monorepo packages.
 */

// Export all entity types
export * from './entityTypes.js';

Version 2 (latest)

/**
 * CWC Types - Shared TypeScript types for CWC application
 *
 * This package contains all shared type definitions used across
 * the CWC monorepo packages.
 */

// Export all entity types
export * from './entityTypes.js';

// Export config types
export * from './config.types.js';

packages/cwc-utils/package.json

2 versions

Version 1

{
  "name": "cwc-utils",
  "version": "1.0.0",
  "description": "Shared utilities for CWC application (browser and Node.js compatible)",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": ["cwc", "utils", "utilities", "shared"],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

Version 2 (latest)

{
  "name": "cwc-utils",
  "version": "1.0.0",
  "description": "Shared utilities for CWC application (browser and Node.js compatible)",
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "default": "./src/index.ts"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": ["cwc", "utils", "utilities", "shared"],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}