Developer MessagesClaude MessagesShow Tool Use

jeff

Hello, today let's work on the cwc-storage package. Please create a new package folder with the core files. I am going to try something new - I have implemented a file storage api on another one of my personal projects and I would like to import that code. There will be some changes needed since this project may handle things like env files/configuration slightly differently. Let's start by creating the package.

Claude

I'll create the cwc-storage package for you. Let me first check the existing package structure to follow established patterns.

Now I have the patterns. Let me create the cwc-storage package with the core files:

jeff

[Request interrupted by user for tool use]

I notice that you are pointing to the ./dist folder in the main, types, and exports settings. didn't we agree to use ./src when we switched the moduleResolution to bundler?

Claude

You're right. Looking at the cwc-types package.json I just read, it points to ./src/index.ts directly for main, types, and exports - not ./dist. With bundler module resolution, we can reference TypeScript source files directly.

Let me correct the package.json:

Now let me add the shortcut script to the root package.json:

The cwc-storage package is created and ready. Here's what was set up:

packages/cwc-storage/package.json - with ./src/index.ts for main/types/exports
packages/cwc-storage/tsconfig.json - extends base config
packages/cwc-storage/src/index.ts - placeholder entry point
packages/cwc-storage/CLAUDE.md - package documentation stub
Root package.json updated with "storage" shortcut script

The package is installed and typecheck passes. Ready for you to import your file storage API code.

jeff

Will I need to point out the moduleResolution issue every time I ask you to create a new package?

Claude

No, you shouldn't have to. That was my oversight - I had just read the cwc-types package.json which clearly showed the ./src/index.ts pattern, yet I still defaulted to ./dist.

I'll update the root CLAUDE.md to make this pattern explicit in the package creation conventions so it's not missed again.

Tool Result

   270→
   271→**Tech Stack:** to be determined as we build each package, update this documentation as we go.
   272→
   273→## Development Tooling & Infrastructure
   274→
   275→### Monorepo Management
   276→
   277→**pnpm v9.x + Turborepo v2.x**
   278→
   279→- **pnpm workspaces** for package management and dependency resolution
   280→  - Configured in `pnpm-workspace.yaml`
   281→  - Packages located in `packages/*`
   282→  - Uses content-addressable storage for disk efficiency
   283→  - Strict dependency resolution prevents phantom dependencies
   284→- **Turborepo** for task orchestration and caching
   285→  - Configured in `turbo.json`
   286→  - Intelligent parallel execution based on dependency graph
   287→  - Local caching for faster rebuilds
   288→  - Pipeline tasks: `build`, `dev`, `test`, `lint`, `typecheck`
   289→
   290→### Node.js Version
   291→
   292→- **Node.js 22 LTS** (specified in `.nvmrc`)
   293→- Required for all development and production environments
   294→- Use `nvm` for version management
   295→
   296→### Code Quality Tools
   297→
   298→**TypeScript v5.4+**
   299→
   300→- Configured in `tsconfig.base.json`
   301→- Strict mode enabled with enhanced type checking
   302→- JavaScript explicitly disallowed (`allowJs: false`)
   303→- Monorepo-optimized with composite projects
   304→- Individual packages extend base config
   305→
   306→**Module Resolution: bundler**
   307→
   308→- Uses `"moduleResolution": "bundler"` in tsconfig.base.json
   309→- Uses `"module": "ES2022"` (required for bundler resolution)
   310→- Allows clean TypeScript imports without `.js` extensions
   311→  - ✅ Correct: `import { Schema } from './types'`
   312→  - ❌ Not needed: `import { Schema } from './types.js'`
   313→- Still produces correct ES module output in compiled JavaScript
   314→- Designed for TypeScript projects compiled by tsc or bundlers
   315→
   316→**Why bundler over NodeNext:**
   317→- **Better DX:** No `.js` extensions in TypeScript source files
   318→- **Modern standard:** Industry standard for TypeScript libraries and monorepos
   319→- **Same output:** Still generates proper ES modules (.js files)
   320→- **No trade-offs:** Type safety and module compatibility maintained
   321→
   322→**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.
   323→
   324→**ESLint v8.x with TypeScript**
   325→
   326→- Configured in `.eslintrc.json`
   327→- Uses `@typescript-eslint/strict` ruleset
   328→- Enforces explicit function return types
   329→- Prohibits `any` type and non-null assertions

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>

Tool Result

   350→- `pnpm typecheck` - Type-check all packages (parallel, cached)
   351→- `pnpm format` - Format all files with Prettier
   352→- `pnpm format:check` - Check formatting without changes
   353→
   354→### Development Workflow
   355→
   356→1. **Before starting work:**
   357→   - Ensure Node 22 is active: `nvm use`
   358→   - Install dependencies: `pnpm install`
   359→
   360→2. **During development:**
   361→   - Run dev mode: `pnpm dev` (in specific package or root)
   362→   - Format code: `pnpm format`
   363→
   364→3. **Before committing:**
   365→   - Type-check: `pnpm typecheck`
   366→   - Lint: `pnpm lint`
   367→   - Format check: `pnpm format:check`
   368→   - Run tests: `pnpm test`
   369→
   370→### Package Creation Conventions
   371→
   372→**When creating a new package in the monorepo:**
   373→
   374→1. **Version Number:** Always start new packages at version `1.0.0` (not `0.0.1`)
   375→   - Example: `"version": "1.0.0"` in package.json
   376→   - This is a project preference for consistency
   377→
   378→2. **Package Structure:**
   379→   - Follow existing package patterns (see cwc-types as reference)
   380→   - Include `package.json`, `tsconfig.json` extending base config
   381→   - Place source files in `src/` directory
   382→   - Include appropriate `build` and `typecheck` scripts
   383→
   384→3. **Package Naming:**
   385→   - Use `cwc-` prefix for all CWC packages
   386→   - Use kebab-case: `cwc-types`, `cwc-backend-utils`, etc.
   387→
   388→4. **Package Documentation:**
   389→   - Create `packages/{package-name}/CLAUDE.md` for package-specific patterns and conventions
   390→   - Document architecture decisions, design patterns, and critical implementation details
   391→   - Keep package docs focused on information needed for AI-assisted coding
   392→
   393→5. **Add Package Shortcut Script:**
   394→   - Add a shortcut script to root `package.json` for the new package
   395→   - Format: `"package-name-shortcut": "pnpm --filter cwc-package-name"`
   396→   - Example: `"backend-utils": "pnpm --filter cwc-backend-utils"`
   397→   - This allows simplified commands: `pnpm backend-utils add express` instead of `pnpm --filter cwc-backend-utils add express`
   398→   - Keep shortcuts in alphabetical order in the scripts section
   399→

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>

I need to fix the numbering - there are now two item 3s:

Done. I've added item 3 "Package Entry Points" to the Package Creation Conventions with explicit instructions about using ./src/index.ts and marked it as CRITICAL. This pattern is now documented and I won't make that mistake again.

jeff

I have pasted some code files into cwc-storage/src but have not added the dependencies or done anything to the code yet other than renaming references to the old project name to cwc. Would you take a good look at this code and determine what we need to do next? Thank you!

Claude

I'll explore the cwc-storage package to understand what code you've imported and what needs to be done.

Now let me check what cwc-backend-utils exports to understand the dependency:

Now I have a complete picture of the imported code. Here's my analysis:

Summary of Imported Code

The cwc-storage package is a file storage microservice built on Express that provides:

GET files from filesystem storage
PUT files to filesystem storage
DELETE files from filesystem storage

Files are organized by groupId directories with API key authentication and HTTPS enforcement in production.

What Needs to Be Done

1. Add Dependencies to package.json

The code imports:

cwc-backend-utils (workspace) - for createExpressService, loadDotEnv
cwc-types (workspace) - for RuntimeEnvironment
express - for Request/Response types

2. Update `BackendServiceName` Type

In cwc-backend-utils/src/backendUtils.types.ts:5, the BackendServiceName type needs to include 'cwc-storage':

export type BackendServiceName = 'cwc-admin-api' | 'cwc-api' | 'cwc-auth' | 'cwc-sql';
// needs to add: | 'cwc-storage'

3. Align Configuration Types

The imported code defines its own Configuration/CachedConfiguration types in src/types.ts which are similar to but not identical to BackendUtilsConfig. Key differences:

cwc-storage has storageVolumePath and logPath (storage-specific)
cwc-storage doesn't have dataUri or logErrorsToDatabase (doesn't use SqlClient)
cwc-storage has its own Secrets type with storageApiKey

The imported code uses BackendUtilsConfigBasic pattern (no database access) which is correct.

4. Logger Differences

The imported code has its own file-based Logger class (writes to ./logs/{date}.log), while cwc-backend-utils has a database-based Logger. This is intentional since cwc-storage doesn't need database access.

5. Interface Alignment

The StorageApi interface in src/types.ts matches ExpressApi from cwc-backend-utils - both have version, handler, path.

Questions for You

Logger: Keep the file-based Logger for cwc-storage (makes sense since no DB access), or adapt to use cwc-backend-utils Logger?
Configuration pattern: The imported code has its own Configuration/CachedConfiguration types. Should we align these more closely with BackendUtilsConfigBasic, or keep them separate since storage has unique config needs?
Any other patterns from your other project you want to handle differently here?

jeff

for #1. yes, keep the file-based logger, #2. yes, I would be interested to see how you implement the configuration to align more closely to BackendUtilsConfigBasic, #3. it looks like cwc-sql implements config differently. can you compare the approaches and patterns and let's choose a consistent pattern to use throughout the application

Claude

I'll look at how cwc-sql implements configuration to compare the approaches.

Now I have a clear picture of both approaches. Here's my comparison:

Configuration Pattern Comparison

cwc-storage (Imported Code) Pattern

Location: src/configuration.ts - single file

Approach:

Command-line arguments (--port, --config, --debug) drive initialization
Calls loadDotEnv() after parsing command-line args
Reads process.env values inline with fallback defaults
Combines into CachedConfiguration type
Exports singleton: export const config = cachedConfig ?? getConfig()

Characteristics:

❌ Command-line arg parsing mixed with config loading
❌ Inline process.env access scattered throughout function
❌ Loose validation (just checks for undefined)
❌ Separate Configuration + CachedConfiguration + Secrets types
❌ writeLog function defined inline
✅ Simple single-file approach

cwc-sql Pattern

Location: src/config/ folder with 3 files:

config.types.ts - Type definition
loadConfig.ts - Loading logic with helper functions
index.ts - Exports

Approach:

Entry point (index.ts) calls loadDotEnv() first
Then calls loadConfig() which reads from process.env
Helper functions: requireEnv(), parseNumber(), parseBoolean(), parseArray()
Validates values (ranges, required fields)
Converts to BackendUtilsConfigBasic via adapter function
Caches result internally

Characteristics:

✅ Clean separation: types, loading, exports
✅ Reusable helper functions for parsing
✅ Strong validation with clear error messages
✅ Single config type (CwcSqlConfig)
✅ Adapter function to convert to BackendUtilsConfigBasic
✅ Debug logging with redacted secrets
✅ Environment-driven (no command-line parsing in config)

Key Differences

Aspect	cwc-storage	cwc-sql
Config source	Command-line + env	Environment only
Type structure	3 types (Config + Cached + Secrets)	1 type
Validation	Minimal	Strong with ranges
Helper functions	None	`requireEnv`, `parseNumber`, etc.
Backend-utils integration	Direct cast	Adapter function
File organization	Single file	Folder with 3 files
Secret handling	Nested `secrets` object	Flat in config type

Recommendation

Use the cwc-sql pattern as the standard. Reasons:

Cleaner separation - Types, loading, and exports in separate files
Reusable helpers - requireEnv(), parseNumber(), parseBoolean() should be moved to cwc-backend-utils for all services
Strong validation - Catches bad config early with clear errors
Single flat type - No need for nested Secrets object
Environment-driven - Command-line parsing belongs in index.ts, not config loading
Explicit adapter - createBackendUtilsConfig() makes the conversion clear

Proposed Changes for cwc-storage

Move config parsing helpers to cwc-backend-utils (so all services can use them)
Create src/config/ folder with:
- config.types.ts - CwcStorageConfig type
- loadConfig.ts - Uses helpers from cwc-backend-utils
- index.ts - Exports
Update src/index.ts to follow cwc-sql's main() pattern
Remove command-line parsing - Use RUNTIME_ENVIRONMENT env var instead

Would you like me to proceed with implementing the cwc-sql pattern for cwc-storage?

jeff

Thank you, yes, please proceed!

Claude

Let me first check the cwc-backend-utils structure to add the config parsing helpers:

Now let me create the cwc-storage config folder structure:

Now I need to update the index.ts to follow the cwc-sql main() pattern. First let me also update the types.ts to remove the old configuration types and the StorageApiV1 to use the new config:

Now I need to update the StorageApiV1 to use the new config pattern. First let me check what needs updating:

The StorageApiV1 uses config from ../../configuration. I need to update it to accept config as a constructor parameter (dependency injection pattern, similar to how cwc-sql passes config to handlers). Let me update it:

Now I need to update the routes.ts and StorageHandler.ts to accept config as a parameter, and update the storage functions to also receive config:

Now let me update the storage functions to use the factory pattern (receive config and return the function):

Now let me update the main index.ts to follow the cwc-sql main() pattern:

Now let me update the package.json with dependencies:

Now let me clean up the old configuration files and update the environment.d.ts:

Now let me also update the utils.ts to remove the config import:

The utils.ts looks fine - it doesn't import from configuration. Let me remove the unused fs import:

I have several errors to fix. Let me address them:

I need to add cwc-storage to the CwcErrorLogServiceName type. Let me fix all the errors:

Now let me fix the StorageApiV1 issue with undefined routeConfig:

Now fix the index.ts serviceApi issue:

Let me also run typecheck on the whole project to make sure there are no issues with the changes I made to cwc-backend-utils and cwc-types:

All packages pass typecheck. Let me mark the todo as complete and update the CLAUDE.md for the cwc-storage package:

All tasks are complete. Here's a summary of what was done:

Summary

1. Added Config Parsing Helpers to cwc-backend-utils

Created packages/cwc-backend-utils/src/configHelpers.ts with reusable functions:

requireEnv() - Get required env var or throw
optionalEnv() - Get optional env var with default
parseNumber() - Parse numeric env var
parseBoolean() - Parse ON/OFF or TRUE/FALSE
parseArray() - Parse comma-separated values
parseJson() - Parse JSON env var
parseMultiLine() - Parse multi-line strings (for keys)

2. Refactored cwc-storage Configuration

Created src/config/ folder following the cwc-sql pattern:

config.types.ts - CwcStorageConfig type
loadConfig.ts - Validates and caches config
index.ts - Clean exports

3. Updated Main Entry Point

Rewrote src/index.ts to follow cwc-sql's main() pattern:

Environment-driven config (not command-line args)
Adapter function for BackendUtilsConfigBasic
Graceful shutdown handlers
Uncaught error handling

4. Dependency Injection Throughout

Updated all components to receive config as constructor parameter:

StorageApiV1(config)
StorageHandler(options, config)
getRoutes(config) returns routes with closures
Storage functions use factory pattern: createGetFromStorage(config)

5. Type Updates

Added 'cwc-storage' to BackendServiceName in cwc-backend-utils
Added 'cwc-storage' to CwcErrorLogServiceName in cwc-types

6. Cleaned Up

Removed old configuration.ts file
Updated environment.d.ts to use RUNTIME_ENVIRONMENT instead of ENVIRONMENT
Updated package.json with workspace dependencies

All packages pass typecheck!

jeff

Very nice! src/apis/StorageApiV1/routes.ts exports getRoutes function. the other app has an entity called 'group', while cwc has other entities.
currently, cwc needs storage support for get, put, delete operations for the session-data files that are generated by cwc-transcript-parser. Let's replace the group routes and functions with session-data functions.

Claude

I'll explore the codebase to understand the session-data context and the current storage structure before proposing changes.

Tool Result

Perfect! I now have a comprehensive understanding of the session-data files. Let me provide a detailed summary to the user.

## Summary: CWC Session-Data Files

Based on my exploration of the cwc-transcript-parser package, here's a complete understanding of the session-data files:

### What Session-Data Files Are

**CwcSessionData** is an intermediate JSON format that converts raw Claude Code transcripts (JSONL + file-history) into an optimized structure for storage and rendering in cwc-website.

**Purpose:** Transforms raw Claude Code output → optimized JSON → storage/display

---

### File Structure and Format

**Output Format:** Single JSON file (not JSONL)

**Type Definition Location:** `/packages/cwc-types/src/sessionData.types.ts`

**Complete Structure:**

```typescript
CwcSessionData {
  // Format versioning
  formatVersion: '1.0.0'
  
  // Session identity
  sessionId: string                    // Claude Code UUID
  projectSessionFolder: string         // From ~/.claude/projects/
  
  // Session metadata
  summary: string | null               // From condensed conversation
  startTimestamp: string | null        // ISO 8601 of first message
  endTimestamp: string | null          // ISO 8601 of last message
  
  // Session context (extracted once from first message)
  cwd: string                          // Working directory
  gitBranch: string                    // Active git branch
  claudeCodeVersion: string            // Claude Code version
  model: string                        // Claude model used (e.g., claude-sonnet-4-5-20250929)
  
  // Conversation data
  messages: CwcSessionMessage[]        // Merged conversation messages
  
  // File history
  files: CwcSessionFile[]              // All modified files with version history
  
  // Computed stats
  stats: CwcSessionStats               // Aggregated statistics
}
```

---

### Message Structure

**CwcSessionMessage:**
```typescript
{
  uuid: string                         // Unique message ID
  parentUuid: string | null            // Thread parent (for branching)
  timestamp: string                    // ISO 8601
  role: 'user' | 'assistant'
  content: CwcSessionContent[]         // Text, tool_use, tool_result
  tokenUsage?: CwcSessionTokenUsage    // Only for assistant messages
}
```

**CwcSessionContent Types:**
- `{ type: 'text'; text: string }`
- `{ type: 'tool_use'; id: string; name: string; input: Record<string, unknown> }`
- `{ type: 'tool_result'; toolUseId: string; content: string; isError: boolean }`

**Important:** Thinking blocks are EXCLUDED to reduce size (~30-40% savings)

**Message Merging:** Consecutive messages from same role are merged together
- Before: 564 messages typical
- After: 24 messages typical

---

### File History Structure

**CwcSessionFile:**
```typescript
{
  filePath: string                     // Original absolute path
  displayPath: string                  // Path with privacy prefix stripped
  hash: string                         // Base hash from backup filename
  versions: CwcSessionFileVersion[]    // All versions (v1, v2, v3, ...)
}
```

**CwcSessionFileVersion:**
```typescript
{
  version: number                      // Version number (1-indexed)
  backupFileName: string               // Format: {hash}@v{version}
  timestamp: string                    // ISO 8601 when created
  content: string                      // Complete file content
}
```

**All versions included** to enable diff rendering in UI

---

### File Naming Convention

**Output filename format:** `{YYYY-MM-DD}_{HH-mm-ss}_session-data.json`

**Example:** `2025-11-19_17-16-35_session-data.json`

**Default location:** Same directory as input JSONL file

**Optional override:** `--output` parameter

---

### Storage Location & Paths

**Input Sources:**
- JSONL: `~/.claude/projects/{projectFolder}/{sessionId}.jsonl`
- File-history: `~/.claude/file-history/{sessionId}/{hash}@v{version}`

**Output Location:**
- Generated where CLI is run (or specified via --output)
- Eventually stored in cwc-storage (filesystem or S3-compatible storage)
- Referenced by storageKey in `codingSession` database table

---

### Path Stripping (Privacy)

**Personal path prefix:** `/Users/jeffbazinet/coding-with-claude/source/`

**Applied to:**
- File paths in displayPath
- File paths in tool invocations

**Example:**
- Before: `/Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/CLAUDE.md`
- After: `coding-with-claude-application/CLAUDE.md`

**Note:** Currently hardcoded - TODO to make configurable

---

### Size Metrics

**Typical Session:**
| Format | Size |
|--------|------|
| Raw JSONL | 2.75 MB |
| CwcSessionData JSON | 1.5-2 MB (45-27% reduction) |
| Gzipped JSON | 400-600 KB (85-78% compression) |

**Savings from:** thinking blocks (~30-40%) + deduplicated context (~10-15%) + filtered messages (~5%)

---

### Statistics Included

**CwcSessionStats:**
```typescript
{
  totalMessages: number                // User + assistant after merging
  userMessages: number
  assistantMessages: number
  filesModified: number                // Unique files changed
  totalTokens: {
    input: number
    output: number
    cacheRead: number                  // From cache_read_input_tokens
    cacheCreation: number              // Sum of all cache creation types
  }
}
```

---

### Key Design Decisions

1. **Exclude thinking blocks** - Reduces size 30-40%, can be added back via formatVersion upgrade
2. **Two-pass parsing** - Collect tool results in Pass 1, attach to assistant messages in Pass 2 (simpler than lookahead)
3. **Merge consecutive messages** - Dramatically improves readability (564 → 24 typical)
4. **Load all file versions** - Enables diff rendering and version navigation
5. **Format versioning** - `formatVersion: '1.0.0'` allows future migrations without breaking changes

---

### Processing Pipeline

1. **Parse JSONL** - Filter sidechain/meta/command messages
2. **Two-pass parsing** - Collect tool results, attach to tool_use calls
3. **Message merging** - Combine consecutive same-role messages
4. **Filter thinking** - Remove thinking blocks from content
5. **Load file versions** - Read all versions from file-history directory
6. **Compute stats** - Aggregate token usage, count messages/files
7. **Extract context once** - Get cwd, gitBranch, model from first message

---

### Related Packages

**Depends On:**
- `cwc-types` - CwcSessionData type definitions
- `cwc-transcript-parser` - Contains parser implementation

**Consumed By:**
- `cwc-website` - React components render CwcSessionData
- `cwc-api` - Upload endpoint converts JSONL → CwcSessionData → storage

---

### File Locations (Absolute Paths)

**Type definitions:** `/packages/cwc-types/src/sessionData.types.ts`
**Parser/converter:** `/packages/cwc-transcript-parser/src/converter/session-data-converter.ts`
**File loader:** `/packages/cwc-transcript-parser/src/converter/file-loader.ts`
**CLI:** `/packages/cwc-transcript-parser/src/cli.ts`
**Parser logic:** `/packages/cwc-transcript-parser/src/parser/session-parser.ts`
**Documentation:** `/packages/cwc-transcript-parser/CLAUDE.md` and `/packages/cwc-transcript-parser/README.md`

Tool Result

Perfect! I have gathered all the information needed. Let me create a comprehensive summary document.

## Summary of cwc-storage Package Implementation

Based on my exploration of the cwc-storage package, here is a detailed analysis of the current storage implementation:

### 1. Current Route Structure

**Routes defined in `/routes.ts`:**

```
/group-storage-get  (POST)  - Retrieve a file
/group-storage-put  (POST)  - Store a file  
/group-storage-delete (POST) - Delete a file
```

All routes are under the base path `/storage/v1` (defined in `StorageApiV1.path`), making the full paths:
- `POST /storage/v1/group-storage-get`
- `POST /storage/v1/group-storage-put`
- `POST /storage/v1/group-storage-delete`

Each route config includes:
- `handlerType: 'storage'` - Identifies handler factory to use
- `path` - Route path string
- `worker` - StorageFunction created by factory function
- `method` - HTTP method (POST)
- `params: undefined` - No URL parameters; payload comes from request body
- `cacheControl` - Cache directives (GET has `'public, no-transform'`, PUT/DELETE are undefined)

### 2. How Storage Functions Work

**Function Pattern (Type Definition):**

```typescript
type StorageFunction<ResultType> = (options: StorageFunctionOptions) => 
  Promise<StorageFunctionResult<ResultType>>;

type StorageFunctionOptions = { payload: RequestPayload };

type StorageFunctionResult<ResultType> = {
  success: boolean;
  error: unknown | undefined;
  data: ResultType | undefined;
};
```

**Three storage functions:**

1. **getFromStorage** (`StorageFunction<Buffer>`)
   - Payload: `{ groupId, filename }`
   - Validates groupId and filename
   - Calls `fetchFromFilesystem()` to read file
   - Returns Buffer with file contents or error

2. **putInStorage** (`StorageFunction<string>`)
   - Payload: `{ groupId, filename, dataUri }`
   - Validates groupId, filename, and dataUri
   - Calls `writeToFilesystem()` to save file
   - Ensures directory exists before writing
   - Returns filename on success

3. **deleteFromStorage** (`StorageFunction<string>`)
   - Payload: `{ groupId, filename }`
   - Validates groupId and filename
   - Calls `deleteFromFilesystem()` to remove file
   - Idempotent: treats "file not found" as success
   - Returns filename on success

**Request Flow:**
1. Express request arrives at `StorageApiV1.handler()`
2. Validates API key (x-api-key header) with timing-safe comparison
3. Validates HTTPS (production only)
4. Extracts route config from routes map
5. Creates `StorageHandler` instance with payload and route config
6. `StorageHandler.processRequest()` calls the worker function with payload
7. Returns response with status 200/400 and success flag

### 3. Type System

**Key Types:**

| Type | Purpose |
|------|---------|
| `StorageFunction<T>` | Async function that processes storage operation |
| `StorageFunctionResult<T>` | Result of storage function (success, error, data) |
| `StorageRouteConfig` | Configuration for a single route |
| `StorageRouteConfigs` | Map of all routes indexed by path |
| `StorageHandler` | Processes a single request, calls worker function |
| `StorageHandlerResponse` | Response from handler (statusCode, success, data, error) |

**All types are defined in:**
- `/apis/StorageApiV1/types.ts` - API-specific types
- `/types.ts` - General service types (RequestPayload, StorageApi)
- `/config/config.types.ts` - Configuration type (CwcStorageConfig)

### 4. How groupId is Used in Paths

**File Path Construction Pattern:**

```typescript
export const getStorageFilePath = (
  storageVolumePath: string,
  groupId: string,
  filename: string
): string => {
  return path.join(storageVolumePath, groupId, filename);
};
```

**Results in:**
```
{STORAGE_VOLUME_PATH}/{groupId}/{filename}

Example: /storage/my-group-123/document.txt
```

**Directory structure:**
- `groupId` is treated as a directory name under the storage volume
- Each group has its own subdirectory for isolation
- Prevents cross-group file access (path traversal validation ensures filename has no `/`, `\`, or `..`)

### 5. Changes Required to Replace "group" with "session-data"

**Scope of changes (minimal due to generic design):**

1. **routes.ts** (3 changes)
   - Rename route paths from `group-storage-*` to `session-data-storage-*`
   - Update comments from "group-storage" to "session-data-storage"
   - Route names: `'/session-data-storage-get'`, `'/session-data-storage-put'`, `'/session-data-storage-delete'`

2. **Storage Functions** (6 total changes)
   - Update Payload type in each function from `groupId: string` to `sessionDataId: string`
   - Update JSDoc comments to reference sessionDataId instead of groupId
   - Update function parameter names in `getFromStorage`, `putInStorage`, `deleteFromStorage`
   - Update validation error messages: `'sessionDataId is undefined'`

3. **utils.ts** (1 change)
   - Update `getStorageFilePath()` JSDoc: change parameter name `groupId` to `sessionDataId`
   - Function implementation remains identical (just variable name)

4. **No changes needed:**
   - StorageHandler - operates generically on payload
   - types.ts - no groupId reference
   - StorageApiV1 - no hardcoded groupId reference
   - Configuration - already generic

**Pattern preservation:**
- The path construction pattern remains identical
- Directory structure changes from `{VOLUME}/{groupId}/{filename}` to `{VOLUME}/{sessionDataId}/{filename}`
- All validations (filename safety, existence checks) remain unchanged

### 6. File Path Construction Pattern Summary

**Current Implementation:**
```
Base Storage Volume: /storage (configured via STORAGE_VOLUME_PATH env var)
├── group-123/
│   ├── document1.txt
│   ├── metadata.json
│   └── transcript.html
├── group-456/
│   └── data.json
```

**How it works:**
1. Three identifiers compose the full path: base volume + groupId + filename
2. Security: filename validation prevents `../` and `/` escapes
3. Isolation: groupId directory acts as namespace for all files of that group
4. Simplicity: no special naming conventions or hash functions needed

**After refactoring to session-data:**
```
Base Storage Volume: /storage (same)
├── session-001/
│   ├── document1.txt
│   ├── metadata.json
│   └── transcript.html
├── session-002/
│   └── data.json
```

The pattern is identical; only the directory naming convention changes from "group" semantics to "session-data" semantics.

Tool Result

Perfect! I have all the information I need. Let me provide a comprehensive summary of the session-related types in the cwc-types package.

## Summary: Session-Related Types in cwc-types Package

### 1. **Database Entity: CwcCodingSession**

Located in `/Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-types/src/entityTypes.ts` (lines 208-229)

This is the primary database entity that represents a coding session:

```typescript
export type CwcCodingSession = {
  codingSessionPkId: number;           // Primary key (auto-generated)
  enabled: boolean;
  createdDate: string;                 // ISO 8601
  modifiedDate: string;                // ISO 8601
  userPkId: number;                    // Foreign key to user
  projectPkId: number;                 // Foreign key to project
  description: string;
  published: boolean;
  sessionId: string;                   // Claude Code session UUID (natural key)
  storageKey: string;                  // Reference to data in cwc-storage
  startTimestamp: string;              // ISO 8601
  endTimestamp: string;                // ISO 8601
  gitBranch: string;
  model: string;
  messageCount: number;
  filesModifiedCount: number;
};
```

**Session Identification:**
- **Primary Key:** `codingSessionPkId` (numeric, auto-generated)
- **Natural Key:** `sessionId` (string UUID from Claude Code)
- **Storage Reference:** `storageKey` (points to compressed JSON in cwc-storage)

---

### 2. **Intermediate Storage Format: CwcSessionData**

Located in `/Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-types/src/sessionData.types.ts` (lines 34-123)

This is the complete parsed session data stored as gzip-compressed JSON in cwc-storage:

```typescript
export type CwcSessionData = {
  formatVersion: '1.0.0';              // Version for migrations
  sessionId: string;                   // Links to CwcCodingSession.sessionId
  projectSessionFolder: string;        // ~/.claude/projects/ folder name
  summary: string | null;              // Generated summary (if condensed)
  startTimestamp: string | null;       // ISO 8601
  endTimestamp: string | null;         // ISO 8601
  cwd: string;                         // Working directory
  gitBranch: string;
  claudeCodeVersion: string;
  model: string;
  messages: CwcSessionMessage[];       // Complete conversation
  files: CwcSessionFile[];             // All file versions edited
  stats: CwcSessionStats;              // Computed statistics
};
```

**Size Profile:**
- Raw JSONL: 2-3 MB typical
- CwcSessionData JSON: 1.5-2 MB (thinking blocks excluded)
- Gzipped: 400-600 KB (70-80% compression)

---

### 3. **Session Message Structure**

```typescript
export type CwcSessionMessage = {
  uuid: string;                        // Unique message ID
  parentUuid: string | null;           // For conversation threading
  timestamp: string;                   // ISO 8601
  role: 'user' | 'assistant';
  content: CwcSessionContent[];        // Text, tool calls, results
  tokenUsage?: CwcSessionTokenUsage;   // Optional, for assistant messages
};

export type CwcSessionContent =
  | CwcSessionTextContent
  | CwcSessionToolUseContent
  | CwcSessionToolResultContent;

export type CwcSessionTextContent = {
  type: 'text';
  text: string;
};

export type CwcSessionToolUseContent = {
  type: 'tool_use';
  id: string;                          // Links to tool_result
  name: string;                        // Tool name (Read, Edit, Bash, etc.)
  input: Record<string, unknown>;
};

export type CwcSessionToolResultContent = {
  type: 'tool_result';
  toolUseId: string;                   // Links to tool_use.id
  content: string;                     // Tool output
  isError: boolean;
};
```

---

### 4. **File History Structure**

```typescript
export type CwcSessionFile = {
  filePath: string;                    // Absolute file path
  displayPath: string;                 // Without personal prefix
  hash: string;                        // From backup filename
  versions: CwcSessionFileVersion[];   // All versions chronologically
};

export type CwcSessionFileVersion = {
  version: number;                     // 1-indexed, increments per edit
  backupFileName: string;              // Format: {hash}@v{version}
  timestamp: string;                   // ISO 8601
  content: string;                     // Complete file content
};
```

---

### 5. **Session Statistics**

```typescript
export type CwcSessionStats = {
  totalMessages: number;               // After message merging
  userMessages: number;
  assistantMessages: number;
  filesModified: number;               // Unique files
  totalTokens: {
    input: number;
    output: number;
    cacheRead: number;
    cacheCreation: number;
  };
};

export type CwcSessionTokenUsage = {
  input: number;
  output: number;
  cacheRead: number;                   // Prompt caching
  cacheCreation: number;               // Cache creation + ephemeral
};
```

---

### 6. **Related Session Entity Types**

**CwcCodingSessionContent** - Content blocks within a session (lines 255-267):
```typescript
export type CwcCodingSessionContent = {
  codingSessionContentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  contentType: CwcCodingSessionContentType;  // 'prompt' | 'response' | 'note' | 'attachment'
  codingSessionPkId: number;                  // Links to CwcCodingSession
  codingSessionAttachmentPkId?: number;      // Optional for attachments
  displayIndex: number;
  text?: string;                              // Optional
};
```

**CwcCodingSessionAttachment** - Images/files attached to sessions (lines 235-247):
```typescript
export type CwcCodingSessionAttachment = {
  codingSessionAttachmentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  codingSessionPkId: number;
  filename: string;
  mimeType: 'image/png' | 'image/jpg';
  height: number;
  width: number;
};
```

---

### Key Design Patterns

1. **Two-Level Session Storage:**
   - **Database:** `CwcCodingSession` stores metadata + storage reference
   - **Object Storage:** `CwcSessionData` stores complete parsed conversation (gzipped)

2. **Session Identification:**
   - `sessionId` is the Claude Code UUID (natural key, unique identifier)
   - `codingSessionPkId` is the database primary key (numeric, auto-generated)
   - `storageKey` references the compressed JSON file location

3. **Message Deduplication:**
   - Thinking blocks excluded from storage (~30-40% savings)
   - Messages merged during conversion from raw JSONL
   - Stats computed after deduplication

4. **File History:**
   - Complete versions stored for every file edit
   - Enables diff rendering between any two versions
   - Hash + version number enables backup file tracking

5. **Polymorphic Content:**
   - `CwcCodingSessionContent` uses `contentType` + optional `codingSessionAttachmentPkId`
   - Follows polymorphic pattern with entity type discrimination

All types exported from `/Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-types/src/index.ts`

Excellent, I now have a comprehensive understanding. Let me clarify a few things before proceeding with the plan:

Claude is asking...

Storage IDWhat identifier should be used for organizing session-data files in storage?

sessionId- Use Claude Code's UUID (e.g., 'abc123-def456...'). Natural key from transcript.

codingSessionPkId- Use the database primary key (e.g., '42'). Requires DB lookup first.

storageKey- Use a custom storage key pattern (you define the format).

Route namingWhat should the route paths be named?

session-data-*- Routes: /session-data-get, /session-data-put, /session-data-delete

coding-session-*- Routes: /coding-session-get, /coding-session-put, /coding-session-delete

session-*- Routes: /session-get, /session-put, /session-delete (shorter)

Developer Response

Q: What identifier should be used for organizing session-data files in storage?

A: "sessionId"

Q: What should the route paths be named?

A: "coding-session-data-*"

Now I have clarity:

Storage ID: Use sessionId (Claude Code's UUID)
Route naming: coding-session-data-* (e.g., /coding-session-data-get)

This is a straightforward refactoring task. Given the minimal scope (renaming identifiers and routes), I'll proceed directly to create the plan rather than launching multiple planning agents.

Plan: majestic-chasing-cocoa.md

Plan: Replace group-storage with coding-session-data-storage

Overview

Refactor cwc-storage routes and functions from group-storage-* to coding-session-data-*, replacing groupId with sessionId to support storing CwcSessionData files generated by cwc-transcript-parser.

Storage Structure

{STORAGE_VOLUME_PATH}/
├── {sessionId}/                    # Claude Code session UUID
│   ├── session-data.json.gz       # Compressed CwcSessionData
│   └── (future: other session files)

Files to Modify

1. `packages/cwc-storage/src/apis/StorageApiV1/routes.ts`

Changes:

Rename route paths from group-storage-* to coding-session-data-*
Update factory function imports

// Before
'/group-storage-get': { ... worker: createGetFromStorage(config) }
'/group-storage-put': { ... worker: createPutInStorage(config) }
'/group-storage-delete': { ... worker: createDeleteFromStorage(config) }

// After
'/coding-session-data-get': { ... worker: createGetFromStorage(config) }
'/coding-session-data-put': { ... worker: createPutInStorage(config) }
'/coding-session-data-delete': { ... worker: createDeleteFromStorage(config) }

2. `packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/getFromStorage.ts`

Changes:

Rename Payload.groupId → Payload.sessionId
Update validation error message
Update JSDoc comments

3. `packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/putInStorage.ts`

Changes:

Rename Payload.groupId → Payload.sessionId
Update validation error message
Update JSDoc comments

4. `packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/deleteFromStorage.ts`

Changes:

Rename Payload.groupId → Payload.sessionId
Update validation error message
Update JSDoc comments

5. `packages/cwc-storage/src/apis/StorageApiV1/utils.ts`

Changes:

Update getStorageFilePath() parameter name in JSDoc: groupId → sessionId
Implementation unchanged (just variable naming in comments)

6. `packages/cwc-storage/CLAUDE.md`

Changes:

Update API routes documentation
Update storage structure example
Update payload examples

API After Refactoring

Route	Method	Payload	Description
`/storage/v1/coding-session-data-get`	POST	`{ sessionId, filename }`	Retrieve session file
`/storage/v1/coding-session-data-put`	POST	`{ sessionId, filename, dataUri }`	Store session file
`/storage/v1/coding-session-data-delete`	POST	`{ sessionId, filename }`	Delete session file

Implementation Steps

Update routes.ts - rename route paths
Update getFromStorage.ts - rename groupId → sessionId in Payload type and validation
Update putInStorage.ts - rename groupId → sessionId in Payload type and validation
Update deleteFromStorage.ts - rename groupId → sessionId in Payload type and validation
Update utils.ts - update JSDoc parameter name
Update CLAUDE.md - reflect new route names and payload structure
Run pnpm storage typecheck to verify changes

Notes

Function implementations remain unchanged (just parameter naming)
Storage path pattern unchanged: {STORAGE_VOLUME_PATH}/{sessionId}/{filename}
Security validations (filename, API key, HTTPS) remain unchanged
No changes needed to types.ts, StorageHandler, or StorageApiV1 class

The plan is complete. This is a straightforward refactoring with:

6 files to modify (routes, 3 storage functions, utils, CLAUDE.md)
No logic changes - just renaming groupId → sessionId and route paths group-storage-* → coding-session-data-*
Storage structure unchanged - {STORAGE_VOLUME_PATH}/{sessionId}/{filename}

The session-data files will be stored using Claude Code's sessionId UUID as the directory identifier, which matches the natural key in CwcSessionData.sessionId and CwcCodingSession.sessionId.

Exited plan mode

Work interrupted

jeff

[Request interrupted by user for tool use]

I would actually like to put all of the coding-session-data files into a single folder named for the projectId.

Claude

Good idea - organizing by project makes sense since sessions belong to projects. Let me clarify:

Claude is asking...

Project IDWhat identifier should be used for the project folder?

projectPkId- Database primary key (e.g., '42'). Numeric, stable.

projectId- Natural key/slug (e.g., 'my-cool-project'). Human-readable if exists.

Other- Specify a different identifier pattern.

File namingWhat should the file naming pattern be within the project folder?

{sessionId}.json.gz- Use sessionId UUID as filename (e.g., 'abc123-def456.json.gz')

{timestamp}_{sessionId}.json.gz- Prefix with timestamp for sorting (e.g., '2025-11-19_abc123.json.gz')

session-data/{sessionId}.json.gz- Keep sessionId subfolder structure

Developer Response

Q: What identifier should be used for the project folder?

A: "projectId"

Q: What should the file naming pattern be within the project folder?

A: "Is there any downside to including timestamp info in the filename? If not, lets go with `{timestamp}_{sessionId}.json.gz`, but since more than one coding session can happen in a single day, we should include the `time` portion as well."

Good question! There's no real downside to including timestamp in the filename:

Pros: Natural sorting by date in file browsers, easy to find sessions chronologically, human-readable at a glance
Cons: Slightly longer filenames (negligible)

The timestamp format from cwc-transcript-parser is already {YYYY-MM-DD}_{HH-mm-ss}, so the full pattern would be:

{STORAGE_VOLUME_PATH}/{projectId}/{YYYY-MM-DD}_{HH-mm-ss}_{sessionId}.json.gz

Example:
/storage/coding-with-claude/2025-11-19_17-16-35_abc123-def456.json.gz

This gives you chronological sorting within each project folder. Let me update the plan:

Route	Method	Payload	Description
`/storage/v1/coding-session-data-get`	POST	`{ projectId, filename }`	Retrieve session file
`/storage/v1/coding-session-data-put`	POST	`{ projectId, filename, dataUri }`	Store session file
`/storage/v1/coding-session-data-delete`	POST	`{ projectId, filename }`	Delete session file

The plan is updated with:

Storage structure: {STORAGE_VOLUME_PATH}/{projectId}/{timestamp}_{sessionId}.json.gz
Route names: coding-session-data-get, coding-session-data-put, coding-session-data-delete
Payload: Uses projectId (not sessionId) as the directory identifier
Filename: {YYYY-MM-DD}_{HH-mm-ss}_{sessionId}.json.gz format (caller provides this)

This is a simple refactoring - just renaming groupId → projectId and route paths. Ready to implement?

Exited plan mode

Plan approved

All done! Here's a summary of the changes:

Summary

Refactored cwc-storage from group-storage to coding-session-data routes:

Route Changes

/storage/v1/group-storage-get → /storage/v1/coding-session-data-get
/storage/v1/group-storage-put → /storage/v1/coding-session-data-put
/storage/v1/group-storage-delete → /storage/v1/coding-session-data-delete

Payload Changes

groupId → projectId in all payloads

Files Modified

routes.ts - Route path names
getFromStorage.ts - Payload type and validation
putInStorage.ts - Payload type and validation
deleteFromStorage.ts - Payload type and validation
utils.ts - JSDoc parameter name
CLAUDE.md - Documentation updated

Storage Structure

{STORAGE_VOLUME_PATH}/
├── {projectId}/
│   ├── 2025-11-19_17-16-35_{sessionId}.json.gz
│   └── ...

Typecheck passes!

System

jeff

cwc-storage does not use the error log service. also cwc-storage uses BackendUtilsConfigBasic, because it does not require access to cwc-sql and it doesn't use database logging. so, why have we added cwc-storage to the CwcErrorLogServiceName type in packages/cwc-types/src/entityTypes.ts?

Claude

You're absolutely right to question this. Let me check what CwcErrorLogServiceName is used for and whether cwc-storage belongs there.

You're correct. CwcErrorLogServiceName is specifically used for the serviceName field on error log entries that get written to the database. Since cwc-storage:

Does NOT use database logging (uses file-based Logger instead)
Uses BackendUtilsConfigBasic (which doesn't have database access)
Will never write error log entries to the cwc_error_log table

...cwc-storage should NOT be in CwcErrorLogServiceName.

This was a mistake on my part - I added it during the previous session when adding cwc-storage to BackendServiceName in cwc-backend-utils, and incorrectly assumed it should also be added to CwcErrorLogServiceName.

The fix is simple: Remove 'cwc-storage' from CwcErrorLogServiceName in packages/cwc-types/src/entityTypes.ts.

Let me update the plan file with this correction:

The existing plan is for the route refactoring which is already complete. This is a new, simple fix. Let me update the plan file:

This is a straightforward single-line fix. The plan is complete.

Exited plan mode

Plan approved

There's a type error in cwc-backend-utils. Let me check the Logger code:

I see the issue. The Logger class uses serviceName: BackendServiceName but then assigns it to serviceName: CwcErrorLogServiceName in the error log. Let me check the Logger class definition:

The issue is clear now:

Logger accepts serviceName: BackendServiceName (which includes 'cwc-storage')
But CwcErrorLog.serviceName expects CwcErrorLogServiceName (which no longer includes 'cwc-storage')
Since BackendServiceName is a superset (includes 'cwc-storage'), TypeScript correctly reports the type mismatch

The fix here is that the Logger (which writes to database) should only accept services that can use database logging. Let me check what the types look like:

I see the problem now. The right solution is:

Keep BackendServiceName with all services (including cwc-storage)
The Logger class in cwc-backend-utils should use CwcErrorLogServiceName from cwc-types instead of BackendServiceName

This makes sense because:

BackendServiceName = all backend services
CwcErrorLogServiceName = services that can log errors to database

Let me update the Logger to use CwcErrorLogServiceName:

jeff

[Request interrupted by user]

I apologize for taking you down that path, in fact you did it correctly by adding cwc-storage to CwcErrorLogServiceName. It doesn't feel right, but to avoid a TypeScript headache, it is easier to simply add it there. We can always come back to this minor issue in the future.

Claude

No problem - you're right. The type algebra here creates a cascade of changes that aren't worth the effort for this minor semantic issue.

Let me revert the changes and restore 'cwc-storage' to CwcErrorLogServiceName:

Good - looks like the linter already restored 'cwc-storage' to CwcErrorLogServiceName. Now I just need to revert the Logger changes. Let me check its current state:

Tool Result

     1→import { CwcErrorLog } from 'cwc-types';
     2→import { SqlClient } from '../SqlClient';
     3→import {
     4→  SqlClientMutationResponse,
     5→  BackendUtilsConfig,
     6→  ILogger,
     7→  LogDebugOptions,
     8→  LogErrorOptions,
     9→  LogInformationOptions,
    10→  BackendServiceName,
    11→} from '../backendUtils.types';
    12→
    13→const errorMessageMaxLength = 2000;
    14→const errorStringMaxLength = 2000;
    15→const stackStringMaxLength = 2000;
    16→const dataStringMaxLength = 2000;
    17→const requestStringMaxLength = 3000;
    18→
    19→type InsertErrorLogOptions = {
    20→  userPkId: number | undefined;
    21→  values: Partial<CwcErrorLog>;
    22→};
    23→
    24→type WriteToLogFileOptions = {
    25→  userPkId: number | undefined;
    26→  errorType: 'error' | 'info' | 'debug';
    27→  codeLocation: string;
    28→  message?: string | object;
    29→  error?: unknown | Error | string | object;
    30→  value?: string | object | unknown;
    31→  request?: string | unknown;
    32→  projectPkId?: number | undefined;
    33→};
    34→
    35→type LoggerOptions = {
    36→  config: BackendUtilsConfig;
    37→  serviceName: BackendServiceName;
    38→};
    39→
    40→export class Logger implements ILogger {
    41→  private config: BackendUtilsConfig;
    42→  private serviceName: BackendServiceName;
    43→  private sqlClient: SqlClient | undefined;
    44→
    45→  constructor({ config, serviceName }: LoggerOptions) {
    46→    this.config = config;
    47→    this.serviceName = serviceName;
    48→  }
    49→
    50→  private getSqlClient() {

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>

The Logger is already back to using BackendServiceName. Both files are in their correct state. Let me run typecheck to confirm everything passes:

Tool Result

> coding-with-claude-application@1.0.0 typecheck /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application
> turbo run typecheck

• Packages in scope: cwc-backend-utils, cwc-deployment, cwc-schema, cwc-sql, cwc-storage, cwc-transcript-parser, cwc-types, cwc-utils
• Running typecheck in 8 packages
• Remote caching disabled
cwc-types:build: cache miss, executing 6128634cd7f420bf
cwc-utils:typecheck: cache hit, replaying logs 4b2c014801e11559
cwc-utils:typecheck: 
cwc-utils:typecheck: > cwc-utils@1.0.0 typecheck /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-utils
cwc-utils:typecheck: > tsc --noEmit
cwc-utils:typecheck: 
cwc-types:typecheck: cache miss, executing 22d6a4a4a55a0f5d
cwc-deployment:typecheck: cache hit, replaying logs 799bf343fe5911ee
cwc-deployment:typecheck: 
cwc-deployment:typecheck: > cwc-deployment@1.0.0 typecheck /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-deployment
cwc-deployment:typecheck: > tsc --noEmit
cwc-deployment:typecheck: 
cwc-schema:typecheck: cache hit, replaying logs a2e4fc15b7232f20
cwc-schema:typecheck: 
cwc-schema:typecheck: > cwc-schema@1.0.0 typecheck /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-schema
cwc-schema:typecheck: > tsc --noEmit
cwc-schema:typecheck: 
cwc-schema:build: cache hit, replaying logs 41dd5101811f257b
cwc-schema:build: 
cwc-schema:build: > cwc-schema@1.0.0 build /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-schema
cwc-schema:build: > tsc
cwc-schema:build: 
cwc-types:typecheck: 
cwc-types:typecheck: > cwc-types@1.0.0 typecheck /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-types
cwc-types:typecheck: > tsc --noEmit
cwc-types:typecheck: 
cwc-types:build: 
cwc-types:build: > cwc-types@1.0.0 build /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-types
cwc-types:build: > tsc
cwc-types:build: 
cwc-backend-utils:build: cache miss, executing 8e313069c3a0ddf1
cwc-transcript-parser:typecheck: cache miss, executing 0abc30107b9808d1
cwc-backend-utils:typecheck: cache miss, executing de70f404d746e63f
cwc-backend-utils:build: 
cwc-backend-utils:build: > cwc-backend-utils@1.0.0 build /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-backend-utils
cwc-backend-utils:build: > tsc
cwc-backend-utils:build: 
cwc-transcript-parser:typecheck: 
cwc-transcript-parser:typecheck: > cwc-transcript-parser@1.0.0 typecheck /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-transcript-parser
cwc-transcript-parser:typecheck: > tsc --noEmit
cwc-transcript-parser:typecheck: 
cwc-backend-utils:typecheck: 
cwc-backend-utils:typecheck: > cwc-backend-utils@1.0.0 typecheck /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-backend-utils
cwc-backend-utils:typecheck: > tsc --noEmit
cwc-backend-utils:typecheck: 
cwc-storage:typecheck: cache miss, executing 45d29d33bb05283e
cwc-sql:typecheck: cache miss, executing f92b097f3b4b6e16
cwc-storage:typecheck: 
cwc-storage:typecheck: > cwc-storage@1.0.0 typecheck /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-storage
cwc-storage:typecheck: > tsc --noEmit
cwc-storage:typecheck: 
cwc-sql:typecheck: 
cwc-sql:typecheck: > cwc-sql@1.0.0 typecheck /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-sql
cwc-sql:typecheck: > tsc --noEmit
cwc-sql:typecheck: 

 Tasks:    11 successful, 11 total
Cached:    4 cached, 11 total
  Time:    2.323s
turbo 2.6.1

Typecheck passes. Everything is back to the original working state with 'cwc-storage' in CwcErrorLogServiceName.

To summarize: cwc-storage remains in both:

BackendServiceName (in cwc-backend-utils) - all backend services
CwcErrorLogServiceName (in cwc-types) - pragmatic choice to avoid TypeScript type narrowing complexity

The semantic imprecision (cwc-storage won't actually write to error log database) is acceptable for now. We can revisit if it becomes a problem.

Session 13: cwc storage

23 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.

CRITICAL: Role and Professional Standards

Claude Code's role on this project is to serve as a "highly experienced senior software engineer and application architect" with "in-depth understanding of the CWC codebase, conventions, and rules."

It is assumed, and imperative, that as a senior engineer, you will do your due diligence:

Required Due Diligence for Every Task

Before proposing any design, architecture, or implementation:

Read all relevant package CLAUDE.md files
- If touching database → read packages/cwc-database/CLAUDE.md
- If defining/modifying types → read packages/cwc-types/CLAUDE.md
- If working with any package → read that package's CLAUDE.md file
- Package-specific conventions MUST be followed
Examine existing code in all affected packages
- Check for existing types, schemas, or utilities before proposing new ones
- Understand established patterns and conventions
- Identify dependencies between packages
Understand the full scope
- Identify all packages affected by the feature or change
- Consider both direct changes and indirect impacts (shared types, utilities, etc.)
- Plan across package boundaries, not in isolation

Cross-Package Feature Planning

When working on features that span multiple packages:

Discovery phase first - Survey the landscape before designing
Read documentation - All relevant package CLAUDE.md files
Examine existing implementations - Check for related code/patterns
Design within constraints - Follow established conventions
Present context with design - Show what you reviewed and how your design follows patterns

This is not optional. The developer should not have to repeatedly point out missed conventions or overlooked existing code. Professional engineers build on institutional knowledge rather than reinventing or contradicting established patterns.

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.

CLAUDE.md File Specification

Purpose: CLAUDE.md files are memory files for AI assistants (like Claude Code), NOT documentation for human developers.

What CLAUDE.md IS for:

Architectural patterns and critical design decisions
Code conventions, naming rules, and style preferences
What to check during planning sessions
Lessons learned and mistakes to avoid
Project-specific security rules and compliance requirements
Critical implementation patterns that must be followed
"If you see X, always do Y" type rules
Checklists for common operations

What CLAUDE.md is NOT for (belongs in README.md):

API documentation and endpoint specifications
Usage examples and tutorials for humans
Setup and installation instructions
General explanations and marketing copy
Step-by-step guides and how-tos
Detailed configuration walkthroughs
Complete type definitions (already in code)
Performance tuning guides for users

File Size Targets:

Warning threshold: 40,000 characters per file (Claude Code performance degrades)
Recommended: Keep under 500 lines when possible for fast loading
Best practice: If a package CLAUDE.md approaches 300-400 lines, review for README-style content
For large packages: Use concise bullet points; move examples to README

Content Guidelines:

Be specific and actionable: "Use 2-space indentation" not "Format code properly"
Focus on patterns: Show the pattern, explain when to use it
Include context for decisions: Why this approach, not alternatives
Use code examples sparingly: Only when pattern is complex
Keep it scannable: Bullet points and clear headers

CLAUDE.md vs README.md:

CLAUDE.md	README.md
For AI assistants	For human developers
Patterns and rules	Complete documentation
What to check/avoid	How to use and setup
Concise and focused	Comprehensive and detailed
Loaded on every session	Read when needed

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
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

Code Review Workflow Patterns

CRITICAL: When the developer provides comprehensive code review feedback and requests step-by-step discussion.

Developer Should Continue Providing Comprehensive Feedback Lists

Encourage the developer to provide ALL feedback items in a single comprehensive list. This is highly valuable because:

Gives full context about scope of changes
Allows identification of dependencies between issues
Helps spot patterns across multiple points
More efficient than addressing issues one at a time

Never discourage comprehensive feedback. The issue is not the list size, but how Claude Code presents the response.

Recognize Step-by-Step Request Signals

When the developer says any of these phrases:

"review each of these in order step by step"
"discuss each point one by one"
"let's go through these one at a time"
"walk me through each item"

This is a request for ITERATIVE discussion, not a comprehensive dump of all analysis.

Step-by-Step Review Pattern (Default for Code Reviews)

When developer provides comprehensive feedback with step-by-step request:

✅ Correct approach:

Present ONLY Point 1 with:
- The developer's original feedback for that point
- Claude's analysis and thoughts
- Any clarifying questions needed
- Recommendation for what to do
Wait for developer response and engage in discussion if needed
After Point 1 is resolved, present Point 2 using same format
Continue iteratively through all points
After all points discussed, ask "Ready to implement?" and show summary of agreed changes

Message format for each point:

## Point N: [Topic Name]

**Your Feedback:**
[Quote the developer's original feedback for this point]

**My Analysis:**
[Thoughts on this specific point only]

**Questions:** [If clarification needed]
- Question 1?
- Question 2?

**Recommendation:**
[What Claude thinks should be done]

---
*Waiting for your thoughts on Point N before moving to Point N+1.*

❌ What NOT to do:

Present all 10-15 points with full analysis at once
Make the developer reference "Point 7" or scroll to find what they want to discuss
Skip the iterative conversation pattern when explicitly requested

Alternative: Full Analysis First Pattern

Only use this pattern when developer explicitly requests it:

Developer says:

"Give me your analysis on all points first"
"Show me all your recommendations, then we'll discuss"
"I want to see the big picture before deciding"

In this case:

Present comprehensive analysis of all points
Wait for developer to identify which points need discussion
Focus conversation only on points developer has questions about

Benefits of Step-by-Step Pattern

Easy to follow: Each message is focused on one decision
Encourages discussion: Natural to discuss one topic at a time
No reference confusion: No need to say "regarding Point 7..."
Clear progress: Both parties know exactly where we are in the review
Better decisions: Focused attention leads to better analysis

Implementation Phase

After all review points are discussed and decisions made:

Summarize all agreed changes in a checklist format
Ask for explicit approval to proceed: "Ready to implement these changes?"
Proceed with implementation in logical groups
Update documentation if patterns/learnings emerged during review

Session 010 Learning: This pattern was established after Claude Code incorrectly presented all 14 review points at once despite clear request for step-by-step discussion. This made it difficult for the developer to engage in focused discussion on individual points.

Version 2 (latest)

CLAUDE.md

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

CRITICAL: Role and Professional Standards

It is assumed, and imperative, that as a senior engineer, you will do your due diligence:

Required Due Diligence for Every Task

Before proposing any design, architecture, or implementation:

Read all relevant package CLAUDE.md files
- If touching database → read packages/cwc-database/CLAUDE.md
- If defining/modifying types → read packages/cwc-types/CLAUDE.md
- If working with any package → read that package's CLAUDE.md file
- Package-specific conventions MUST be followed
Examine existing code in all affected packages
- Check for existing types, schemas, or utilities before proposing new ones
- Understand established patterns and conventions
- Identify dependencies between packages
Understand the full scope
- Identify all packages affected by the feature or change
- Consider both direct changes and indirect impacts (shared types, utilities, etc.)
- Plan across package boundaries, not in isolation

Cross-Package Feature Planning

When working on features that span multiple packages:

Discovery phase first - Survey the landscape before designing
Read documentation - All relevant package CLAUDE.md files
Examine existing implementations - Check for related code/patterns
Design within constraints - Follow established conventions
Present context with design - Show what you reviewed and how your design follows patterns

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.

CLAUDE.md File Specification

Purpose: CLAUDE.md files are memory files for AI assistants (like Claude Code), NOT documentation for human developers.

What CLAUDE.md IS for:

Architectural patterns and critical design decisions
Code conventions, naming rules, and style preferences
What to check during planning sessions
Lessons learned and mistakes to avoid
Project-specific security rules and compliance requirements
Critical implementation patterns that must be followed
"If you see X, always do Y" type rules
Checklists for common operations

What CLAUDE.md is NOT for (belongs in README.md):

API documentation and endpoint specifications
Usage examples and tutorials for humans
Setup and installation instructions
General explanations and marketing copy
Step-by-step guides and how-tos
Detailed configuration walkthroughs
Complete type definitions (already in code)
Performance tuning guides for users

File Size Targets:

Warning threshold: 40,000 characters per file (Claude Code performance degrades)
Recommended: Keep under 500 lines when possible for fast loading
Best practice: If a package CLAUDE.md approaches 300-400 lines, review for README-style content
For large packages: Use concise bullet points; move examples to README

Content Guidelines:

Be specific and actionable: "Use 2-space indentation" not "Format code properly"
Focus on patterns: Show the pattern, explain when to use it
Include context for decisions: Why this approach, not alternatives
Use code examples sparingly: Only when pattern is complex
Keep it scannable: Bullet points and clear headers

CLAUDE.md vs README.md:

CLAUDE.md	README.md
For AI assistants	For human developers
Patterns and rules	Complete documentation
What to check/avoid	How to use and setup
Concise and focused	Comprehensive and detailed
Loaded on every session	Read when needed

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 Entry Points (CRITICAL - bundler resolution):
- Point main, types, and exports to ./src/index.ts (NOT ./dist)
- With bundler module resolution, we reference TypeScript source directly
- Example:
```
"main": "./src/index.ts",
"types": "./src/index.ts",
"exports": {
  ".": {
    "types": "./src/index.ts",
    "default": "./src/index.ts"
  }
}
```
- ❌ NEVER use ./dist/index.js or ./dist/index.d.ts
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

Code Review Workflow Patterns

CRITICAL: When the developer provides comprehensive code review feedback and requests step-by-step discussion.

Developer Should Continue Providing Comprehensive Feedback Lists

Encourage the developer to provide ALL feedback items in a single comprehensive list. This is highly valuable because:

Gives full context about scope of changes
Allows identification of dependencies between issues
Helps spot patterns across multiple points
More efficient than addressing issues one at a time

Never discourage comprehensive feedback. The issue is not the list size, but how Claude Code presents the response.

Recognize Step-by-Step Request Signals

When the developer says any of these phrases:

"review each of these in order step by step"
"discuss each point one by one"
"let's go through these one at a time"
"walk me through each item"

This is a request for ITERATIVE discussion, not a comprehensive dump of all analysis.

Step-by-Step Review Pattern (Default for Code Reviews)

When developer provides comprehensive feedback with step-by-step request:

✅ Correct approach:

Present ONLY Point 1 with:
- The developer's original feedback for that point
- Claude's analysis and thoughts
- Any clarifying questions needed
- Recommendation for what to do
Wait for developer response and engage in discussion if needed
After Point 1 is resolved, present Point 2 using same format
Continue iteratively through all points
After all points discussed, ask "Ready to implement?" and show summary of agreed changes

Message format for each point:

## Point N: [Topic Name]

**Your Feedback:**
[Quote the developer's original feedback for this point]

**My Analysis:**
[Thoughts on this specific point only]

**Questions:** [If clarification needed]
- Question 1?
- Question 2?

**Recommendation:**
[What Claude thinks should be done]

---
*Waiting for your thoughts on Point N before moving to Point N+1.*

❌ What NOT to do:

Present all 10-15 points with full analysis at once
Make the developer reference "Point 7" or scroll to find what they want to discuss
Skip the iterative conversation pattern when explicitly requested

Alternative: Full Analysis First Pattern

Only use this pattern when developer explicitly requests it:

Developer says:

"Give me your analysis on all points first"
"Show me all your recommendations, then we'll discuss"
"I want to see the big picture before deciding"

In this case:

Present comprehensive analysis of all points
Wait for developer to identify which points need discussion
Focus conversation only on points developer has questions about

Benefits of Step-by-Step Pattern

Easy to follow: Each message is focused on one decision
Encourages discussion: Natural to discuss one topic at a time
No reference confusion: No need to say "regarding Point 7..."
Clear progress: Both parties know exactly where we are in the review
Better decisions: Focused attention leads to better analysis

Implementation Phase

After all review points are discussed and decisions made:

Summarize all agreed changes in a checklist format
Ask for explicit approval to proceed: "Ready to implement these changes?"
Proceed with implementation in logical groups
Update documentation if patterns/learnings emerged during review

package.json

2 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}\"",
    "backend-utils": "pnpm --filter cwc-backend-utils",
    "database": "pnpm --filter cwc-database",
    "deployment": "pnpm --filter cwc-deployment",
    "schema": "pnpm --filter cwc-schema",
    "sql": "pnpm --filter cwc-sql",
    "transcript-parser": "pnpm --filter cwc-transcript-parser",
    "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"
}

Version 2 (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",
    "sql": "pnpm --filter cwc-sql",
    "storage": "pnpm --filter cwc-storage",
    "transcript-parser": "pnpm --filter cwc-transcript-parser",
    "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/src/backendUtils.types.ts

2 versions

Version 1

import http from 'node:http';
import { RequestHandler } from 'express';
import express from 'express';

export type BackendServiceName = 'cwc-admin-api' | 'cwc-api' | 'cwc-auth' | 'cwc-sql';

export type BackendUtilsConfig = {
  debugMode: boolean;
  dataUri: string;
  logErrorsToDatabase: boolean;
  isDevelopment: boolean;
  isTest: boolean;
  isProduction: boolean;
  isUnitTest: boolean;
  isEndToEnd: boolean;
  corsOrigin: string;
  servicePort: number;
  rateLimiterPoints: number;
  rateLimiterDuration: number;
  // development settings
  devMachines:
    | undefined
    | {
        name: string;
        ip: string;
      }[];
  devCorsOrigin: string;
  // service api
  serviceApi?: {
    allowedIps: string;
  };
  // End-to-end testing mock values
  endToEndMockValues?: Record<string, string> | undefined;
};

// Simplified config for services that don't use SqlClient or database logging
export type BackendUtilsConfigBasic = Omit<BackendUtilsConfig, 'dataUri' | 'logErrorsToDatabase'>;

// *********************************
// SqlClient
// *********************************

export type SqlClientToken = string;

export type SqlClientOperationType = 'delete' | 'insert' | 'select' | 'update';

export type SqlClientOperationName = string;
export type SqlClientOperationTable = string;

export type SqlClientOperationFilters = {
  [key: string]: string | number | boolean | number[];
};

export type SqlClientOperationFields = string[] | undefined;

export type SqlClientOperationValues = {
  [key: string]: string | number | boolean | undefined | unknown | unknown[];
};

export type SqlClientOperationSortItem = {
  fieldName: string;
  direction?: string;
};

export type SqlClientOperationSort = SqlClientOperationSortItem[];

export type SqlClientOperationLimit = {
  recordCount: number;
  startIndex: number;
};

export type SqlClientOperationCustomSql = string;

export type SqlClientOperationCustomParam = string | number | boolean;

export type SqlClientOperationCustomParams = {
  [key: string]: SqlClientOperationCustomParam;
};

// **********************************
// sort example:
// **********************************
// const sort = [ {fieldName: 'username', direction: 'ASC' }, {fieldName: 'groupName', direction: 'DESC' }];

export type SqlClientOperationCustom = {
  customSql: SqlClientOperationCustomSql;
  customParams: SqlClientOperationCustomParams;
  customTables: SqlClientOperationTable[];
};

export type SqlClientOperation = {
  operationType: SqlClientOperationType;
  name?: SqlClientOperationName | undefined;
  table: SqlClientOperationTable | undefined;
  fields?: SqlClientOperationFields | undefined;
  filters?: SqlClientOperationFilters | undefined;
  values?: SqlClientOperationValues | undefined;
  sort?: SqlClientOperationSort | undefined;
  limit?: SqlClientOperationLimit | undefined;
  custom?: SqlClientOperationCustom | undefined;
  filterCount?: boolean | undefined; // return a count of records matching filters
};

export type SqlClientSchemaOptions = {
  userPkId: number | undefined;
};

export type Schema = {
  [key: string]: object;
};

export type SqlClientSchemaResponse = {
  data: Schema;
};

export type SqlClientCommand = {
  transaction: boolean;
  operations: SqlClientOperation[];
  filterCount: boolean; // return filtered record count with results
};

export type SqlClientExecuteOptions = {
  userPkId: number | undefined;
  command: SqlClientCommand;
};

export interface SqlClientQueryResponse {
  [key: string]: unknown[] | undefined;
}

export type SqlClientMutationResult = {
  affectedRows?: number;
  insertId?: number;
  changedRows?: number;
};

export interface SqlClientMutationResponse {
  [key: string]: SqlClientMutationResult;
}

export type SqlClientExecuteQuery = (
  options: SqlClientExecuteOptions
) => Promise<SqlClientQueryResponse | undefined>;

export type SqlClientExecuteMutation = (
  options: SqlClientExecuteOptions
) => Promise<SqlClientMutationResponse | undefined>;

export type VerifySqlClientCredentialsOptions = {
  userPkId: number | undefined;
  authToken: string | undefined;
  invokedBy: string;
};

export type DeleteCommandOptions = Omit<
  SqlClientOperation,
  'operationType' | 'fields' | 'values' | 'sort' | 'limit' | 'custom'
>;

export type InsertCommandOptions = Omit<
  SqlClientOperation,
  'operationType' | 'fields' | 'filters' | 'sort' | 'limit' | 'custom'
>;

export type SelectCommandOptions = Omit<SqlClientOperation, 'operationType' | 'values'>;

export type UpdateCommandOptions = Omit<
  SqlClientOperation,
  'operationType' | 'fields' | 'sort' | 'limit' | 'custom'
>;

export type OperationDetails = Omit<SqlClientOperation, 'table' | 'operationType'>;

export type AddOperationOptions = {
  command: SqlClientCommand;
  table: string | undefined;
  operationType: SqlClientOperationType;
  operationDetails: OperationDetails;
};

export type SqlClientType = {
  query: ({
    userPkId,
    command,
  }: SqlClientExecuteOptions) => Promise<SqlClientQueryResponse | undefined>;
  mutate: ({
    userPkId,
    command,
  }: SqlClientExecuteOptions) => Promise<SqlClientMutationResponse | undefined>;

  getFirstResult: <ResultType>(
    response: SqlClientQueryResponse | undefined
  ) => ResultType | undefined;

  getSecondResult: <ResultType>(
    response: SqlClientQueryResponse | undefined
  ) => ResultType | undefined;

  getResult: <ResultType>(
    response: SqlClientQueryResponse | undefined,
    name: string,
    index: number
  ) => ResultType | undefined;

  getFirstResults: <ResultType>(response: SqlClientQueryResponse | undefined) => ResultType[];

  getSecondResults: <ResultType>(response: SqlClientQueryResponse | undefined) => ResultType[];

  getResults: <ResultType>(
    response: SqlClientQueryResponse | undefined,
    name: string
  ) => ResultType[];

  getInsertResult: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => boolean;

  getInsertResultId: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => number | undefined;

  getUpdateResult: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => boolean;

  getDeleteResult: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => boolean;

  emptyCommand: (transaction: boolean) => SqlClientCommand;

  deleteCommand: ({ name, table, filters }: DeleteCommandOptions) => SqlClientCommand;

  insertCommand: ({ name, table, values }: InsertCommandOptions) => SqlClientCommand;

  selectCommand: ({
    name,
    table,
    filters,
    fields,
    sort,
    limit,
    custom,
    filterCount,
  }: SelectCommandOptions) => SqlClientCommand;

  updateCommand: ({ name, table, filters, values }: UpdateCommandOptions) => SqlClientCommand;

  addOperation: ({
    command,
    table,
    operationType,
    operationDetails,
  }: AddOperationOptions) => SqlClientOperation | undefined;
};

// *********************************
// Logger
// *********************************

export interface ILogger {
  logDebug: ({ codeLocation, message, value }: LogDebugOptions) => void;
  logError: ({ codeLocation, message, error, value, request }: LogErrorOptions) => Promise<void>;
  logInformation: ({ codeLocation, message, value }: LogInformationOptions) => void;
}

export type LogErrorOptions = {
  userPkId: number | undefined;
  codeLocation: string;
  message: string;
  error?: unknown | Error | object | string;
  value?: object | string | unknown;
  request?: string | unknown;
};

export type LogInformationOptions = {
  userPkId: number | undefined;
  codeLocation: string;
  message: string;
  value?: object | string;
  request?: string | unknown;
};

export type LogDebugOptions = {
  userPkId: number | undefined;
  codeLocation: string;
  message: string;
  value?: object | string;
  request?: string | unknown;
};

// *********************************
// express
// *********************************

export interface ExpressApi {
  version: number;
  handler: RequestHandler;
  path: string;
}

export type ExpressCorsOptions = {
  config: BackendUtilsConfig;
  allowPost: boolean;
  allowOptions: boolean;
  allowGet: boolean;
};

export type ExpressInvalidRoutesOptions = {
  apis: ExpressApi[];
  allowPost: boolean;
  allowOptions: boolean;
  allowGet: boolean;
};

export type ExpressRateLimiterOptions = {
  config: BackendUtilsConfig;
};

export type ExpressServiceOptions = {
  config: BackendUtilsConfig | BackendUtilsConfigBasic;
  serviceName: BackendServiceName;
  apis: ExpressApi[];
  allowPost: boolean;
  allowOptions: boolean;
  allowGet: boolean;
  payloadLimit: string | undefined; // eg: 2mb
};

export type ExpressService = {
  expressApp: express.Express;
  httpServer: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
  start(apis: ExpressApi[]): void;
};

Version 2 (latest)

import http from 'node:http';
import { RequestHandler } from 'express';
import express from 'express';

export type BackendServiceName = 'cwc-admin-api' | 'cwc-api' | 'cwc-auth' | 'cwc-sql' | 'cwc-storage';

export type BackendUtilsConfig = {
  debugMode: boolean;
  dataUri: string;
  logErrorsToDatabase: boolean;
  isDevelopment: boolean;
  isTest: boolean;
  isProduction: boolean;
  isUnitTest: boolean;
  isEndToEnd: boolean;
  corsOrigin: string;
  servicePort: number;
  rateLimiterPoints: number;
  rateLimiterDuration: number;
  // development settings
  devMachines:
    | undefined
    | {
        name: string;
        ip: string;
      }[];
  devCorsOrigin: string;
  // service api
  serviceApi?: {
    allowedIps: string;
  };
  // End-to-end testing mock values
  endToEndMockValues?: Record<string, string> | undefined;
};

// Simplified config for services that don't use SqlClient or database logging
export type BackendUtilsConfigBasic = Omit<BackendUtilsConfig, 'dataUri' | 'logErrorsToDatabase'>;

// *********************************
// SqlClient
// *********************************

export type SqlClientToken = string;

export type SqlClientOperationType = 'delete' | 'insert' | 'select' | 'update';

export type SqlClientOperationName = string;
export type SqlClientOperationTable = string;

export type SqlClientOperationFilters = {
  [key: string]: string | number | boolean | number[];
};

export type SqlClientOperationFields = string[] | undefined;

export type SqlClientOperationValues = {
  [key: string]: string | number | boolean | undefined | unknown | unknown[];
};

export type SqlClientOperationSortItem = {
  fieldName: string;
  direction?: string;
};

export type SqlClientOperationSort = SqlClientOperationSortItem[];

export type SqlClientOperationLimit = {
  recordCount: number;
  startIndex: number;
};

export type SqlClientOperationCustomSql = string;

export type SqlClientOperationCustomParam = string | number | boolean;

export type SqlClientOperationCustomParams = {
  [key: string]: SqlClientOperationCustomParam;
};

// **********************************
// sort example:
// **********************************
// const sort = [ {fieldName: 'username', direction: 'ASC' }, {fieldName: 'groupName', direction: 'DESC' }];

export type SqlClientOperationCustom = {
  customSql: SqlClientOperationCustomSql;
  customParams: SqlClientOperationCustomParams;
  customTables: SqlClientOperationTable[];
};

export type SqlClientOperation = {
  operationType: SqlClientOperationType;
  name?: SqlClientOperationName | undefined;
  table: SqlClientOperationTable | undefined;
  fields?: SqlClientOperationFields | undefined;
  filters?: SqlClientOperationFilters | undefined;
  values?: SqlClientOperationValues | undefined;
  sort?: SqlClientOperationSort | undefined;
  limit?: SqlClientOperationLimit | undefined;
  custom?: SqlClientOperationCustom | undefined;
  filterCount?: boolean | undefined; // return a count of records matching filters
};

export type SqlClientSchemaOptions = {
  userPkId: number | undefined;
};

export type Schema = {
  [key: string]: object;
};

export type SqlClientSchemaResponse = {
  data: Schema;
};

export type SqlClientCommand = {
  transaction: boolean;
  operations: SqlClientOperation[];
  filterCount: boolean; // return filtered record count with results
};

export type SqlClientExecuteOptions = {
  userPkId: number | undefined;
  command: SqlClientCommand;
};

export interface SqlClientQueryResponse {
  [key: string]: unknown[] | undefined;
}

export type SqlClientMutationResult = {
  affectedRows?: number;
  insertId?: number;
  changedRows?: number;
};

export interface SqlClientMutationResponse {
  [key: string]: SqlClientMutationResult;
}

export type SqlClientExecuteQuery = (
  options: SqlClientExecuteOptions
) => Promise<SqlClientQueryResponse | undefined>;

export type SqlClientExecuteMutation = (
  options: SqlClientExecuteOptions
) => Promise<SqlClientMutationResponse | undefined>;

export type VerifySqlClientCredentialsOptions = {
  userPkId: number | undefined;
  authToken: string | undefined;
  invokedBy: string;
};

export type DeleteCommandOptions = Omit<
  SqlClientOperation,
  'operationType' | 'fields' | 'values' | 'sort' | 'limit' | 'custom'
>;

export type InsertCommandOptions = Omit<
  SqlClientOperation,
  'operationType' | 'fields' | 'filters' | 'sort' | 'limit' | 'custom'
>;

export type SelectCommandOptions = Omit<SqlClientOperation, 'operationType' | 'values'>;

export type UpdateCommandOptions = Omit<
  SqlClientOperation,
  'operationType' | 'fields' | 'sort' | 'limit' | 'custom'
>;

export type OperationDetails = Omit<SqlClientOperation, 'table' | 'operationType'>;

export type AddOperationOptions = {
  command: SqlClientCommand;
  table: string | undefined;
  operationType: SqlClientOperationType;
  operationDetails: OperationDetails;
};

export type SqlClientType = {
  query: ({
    userPkId,
    command,
  }: SqlClientExecuteOptions) => Promise<SqlClientQueryResponse | undefined>;
  mutate: ({
    userPkId,
    command,
  }: SqlClientExecuteOptions) => Promise<SqlClientMutationResponse | undefined>;

  getFirstResult: <ResultType>(
    response: SqlClientQueryResponse | undefined
  ) => ResultType | undefined;

  getSecondResult: <ResultType>(
    response: SqlClientQueryResponse | undefined
  ) => ResultType | undefined;

  getResult: <ResultType>(
    response: SqlClientQueryResponse | undefined,
    name: string,
    index: number
  ) => ResultType | undefined;

  getFirstResults: <ResultType>(response: SqlClientQueryResponse | undefined) => ResultType[];

  getSecondResults: <ResultType>(response: SqlClientQueryResponse | undefined) => ResultType[];

  getResults: <ResultType>(
    response: SqlClientQueryResponse | undefined,
    name: string
  ) => ResultType[];

  getInsertResult: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => boolean;

  getInsertResultId: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => number | undefined;

  getUpdateResult: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => boolean;

  getDeleteResult: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => boolean;

  emptyCommand: (transaction: boolean) => SqlClientCommand;

  deleteCommand: ({ name, table, filters }: DeleteCommandOptions) => SqlClientCommand;

  insertCommand: ({ name, table, values }: InsertCommandOptions) => SqlClientCommand;

  selectCommand: ({
    name,
    table,
    filters,
    fields,
    sort,
    limit,
    custom,
    filterCount,
  }: SelectCommandOptions) => SqlClientCommand;

  updateCommand: ({ name, table, filters, values }: UpdateCommandOptions) => SqlClientCommand;

  addOperation: ({
    command,
    table,
    operationType,
    operationDetails,
  }: AddOperationOptions) => SqlClientOperation | undefined;
};

// *********************************
// Logger
// *********************************

export interface ILogger {
  logDebug: ({ codeLocation, message, value }: LogDebugOptions) => void;
  logError: ({ codeLocation, message, error, value, request }: LogErrorOptions) => Promise<void>;
  logInformation: ({ codeLocation, message, value }: LogInformationOptions) => void;
}

export type LogErrorOptions = {
  userPkId: number | undefined;
  codeLocation: string;
  message: string;
  error?: unknown | Error | object | string;
  value?: object | string | unknown;
  request?: string | unknown;
};

export type LogInformationOptions = {
  userPkId: number | undefined;
  codeLocation: string;
  message: string;
  value?: object | string;
  request?: string | unknown;
};

export type LogDebugOptions = {
  userPkId: number | undefined;
  codeLocation: string;
  message: string;
  value?: object | string;
  request?: string | unknown;
};

// *********************************
// express
// *********************************

export interface ExpressApi {
  version: number;
  handler: RequestHandler;
  path: string;
}

export type ExpressCorsOptions = {
  config: BackendUtilsConfig;
  allowPost: boolean;
  allowOptions: boolean;
  allowGet: boolean;
};

export type ExpressInvalidRoutesOptions = {
  apis: ExpressApi[];
  allowPost: boolean;
  allowOptions: boolean;
  allowGet: boolean;
};

export type ExpressRateLimiterOptions = {
  config: BackendUtilsConfig;
};

export type ExpressServiceOptions = {
  config: BackendUtilsConfig | BackendUtilsConfigBasic;
  serviceName: BackendServiceName;
  apis: ExpressApi[];
  allowPost: boolean;
  allowOptions: boolean;
  allowGet: boolean;
  payloadLimit: string | undefined; // eg: 2mb
};

export type ExpressService = {
  expressApp: express.Express;
  httpServer: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
  start(apis: ExpressApi[]): void;
};

packages/cwc-backend-utils/src/configHelpers.ts

2 versions

Version 1

/**
 * Configuration parsing helpers for backend services
 * These helpers provide consistent parsing and validation of environment variables
 */

/**
 * Gets a required environment variable, throwing if not present
 */
export function requireEnv(name: string): string {
  const value = process.env[name];
  if (value === undefined || value === '') {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

/**
 * Gets an optional environment variable with a default value
 */
export function optionalEnv(name: string, defaultValue: string): string {
  const value = process.env[name];
  if (value === undefined || value === '') {
    return defaultValue;
  }
  return value;
}

/**
 * Parses an environment variable as a number
 */
export function parseNumber(name: string, defaultValue?: number): number {
  const value = process.env[name];
  if (value === undefined || value === '') {
    if (defaultValue !== undefined) {
      return defaultValue;
    }
    throw new Error(`Missing required environment variable: ${name}`);
  }

  const parsed = Number(value);
  if (isNaN(parsed)) {
    throw new Error(`Environment variable ${name} must be a number, got: ${value}`);
  }
  return parsed;
}

/**
 * Parses an environment variable as a boolean (ON/OFF or TRUE/FALSE)
 */
export function parseBoolean(name: string, defaultValue: boolean = false): boolean {
  const value = process.env[name];
  if (value === undefined || value === '') {
    return defaultValue;
  }

  const upper = value.toUpperCase();
  if (upper === 'ON' || upper === 'TRUE' || upper === '1') {
    return true;
  }
  if (upper === 'OFF' || upper === 'FALSE' || upper === '0') {
    return false;
  }

  throw new Error(`Environment variable ${name} must be ON/OFF or TRUE/FALSE, got: ${value}`);
}

/**
 * Parses a comma-separated environment variable into an array
 */
export function parseArray(name: string, defaultValue: string[] = []): string[] {
  const value = process.env[name];
  if (value === undefined || value === '') {
    return defaultValue;
  }

  return value
    .split(',')
    .map((item) => item.trim())
    .filter((item) => item.length > 0);
}

/**
 * Parses a JSON environment variable
 */
export function parseJson<T>(name: string, defaultValue?: T): T {
  const value = process.env[name];
  if (value === undefined || value === '') {
    if (defaultValue !== undefined) {
      return defaultValue;
    }
    throw new Error(`Missing required environment variable: ${name}`);
  }

  try {
    return JSON.parse(value) as T;
  } catch {
    throw new Error(`Environment variable ${name} must be valid JSON, got: ${value}`);
  }
}

/**
 * Parses a multi-line string from environment variable (converts \\n to newlines)
 */
export function parseMultiLine(name: string): string {
  const value = requireEnv(name);
  return value.replace(/\\n/g, '\n');
}

Version 2 (latest)

/**
 * Configuration parsing helpers for backend services
 * These helpers provide consistent parsing and validation of environment variables
 */

/**
 * Gets a required environment variable, throwing if not present
 */
export function requireEnv(name: string): string {
  const value = process.env[name];
  if (value === undefined || value === '') {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

/**
 * Gets an optional environment variable with a default value
 */
export function optionalEnv(name: string, defaultValue: string): string {
  const value = process.env[name];
  if (value === undefined || value === '') {
    return defaultValue;
  }
  return value;
}

/**
 * Parses an environment variable as a number
 */
export function parseNumber(name: string, defaultValue?: number): number {
  const value = process.env[name];
  if (value === undefined || value === '') {
    if (defaultValue !== undefined) {
      return defaultValue;
    }
    throw new Error(`Missing required environment variable: ${name}`);
  }

  const parsed = Number(value);
  if (isNaN(parsed)) {
    throw new Error(`Environment variable ${name} must be a number, got: ${value}`);
  }
  return parsed;
}

/**
 * Parses an environment variable as a boolean (ON/OFF or TRUE/FALSE)
 */
export function parseBoolean(name: string, defaultValue: boolean = false): boolean {
  const value = process.env[name];
  if (value === undefined || value === '') {
    return defaultValue;
  }

  const upper = value.toUpperCase();
  if (upper === 'ON' || upper === 'TRUE' || upper === '1') {
    return true;
  }
  if (upper === 'OFF' || upper === 'FALSE' || upper === '0') {
    return false;
  }

  throw new Error(`Environment variable ${name} must be ON/OFF or TRUE/FALSE, got: ${value}`);
}

/**
 * Parses a comma-separated environment variable into an array
 */
export function parseArray(name: string, defaultValue: string[] = []): string[] {
  const value = process.env[name];
  if (value === undefined || value === '') {
    return defaultValue;
  }

  return value
    .split(',')
    .map((item) => item.trim())
    .filter((item) => item.length > 0);
}

/**
 * Parses a JSON environment variable
 */
export function parseJson<T>(name: string, defaultValue?: T): T {
  const value = process.env[name];
  if (value === undefined || value === '') {
    if (defaultValue !== undefined) {
      return defaultValue;
    }
    throw new Error(`Missing required environment variable: ${name}`);
  }

  try {
    return JSON.parse(value) as T;
  } catch {
    throw new Error(`Environment variable ${name} must be valid JSON, got: ${value}`);
  }
}

/**
 * Parses a multi-line string from environment variable (converts \\n to newlines)
 */
export function parseMultiLine(name: string): string {
  const value = requireEnv(name);
  return value.replace(/\\n/g, '\n');
}

packages/cwc-backend-utils/src/index.ts

2 versions

Version 1

export * from './SqlClient';
export * from './Logger';
export * from './SqlClientKeysUtil';
export * from './backendUtils.types';
export * from './express';
export * from './loadDotEnv';

Version 2 (latest)

export * from './SqlClient';
export * from './Logger';
export * from './SqlClientKeysUtil';
export * from './backendUtils.types';
export * from './express';
export * from './loadDotEnv';
export * from './configHelpers';

packages/cwc-backend-utils/src/Logger/Logger.ts

import { CwcErrorLog } from 'cwc-types';
import { SqlClient } from '../SqlClient';
import {
  SqlClientMutationResponse,
  BackendUtilsConfig,
  ILogger,
  LogDebugOptions,
  LogErrorOptions,
  LogInformationOptions,
  BackendServiceName,
} from '../backendUtils.types';

const errorMessageMaxLength = 2000;
const errorStringMaxLength = 2000;
const stackStringMaxLength = 2000;
const dataStringMaxLength = 2000;
const requestStringMaxLength = 3000;

type InsertErrorLogOptions = {
  userPkId: number | undefined;
  values: Partial<CwcErrorLog>;
};

type WriteToLogFileOptions = {
  userPkId: number | undefined;
  errorType: 'error' | 'info' | 'debug';
  codeLocation: string;
  message?: string | object;
  error?: unknown | Error | string | object;
  value?: string | object | unknown;
  request?: string | unknown;
  projectPkId?: number | undefined;
};

type LoggerOptions = {
  config: BackendUtilsConfig;
  serviceName: BackendServiceName;
};

export class Logger implements ILogger {
  private config: BackendUtilsConfig;
  private serviceName: BackendServiceName;
  private sqlClient: SqlClient | undefined;

  constructor({ config, serviceName }: LoggerOptions) {
    this.config = config;
    this.serviceName = serviceName;
  }

  private getSqlClient() {
    if (!this.sqlClient) {
      this.sqlClient = new SqlClient({
        config: this.config,
        enableLogging: true,
        clientName: this.serviceName,
        logger: this,
      });
    }
  }

  private async insertErrorLog({
    userPkId,
    values,
  }: InsertErrorLogOptions): Promise<number | undefined> {
    if (this.sqlClient) {
      const command = this.sqlClient.insertCommand({ table: 'errorLog', values });
      const response: SqlClientMutationResponse | undefined = await this.sqlClient.mutate({
        userPkId,
        command,
      });
      const userAlertPkId = this.sqlClient.getInsertResultId(response);
      return userAlertPkId ?? undefined;
    }
    return;
  }

  private async writeToErrorLog({
    userPkId,
    errorType = 'error',
    codeLocation,
    message,
    error,
    value,
    request,
    projectPkId,
  }: WriteToLogFileOptions): Promise<number | undefined> {
    if (this.sqlClient) {
      try {
        let errorString = 'NULL';
        let stackString = 'NULL';
        let dataString = 'NULL';
        let requestString = 'NULL';
        let errorMessage = 'NULL';

        if (message) {
          if (typeof message === 'string') {
            errorMessage = message.slice(0, errorMessageMaxLength);
          } else {
            errorMessage = JSON.stringify(message).slice(0, errorMessageMaxLength);
          }
        }

        if (error) {
          if (typeof error === 'string') {
            errorString = error.slice(0, errorStringMaxLength);
          } else {
            const err = error as Error;
            if (err.message) {
              errorString = err.message.slice(0, errorStringMaxLength);
            }
            if (err.stack) {
              stackString = JSON.stringify(err.stack).slice(0, stackStringMaxLength);
            }
          }
        }

        if (value) {
          if (typeof value === 'string') {
            dataString = value.slice(0, dataStringMaxLength);
          } else {
            dataString = JSON.stringify(value).slice(0, dataStringMaxLength);
          }
        }

        if (request) {
          if (typeof request === 'string') {
            requestString = request.slice(0, requestStringMaxLength);
          } else {
            requestString = JSON.stringify(request).slice(0, requestStringMaxLength);
          }
        }

        const values: Partial<CwcErrorLog> = {
          serviceName: this.serviceName,
          dismissed: false,
          errorType: errorType || 'error',
          userPkId,
          projectPkId,
          codeLocation,
          errorMessage,
          error: errorString,
          stack: stackString,
          data: dataString,
          request: requestString,
        };

        const pkid: number | undefined = await this.insertErrorLog({ userPkId, values });
        return pkid;
      } catch (err) {
        console.log('logger.writeToErrorLog - ERROR', err);
      }
    }
    return;
  }

  public async logError({
    userPkId,
    codeLocation,
    message,
    error,
    value,
    request,
  }: LogErrorOptions): Promise<void> {
    if (this.config.debugMode) {
      console.log('logger.logError', {
        userPkId,
        codeLocation,
        message,
        error,
        value,
        request,
      });
    }

    if (this.config.logErrorsToDatabase) {
      this.getSqlClient();
      await this.writeToErrorLog({
        userPkId,
        errorType: 'error',
        codeLocation,
        message,
        error,
        value,
        request,
      });
    }
  }

  private stringifyValue(value: object | string | undefined) {
    if (value === undefined) {
      return;
    }
    if (typeof value === 'string') {
      return value;
    }
    let jsonValue: string = '';
    try {
      jsonValue = JSON.stringify(value);
      return jsonValue;
    } catch (err) {
      const error = err as Error;
      console.log('logInformation - ERROR', { error });
      jsonValue = 'ERROR PARSING THE VALUE PROVIDED TO LOG-INFORMATION';
    }
    return;
  }

  public logInformation({ userPkId, codeLocation, message, value }: LogInformationOptions): void {
    if (this.config.debugMode) {
      const jsonValue = this.stringifyValue(value);
      console.log('logger.logInformation', {
        userPkId,
        codeLocation,
        message,
        value: jsonValue,
      });
    }
  }

  public logDebug({ userPkId, codeLocation, message, value }: LogDebugOptions) {
    if (this.config.debugMode) {
      console.log('logger.logDebug', {
        userPkId,
        codeLocation,
        message,
        value,
      });
    }
  }
}

packages/cwc-storage/CLAUDE.md

4 versions

Version 1

cwc-storage Package

File storage service for CWC application. Provides abstracted file storage capabilities.

Purpose

Manage file uploads and storage
Provide consistent storage API regardless of backend provider
Handle file metadata and retrieval

Architecture

To be documented as implementation progresses

Patterns

To be documented as implementation progresses

Version 2

cwc-storage Package

File storage microservice for CWC application. Provides filesystem-based storage for user files organized by group.

Architecture

Standalone Microservice:

Does NOT use database (no SqlClient dependency)
Uses file-based Logger (writes to ./logs/{date}.log)
Authenticates via API key (x-api-key header)
Uses BackendUtilsConfigBasic (not full BackendUtilsConfig)

Storage Model:

Files organized by groupId directories
Path: {STORAGE_VOLUME_PATH}/{groupId}/{filename}
Validates filenames to prevent path traversal attacks

Configuration Pattern

Follows cwc-sql pattern:

Config in src/config/ folder with 3 files:
- config.types.ts - CwcStorageConfig type definition
- loadConfig.ts - Loads and validates from environment
- index.ts - Exports
Uses shared helpers from cwc-backend-utils:
- requireEnv(), optionalEnv(), parseNumber(), parseBoolean(), parseJson()
Adapter function converts to BackendUtilsConfigBasic for Express service

Required Environment Variables:

RUNTIME_ENVIRONMENT=dev  # dev | test | prod | unit | e2e
SERVICE_PORT=5004
CORS_ORIGIN=http://localhost:3000
STORAGE_API_KEY=your-secret-api-key
RATE_LIMITER_POINTS=15
RATE_LIMITER_DURATION=1
STORAGE_VOLUME_PATH=/path/to/storage
LOG_PATH=./logs
DEBUG_MODE=ON  # ON | OFF
DEV_MACHINES=[]  # JSON array
DEV_CORS_ORIGIN=

API Routes

All routes require x-api-key header and use POST method.

Route	Description	Payload
`/storage/v1/group-storage-get`	Retrieve file	`{ groupId, filename }`
`/storage/v1/group-storage-put`	Store file	`{ groupId, filename, dataUri }`
`/storage/v1/group-storage-delete`	Delete file	`{ groupId, filename }`

Security

API Key Authentication:

Uses constant-time comparison (crypto.timingSafeEqual) to prevent timing attacks
API key required in x-api-key header for all requests

HTTPS Enforcement:

Only required in production (isProduction: true)
Checks x-forwarded-proto header for proxy/load balancer scenarios

Filename Validation:

Rejects filenames with /, \, or ..
Prevents path traversal attacks

File-Based Logger

Different from cwc-backend-utils Logger:

Writes to filesystem ({logPath}/{YYYY-MM-DD}.log)
Does NOT write to database (cwc-storage has no DB access)
Supports ERROR, INFO, DEBUG levels
DEBUG only outputs when debugMode: true

Dependency Injection Pattern

Config passed to constructors (not imported globally):

// index.ts
const config = loadConfig();
const apis: ExpressApi[] = [new StorageApiV1(config)];

// StorageApiV1 passes config to handlers
const handlerFactories = {
  storage: () => new StorageHandler(handlerOptions, this.config),
};

// Routes receive config for storage functions
export const getRoutes = (config: CwcStorageConfig): StorageRouteConfigs => ({
  '/group-storage-get': {
    worker: createGetFromStorage(config),
    // ...
  },
});

Related Packages

Depends On:

cwc-backend-utils (workspace) - Express service factory, config helpers, loadDotEnv
cwc-types (workspace) - RuntimeEnvironment type
express - Web framework

Does NOT Depend On:

cwc-sql - No database access
SqlClient - No database queries

Version 3

cwc-storage Package

File storage microservice for CWC application. Provides filesystem-based storage for coding session data files organized by project.

Architecture

Standalone Microservice:

Does NOT use database (no SqlClient dependency)
Uses file-based Logger (writes to ./logs/{date}.log)
Authenticates via API key (x-api-key header)
Uses BackendUtilsConfigBasic (not full BackendUtilsConfig)

Storage Model:

Files organized by projectId directories
Path: {STORAGE_VOLUME_PATH}/{projectId}/{filename}
Validates filenames to prevent path traversal attacks

Directory Structure:

{STORAGE_VOLUME_PATH}/
├── {projectId}/                                           # Project natural key/slug
│   ├── 2025-11-19_17-16-35_abc123-def456.json.gz         # {timestamp}_{sessionId}.json.gz
│   ├── 2025-11-20_09-30-00_xyz789-uvw012.json.gz
│   └── ...
├── another-project/
│   └── ...

Configuration Pattern

Follows cwc-sql pattern:

Config in src/config/ folder with 3 files:
- config.types.ts - CwcStorageConfig type definition
- loadConfig.ts - Loads and validates from environment
- index.ts - Exports
Uses shared helpers from cwc-backend-utils:
- requireEnv(), optionalEnv(), parseNumber(), parseBoolean(), parseJson()
Adapter function converts to BackendUtilsConfigBasic for Express service

Required Environment Variables:

RUNTIME_ENVIRONMENT=dev  # dev | test | prod | unit | e2e
SERVICE_PORT=5004
CORS_ORIGIN=http://localhost:3000
STORAGE_API_KEY=your-secret-api-key
RATE_LIMITER_POINTS=15
RATE_LIMITER_DURATION=1
STORAGE_VOLUME_PATH=/path/to/storage
LOG_PATH=./logs
DEBUG_MODE=ON  # ON | OFF
DEV_MACHINES=[]  # JSON array
DEV_CORS_ORIGIN=

API Routes

All routes require x-api-key header and use POST method.

Route	Description	Payload
`/storage/v1/coding-session-data-get`	Retrieve session file	`{ projectId, filename }`
`/storage/v1/coding-session-data-put`	Store session file	`{ projectId, filename, dataUri }`
`/storage/v1/coding-session-data-delete`	Delete session file	`{ projectId, filename }`

Example Usage:

// PUT a session-data file
{
  projectId: "coding-with-claude",
  filename: "2025-11-19_17-16-35_abc123-def456.json.gz",
  dataUri: "<base64-encoded-gzipped-json>"
}

// GET a session-data file
{
  projectId: "coding-with-claude",
  filename: "2025-11-19_17-16-35_abc123-def456.json.gz"
}

Security

API Key Authentication:

Uses constant-time comparison (crypto.timingSafeEqual) to prevent timing attacks
API key required in x-api-key header for all requests

HTTPS Enforcement:

Only required in production (isProduction: true)
Checks x-forwarded-proto header for proxy/load balancer scenarios

Filename Validation:

Rejects filenames with /, \, or ..
Prevents path traversal attacks

File-Based Logger

Different from cwc-backend-utils Logger:

Writes to filesystem ({logPath}/{YYYY-MM-DD}.log)
Does NOT write to database (cwc-storage has no DB access)
Supports ERROR, INFO, DEBUG levels
DEBUG only outputs when debugMode: true

Dependency Injection Pattern

Config passed to constructors (not imported globally):

// index.ts
const config = loadConfig();
const apis: ExpressApi[] = [new StorageApiV1(config)];

// StorageApiV1 passes config to handlers
const handlerFactories = {
  storage: () => new StorageHandler(handlerOptions, this.config),
};

// Routes receive config for storage functions
export const getRoutes = (config: CwcStorageConfig): StorageRouteConfigs => ({
  '/coding-session-data-get': {
    worker: createGetFromStorage(config),
    // ...
  },
});

Related Packages

Depends On:

cwc-backend-utils (workspace) - Express service factory, config helpers, loadDotEnv
cwc-types (workspace) - RuntimeEnvironment type
express - Web framework

Does NOT Depend On:

cwc-sql - No database access
SqlClient - No database queries

Version 4 (latest)

cwc-storage Package

File storage microservice for CWC application. Provides filesystem-based storage for coding session data files organized by project.

Architecture

Standalone Microservice:

Does NOT use database (no SqlClient dependency)
Uses file-based Logger (writes to ./logs/{date}.log)
Authenticates via API key (x-api-key header)
Uses BackendUtilsConfigBasic (not full BackendUtilsConfig)

Storage Model:

Files organized by projectId directories
Path: {STORAGE_VOLUME_PATH}/{projectId}/{filename}
Validates filenames to prevent path traversal attacks

Directory Structure:

{STORAGE_VOLUME_PATH}/
├── {projectId}/                                           # Project natural key/slug
│   ├── 2025-11-19_17-16-35_abc123-def456.json.gz         # {timestamp}_{sessionId}.json.gz
│   ├── 2025-11-20_09-30-00_xyz789-uvw012.json.gz
│   └── ...
├── another-project/
│   └── ...

Configuration Pattern

Follows cwc-sql pattern:

Config in src/config/ folder with 3 files:
- config.types.ts - CwcStorageConfig type definition
- loadConfig.ts - Loads and validates from environment
- index.ts - Exports
Uses shared helpers from cwc-backend-utils:
- requireEnv(), optionalEnv(), parseNumber(), parseBoolean(), parseJson()
Adapter function converts to BackendUtilsConfigBasic for Express service

Required Environment Variables:

RUNTIME_ENVIRONMENT=dev  # dev | test | prod | unit | e2e
SERVICE_PORT=5004
CORS_ORIGIN=http://localhost:3000
STORAGE_API_KEY=your-secret-api-key
RATE_LIMITER_POINTS=15
RATE_LIMITER_DURATION=1
STORAGE_VOLUME_PATH=/path/to/storage
LOG_PATH=./logs
DEBUG_MODE=ON  # ON | OFF
DEV_MACHINES=[]  # JSON array
DEV_CORS_ORIGIN=

API Routes

All routes require x-api-key header and use POST method.

Route	Description	Payload
`/storage/v1/coding-session-data-get`	Retrieve session file	`{ projectId, filename }`
`/storage/v1/coding-session-data-put`	Store session file	`{ projectId, filename, dataUri }`
`/storage/v1/coding-session-data-delete`	Delete session file	`{ projectId, filename }`

Example Usage:

// PUT a session-data file
{
  projectId: "coding-with-claude",
  filename: "2025-11-19_17-16-35_abc123-def456.json.gz",
  dataUri: "<base64-encoded-gzipped-json>"
}

// GET a session-data file
{
  projectId: "coding-with-claude",
  filename: "2025-11-19_17-16-35_abc123-def456.json.gz"
}

Security

API Key Authentication:

Uses constant-time comparison (crypto.timingSafeEqual) to prevent timing attacks
API key required in x-api-key header for all requests

HTTPS Enforcement:

Only required in production (isProduction: true)
Checks x-forwarded-proto header for proxy/load balancer scenarios

Filename Validation:

Rejects filenames with /, \, or ..
Prevents path traversal attacks

File-Based Logger

Different from cwc-backend-utils Logger:

Writes to filesystem ({logPath}/{YYYY-MM-DD}.log)
Does NOT write to database (cwc-storage has no DB access)
Supports ERROR, INFO, DEBUG levels
DEBUG only outputs when debugMode: true

Dependency Injection Pattern

Config passed to constructors (not imported globally):

// index.ts
const config = loadConfig();
const apis: ExpressApi[] = [new StorageApiV1(config)];

// StorageApiV1 passes config to handlers
const handlerFactories = {
  storage: () => new StorageHandler(handlerOptions, this.config),
};

// Routes receive config for storage functions
export const getRoutes = (config: CwcStorageConfig): StorageRouteConfigs => ({
  '/coding-session-data-get': {
    worker: createGetFromStorage(config),
    // ...
  },
});

Related Packages

Depends On:

cwc-backend-utils (workspace) - Express service factory, config helpers, loadDotEnv
cwc-types (workspace) - RuntimeEnvironment type
express - Web framework

Does NOT Depend On:

cwc-sql - No database access
SqlClient - No database queries

packages/cwc-storage/package.json

3 versions

Version 1

{
  "name": "cwc-storage",
  "version": "1.0.0",
  "description": "File storage service 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", "storage", "file-storage"],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

Version 2

{
  "name": "cwc-storage",
  "version": "1.0.0",
  "description": "File storage service 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", "storage", "file-storage"],
  "author": "",
  "license": "UNLICENSED",
  "dependencies": {
    "cwc-backend-utils": "workspace:*",
    "cwc-types": "workspace:*",
    "express": "^4.21.0"
  },
  "devDependencies": {
    "@types/express": "^5.0.0",
    "@types/node": "^22.0.0",
    "typescript": "^5.4.0"
  }
}

Version 3 (latest)

{
  "name": "cwc-storage",
  "version": "1.0.0",
  "description": "File storage service 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", "storage", "file-storage"],
  "author": "",
  "license": "UNLICENSED",
  "dependencies": {
    "cwc-backend-utils": "workspace:*",
    "cwc-types": "workspace:*",
    "express": "^4.21.0"
  },
  "devDependencies": {
    "@types/express": "^5.0.0",
    "@types/node": "^22.0.0",
    "typescript": "^5.4.0"
  }
}

packages/cwc-storage/src/apis/StorageApiV1/index.ts

2 versions

Version 1

import crypto from 'crypto';
import { NextFunction, Request, Response } from 'express';
import { RequestPayload, StorageApi } from '../../types';
import { getRoutes } from './routes';
import {
  StorageApiResponseData,
  StorageHandlerResponse,
  StorageRouteConfig,
  StorageRouteConfigs,
  StorageRouteHandler,
  StorageRouteHandlerOptions,
} from './types';
import { StorageHandler } from './StorageHandler';
import { Logger } from '../../Logger';
import { config } from '../../configuration';

const codeLocation = 'src/apis/StorageApiV1/index.ts';

export class StorageApiV1 implements StorageApi {
  private routes: StorageRouteConfigs;
  private logger: Logger;
  private apiKey: string | undefined;

  constructor() {
    this.logger = new Logger({
      logPath: config.logPath,
      serviceName: 'cwc-storage',
      debugMode: config.debugMode,
    });
    this.routes = getRoutes();
    // API key should be configured via environment variable
    this.apiKey = config.secrets?.storageApiKey;
  }

  public get path() {
    return '/storage/v1';
  }
  public get version() {
    return 1;
  }

  private validateApiKey(req: Request): boolean {
    // Check for API key in x-api-key header
    const requestApiKey = req.headers['x-api-key'];

    if (!requestApiKey || typeof requestApiKey !== 'string') {
      return false;
    }

    if (!this.apiKey) {
      this.logger.logError({
        username: undefined,
        codeLocation,
        message: 'API key not configured in secrets',
        error: 'storageApiKey is undefined',
        value: undefined,
        request: undefined,
      });
      return false;
    }

    // Use constant-time comparison to prevent timing attacks
    try {
      const requestBuffer = Buffer.from(requestApiKey);
      const apiKeyBuffer = Buffer.from(this.apiKey);

      // timingSafeEqual requires equal-length buffers
      if (requestBuffer.length !== apiKeyBuffer.length) {
        return false;
      }

      return crypto.timingSafeEqual(requestBuffer, apiKeyBuffer);
    } catch (error) {
      this.logger.logError({
        username: undefined,
        codeLocation,
        message: 'API key comparison failed',
        error,
        value: undefined,
        request: undefined,
      });
      return false;
    }
  }

  private isHttpsRequired(): boolean {
    // Only require HTTPS in "prod" environment
    return config.isProduction;
  }

  private validateHttps(req: Request): boolean {
    // Check if HTTPS is required
    if (!this.isHttpsRequired()) {
      return true; // Allow HTTP in development/test
    }

    // Check protocol from request
    const protocol = req.protocol;
    const isSecure = req.secure || protocol === 'https';

    // Also check x-forwarded-proto header (for proxies/load balancers)
    const forwardedProto = req.headers['x-forwarded-proto'];
    const isForwardedSecure = forwardedProto === 'https';

    return isSecure || isForwardedSecure;
  }

  public async handler(req: Request, res: Response, next: NextFunction) {
    const logError = (message: string, error: unknown, value: unknown = undefined) => {
      this.logger.logError({
        username: undefined,
        request: undefined,
        codeLocation,
        message,
        value,
        error,
      });
    };

    try {
      if (res.statusCode !== 200) {
        return;
      }
      if (res.writableEnded) {
        return;
      }

      const { body, path, query, method } = req;

      // Enforce HTTPS in "prod"
      if (!this.validateHttps(req)) {
        logError('HTTPS required', 'Non-HTTPS request in "prod" environment');
        return res.status(403).send('HTTPS required');
      }

      // Validate API key for all requests
      if (!this.validateApiKey(req)) {
        return res.status(401).send('unauthorized');
      }

      // Validate the path
      if (!this.isPathValid(path)) {
        return res.status(404).send('not found');
      }

      // Locate the corresponding route config object
      const routeConfig: StorageRouteConfig = this.routes[path];
      if (!routeConfig) {
        logError('handler', 'ROUTE CONFIG NOT FOUND', { path });
        next();
        return;
      }

      if (method !== routeConfig.method) {
        logError('handler', 'ROUTE NOT FOUND', { path });
        return res.status(404).send('invalid route');
      }

      // Build payload from body and query params
      let payload: RequestPayload = body ?? {};
      if (routeConfig.params?.length && query) {
        for (let i = 0; i < routeConfig.params.length; i++) {
          const key = routeConfig.params[i];
          payload[key] = query[key.toLowerCase()];
        }
      }

      // Instantiate the route handler
      const handlerOptions: StorageRouteHandlerOptions = {
        payload,
        routeConfig,
      };

      const handlerFactories = {
        storage: () => new StorageHandler(handlerOptions),
      };
      type FactoryFunction = () => StorageRouteHandler;
      const factory: FactoryFunction = handlerFactories[routeConfig.handlerType];

      if (!factory) {
        logError('handler', 'HANDLER FACTORY NOT FOUND', { path });
        return res.status(404).send('invalid route');
      }

      const routeHandler: StorageRouteHandler = factory();
      if (!routeHandler) {
        logError('handler', 'HANDLER FACTORY FAILED', { path });
        return res.status(404).send('invalid route');
      }

      // Invoke the route handler
      const handlerResponse: StorageHandlerResponse = await routeHandler.processRequest();

      const statusCode = handlerResponse.statusCode;
      const data: StorageApiResponseData = {
        success: false,
        data: undefined,
      };

      const success = statusCode === 200 && handlerResponse?.success === true;
      if (success === true) {
        data.success = true;
        data.data = handlerResponse.data;
      }

      if (routeConfig.cacheControl) {
        res.header('Cache-Control', routeConfig.cacheControl);
      }

      return res.status(statusCode).json(data);
    } catch (error) {
      logError('StorageApiV1.handler - ERROR', error);
      return res.status(404).send('request failed');
    }
  }

  private isPathValid(path: string): boolean {
    if (!path || path === '/') {
      return false;
    }
    return true;
  }
}

Version 2 (latest)

import crypto from 'crypto';
import { NextFunction, Request, Response } from 'express';
import { RequestPayload, StorageApi } from '../../types';
import { getRoutes } from './routes';
import {
  StorageApiResponseData,
  StorageHandlerResponse,
  StorageRouteConfigs,
  StorageRouteHandler,
  StorageRouteHandlerOptions,
} from './types';
import { StorageHandler } from './StorageHandler';
import { Logger } from '../../Logger';
import type { CwcStorageConfig } from '../../config';

const codeLocation = 'src/apis/StorageApiV1/index.ts';

export class StorageApiV1 implements StorageApi {
  private routes: StorageRouteConfigs;
  private logger: Logger;
  private apiKey: string;
  private config: CwcStorageConfig;

  constructor(config: CwcStorageConfig) {
    this.config = config;
    this.logger = new Logger({
      logPath: config.logPath,
      serviceName: 'cwc-storage',
      debugMode: config.debugMode,
    });
    this.routes = getRoutes(config);
    this.apiKey = config.storageApiKey;
  }

  public get path(): string {
    return '/storage/v1';
  }

  public get version(): number {
    return 1;
  }

  private validateApiKey(req: Request): boolean {
    // Check for API key in x-api-key header
    const requestApiKey = req.headers['x-api-key'];

    if (!requestApiKey || typeof requestApiKey !== 'string') {
      return false;
    }

    if (!this.apiKey) {
      this.logger.logError({
        username: undefined,
        codeLocation,
        message: 'API key not configured',
        error: 'storageApiKey is undefined',
        value: undefined,
        request: undefined,
      });
      return false;
    }

    // Use constant-time comparison to prevent timing attacks
    try {
      const requestBuffer = Buffer.from(requestApiKey);
      const apiKeyBuffer = Buffer.from(this.apiKey);

      // timingSafeEqual requires equal-length buffers
      if (requestBuffer.length !== apiKeyBuffer.length) {
        return false;
      }

      return crypto.timingSafeEqual(requestBuffer, apiKeyBuffer);
    } catch (error) {
      this.logger.logError({
        username: undefined,
        codeLocation,
        message: 'API key comparison failed',
        error,
        value: undefined,
        request: undefined,
      });
      return false;
    }
  }

  private isHttpsRequired(): boolean {
    // Only require HTTPS in "prod" environment
    return this.config.isProduction;
  }

  private validateHttps(req: Request): boolean {
    // Check if HTTPS is required
    if (!this.isHttpsRequired()) {
      return true; // Allow HTTP in development/test
    }

    // Check protocol from request
    const protocol = req.protocol;
    const isSecure = req.secure || protocol === 'https';

    // Also check x-forwarded-proto header (for proxies/load balancers)
    const forwardedProto = req.headers['x-forwarded-proto'];
    const isForwardedSecure = forwardedProto === 'https';

    return isSecure || isForwardedSecure;
  }

  public async handler(req: Request, res: Response, next: NextFunction): Promise<void> {
    const logError = (message: string, error: unknown, value: unknown = undefined): void => {
      this.logger.logError({
        username: undefined,
        request: undefined,
        codeLocation,
        message,
        value,
        error,
      });
    };

    try {
      if (res.statusCode !== 200) {
        return;
      }
      if (res.writableEnded) {
        return;
      }

      const { body, path, query, method } = req;

      // Enforce HTTPS in "prod"
      if (!this.validateHttps(req)) {
        logError('HTTPS required', 'Non-HTTPS request in "prod" environment');
        res.status(403).send('HTTPS required');
        return;
      }

      // Validate API key for all requests
      if (!this.validateApiKey(req)) {
        res.status(401).send('unauthorized');
        return;
      }

      // Validate the path
      if (!this.isPathValid(path)) {
        res.status(404).send('not found');
        return;
      }

      // Locate the corresponding route config object
      const routeConfig = this.routes[path];
      if (!routeConfig) {
        logError('handler', 'ROUTE CONFIG NOT FOUND', { path });
        next();
        return;
      }

      if (method !== routeConfig.method) {
        logError('handler', 'ROUTE NOT FOUND', { path });
        res.status(404).send('invalid route');
        return;
      }

      // Build payload from body and query params
      const payload: RequestPayload = body ?? {};
      if (routeConfig.params && routeConfig.params.length > 0 && query) {
        for (let i = 0; i < routeConfig.params.length; i++) {
          const key = routeConfig.params[i];
          if (key) {
            payload[key] = query[key.toLowerCase()];
          }
        }
      }

      // Instantiate the route handler
      const handlerOptions: StorageRouteHandlerOptions = {
        payload,
        routeConfig,
      };

      const handlerFactories = {
        storage: () => new StorageHandler(handlerOptions, this.config),
      };
      type FactoryFunction = () => StorageRouteHandler;
      const factory: FactoryFunction = handlerFactories[routeConfig.handlerType];

      if (!factory) {
        logError('handler', 'HANDLER FACTORY NOT FOUND', { path });
        res.status(404).send('invalid route');
        return;
      }

      const routeHandler: StorageRouteHandler = factory();
      if (!routeHandler) {
        logError('handler', 'HANDLER FACTORY FAILED', { path });
        res.status(404).send('invalid route');
        return;
      }

      // Invoke the route handler
      const handlerResponse: StorageHandlerResponse = await routeHandler.processRequest();

      const statusCode = handlerResponse.statusCode;
      const data: StorageApiResponseData = {
        success: false,
        data: undefined,
      };

      const success = statusCode === 200 && handlerResponse?.success === true;
      if (success === true) {
        data.success = true;
        data.data = handlerResponse.data;
      }

      if (routeConfig.cacheControl) {
        res.header('Cache-Control', routeConfig.cacheControl);
      }

      res.status(statusCode).json(data);
    } catch (error) {
      logError('StorageApiV1.handler - ERROR', error);
      res.status(404).send('request failed');
    }
  }

  private isPathValid(path: string): boolean {
    if (!path || path === '/') {
      return false;
    }
    return true;
  }
}

packages/cwc-storage/src/apis/StorageApiV1/routes.ts

3 versions

Version 1

'use strict';

import { deleteFromStorage } from './storageFunctions/deleteFromStorage';
import { getFromStorage } from './storageFunctions/getFromStorage';
import { putInStorage } from './storageFunctions/putInStorage';
import { StorageRouteConfigs } from './types';

export const getRoutes = (): StorageRouteConfigs => ({
  // ****************************************************************
  // group-storage routes
  // ****************************************************************
  '/group-storage-get': {
    handlerType: 'storage',
    path: '/group-storage-get',
    worker: getFromStorage,
    method: 'POST',
    params: undefined,
    cacheControl: 'public, no-transform',
  },
  '/group-storage-put': {
    handlerType: 'storage',
    path: '/group-storage-put',
    worker: putInStorage,
    method: 'POST',
    params: undefined,
    cacheControl: undefined,
  },
  '/group-storage-delete': {
    handlerType: 'storage',
    path: '/group-storage-delete',
    worker: deleteFromStorage,
    method: 'POST',
    params: undefined,
    cacheControl: undefined,
  },
});

Version 2

'use strict';

import { createDeleteFromStorage } from './storageFunctions/deleteFromStorage';
import { createGetFromStorage } from './storageFunctions/getFromStorage';
import { createPutInStorage } from './storageFunctions/putInStorage';
import { StorageRouteConfigs } from './types';
import type { CwcStorageConfig } from '../../config';

export const getRoutes = (config: CwcStorageConfig): StorageRouteConfigs => ({
  // ****************************************************************
  // group-storage routes
  // ****************************************************************
  '/group-storage-get': {
    handlerType: 'storage',
    path: '/group-storage-get',
    worker: createGetFromStorage(config),
    method: 'POST',
    params: undefined,
    cacheControl: 'public, no-transform',
  },
  '/group-storage-put': {
    handlerType: 'storage',
    path: '/group-storage-put',
    worker: createPutInStorage(config),
    method: 'POST',
    params: undefined,
    cacheControl: undefined,
  },
  '/group-storage-delete': {
    handlerType: 'storage',
    path: '/group-storage-delete',
    worker: createDeleteFromStorage(config),
    method: 'POST',
    params: undefined,
    cacheControl: undefined,
  },
});

Version 3 (latest)

'use strict';

import { createDeleteFromStorage } from './storageFunctions/deleteFromStorage';
import { createGetFromStorage } from './storageFunctions/getFromStorage';
import { createPutInStorage } from './storageFunctions/putInStorage';
import { StorageRouteConfigs } from './types';
import type { CwcStorageConfig } from '../../config';

export const getRoutes = (config: CwcStorageConfig): StorageRouteConfigs => ({
  // ****************************************************************
  // coding-session-data storage routes
  // ****************************************************************
  '/coding-session-data-get': {
    handlerType: 'storage',
    path: '/coding-session-data-get',
    worker: createGetFromStorage(config),
    method: 'POST',
    params: undefined,
    cacheControl: 'public, no-transform',
  },
  '/coding-session-data-put': {
    handlerType: 'storage',
    path: '/coding-session-data-put',
    worker: createPutInStorage(config),
    method: 'POST',
    params: undefined,
    cacheControl: undefined,
  },
  '/coding-session-data-delete': {
    handlerType: 'storage',
    path: '/coding-session-data-delete',
    worker: createDeleteFromStorage(config),
    method: 'POST',
    params: undefined,
    cacheControl: undefined,
  },
});

packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/deleteFromStorage.ts

3 versions

Version 1

import fs from 'fs/promises';
import { StorageFunctionOptions, StorageFunctionResult } from '../types';
import { config } from '../../../configuration';
import { getStorageFilePath, isValidFilename } from '../utils';

// Payload type for this storage function
type Payload = {
  groupId: string;
  filename: string;
};

/**
 * Deletes a file from the filesystem storage
 * @param groupId - Group identifier
 * @param filename - Name of the file to delete
 * @returns true if successful
 */
const deleteFromFilesystem = async (groupId: string, filename: string): Promise<boolean> => {
  const filePath = getStorageFilePath(config.storageVolumePath, groupId, filename);

  try {
    await fs.unlink(filePath);
    return true;
  } catch (error) {
    // If file doesn't exist, consider it a success (idempotent delete)
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
      return true;
    }
    // Other errors should be thrown
    throw error;
  }
};

/**
 * Storage function to delete a file from filesystem storage
 */
export const deleteFromStorage = async ({
  payload,
}: StorageFunctionOptions): Promise<StorageFunctionResult<string>> => {
  const { groupId, filename } = payload as Payload;

  // Validate groupId
  if (!groupId) {
    return {
      success: false,
      error: 'groupId is undefined',
      data: undefined,
    };
  }

  // Validate filename
  if (!filename) {
    return {
      success: false,
      error: 'filename is undefined',
      data: undefined,
    };
  }

  // Validate filename safety
  if (!isValidFilename(filename)) {
    return {
      success: false,
      error: 'invalid filename',
      data: undefined,
    };
  }

  try {
    // Delete the file from filesystem
    await deleteFromFilesystem(groupId, filename);

    return {
      success: true,
      error: undefined,
      data: filename, // return the filename when successful
    };
  } catch (error) {
    return {
      success: false,
      error: 'deleteFromStorage failed',
      data: undefined,
    };
  }
};

Version 2

import fs from 'fs/promises';
import { StorageFunction, StorageFunctionOptions, StorageFunctionResult } from '../types';
import { getStorageFilePath, isValidFilename } from '../utils';
import type { CwcStorageConfig } from '../../../config';

// Payload type for this storage function
type Payload = {
  groupId: string;
  filename: string;
};

/**
 * Deletes a file from the filesystem storage
 * @param storageVolumePath - Base path to storage volume
 * @param groupId - Group identifier
 * @param filename - Name of the file to delete
 * @returns true if successful
 */
const deleteFromFilesystem = async (
  storageVolumePath: string,
  groupId: string,
  filename: string
): Promise<boolean> => {
  const filePath = getStorageFilePath(storageVolumePath, groupId, filename);

  try {
    await fs.unlink(filePath);
    return true;
  } catch (error) {
    // If file doesn't exist, consider it a success (idempotent delete)
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
      return true;
    }
    // Other errors should be thrown
    throw error;
  }
};

/**
 * Creates a storage function to delete a file from filesystem storage
 */
export const createDeleteFromStorage = (config: CwcStorageConfig): StorageFunction<string> => {
  return async ({ payload }: StorageFunctionOptions): Promise<StorageFunctionResult<string>> => {
    const { groupId, filename } = payload as Payload;

    // Validate groupId
    if (!groupId) {
      return {
        success: false,
        error: 'groupId is undefined',
        data: undefined,
      };
    }

    // Validate filename
    if (!filename) {
      return {
        success: false,
        error: 'filename is undefined',
        data: undefined,
      };
    }

    // Validate filename safety
    if (!isValidFilename(filename)) {
      return {
        success: false,
        error: 'invalid filename',
        data: undefined,
      };
    }

    try {
      // Delete the file from filesystem
      await deleteFromFilesystem(config.storageVolumePath, groupId, filename);

      return {
        success: true,
        error: undefined,
        data: filename, // return the filename when successful
      };
    } catch {
      return {
        success: false,
        error: 'deleteFromStorage failed',
        data: undefined,
      };
    }
  };
};

Version 3 (latest)

import fs from 'fs/promises';
import { StorageFunction, StorageFunctionOptions, StorageFunctionResult } from '../types';
import { getStorageFilePath, isValidFilename } from '../utils';
import type { CwcStorageConfig } from '../../../config';

// Payload type for this storage function
type Payload = {
  projectId: string;
  filename: string;
};

/**
 * Deletes a file from the filesystem storage
 * @param storageVolumePath - Base path to storage volume
 * @param projectId - Project identifier
 * @param filename - Name of the file to delete
 * @returns true if successful
 */
const deleteFromFilesystem = async (
  storageVolumePath: string,
  projectId: string,
  filename: string
): Promise<boolean> => {
  const filePath = getStorageFilePath(storageVolumePath, projectId, filename);

  try {
    await fs.unlink(filePath);
    return true;
  } catch (error) {
    // If file doesn't exist, consider it a success (idempotent delete)
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
      return true;
    }
    // Other errors should be thrown
    throw error;
  }
};

/**
 * Creates a storage function to delete a file from filesystem storage
 */
export const createDeleteFromStorage = (config: CwcStorageConfig): StorageFunction<string> => {
  return async ({ payload }: StorageFunctionOptions): Promise<StorageFunctionResult<string>> => {
    const { projectId, filename } = payload as Payload;

    // Validate projectId
    if (!projectId) {
      return {
        success: false,
        error: 'projectId is undefined',
        data: undefined,
      };
    }

    // Validate filename
    if (!filename) {
      return {
        success: false,
        error: 'filename is undefined',
        data: undefined,
      };
    }

    // Validate filename safety
    if (!isValidFilename(filename)) {
      return {
        success: false,
        error: 'invalid filename',
        data: undefined,
      };
    }

    try {
      // Delete the file from filesystem
      await deleteFromFilesystem(config.storageVolumePath, projectId, filename);

      return {
        success: true,
        error: undefined,
        data: filename, // return the filename when successful
      };
    } catch {
      return {
        success: false,
        error: 'deleteFromStorage failed',
        data: undefined,
      };
    }
  };
};

packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/getFromStorage.ts

3 versions

Version 1

import fs from 'fs/promises';
import { StorageFunction, StorageFunctionOptions, StorageFunctionResult } from '../types';
import { config } from '../../../configuration';
import { getStorageFilePath, isValidFilename } from '../utils';

// Payload type for this storage function
type Payload = {
  groupId: string;
  filename: string;
};

/**
 * Fetches a file from the filesystem storage
 * @param groupId - Group identifier
 * @param filename - Name of the file to fetch
 * @returns Buffer containing file contents or undefined if not found
 */
const fetchFromFilesystem = async (
  groupId: string,
  filename: string
): Promise<StorageFunctionResult<Buffer>> => {
  const filePath = getStorageFilePath(config.storageVolumePath, groupId, filename);
  try {
    const data = await fs.readFile(filePath);

    return {
      success: true,
      error: undefined,
      data,
    };
  } catch (error) {
    // File not found or other read error
    const errorMessage =
      (error as NodeJS.ErrnoException).code === 'ENOENT'
        ? `file not found. ${filePath}`
        : `failed to read file. ${filePath}`;

    return {
      success: false,
      error: errorMessage,
      data: undefined,
    };
  }
};

/**
 * Storage function to retrieve a file from filesystem storage
 */
export const getFromStorage: StorageFunction<Buffer> = async ({
  payload,
}: StorageFunctionOptions): Promise<StorageFunctionResult<Buffer>> => {
  const { groupId, filename } = payload as Payload;

  // Validate groupId
  if (!groupId) {
    return {
      success: false,
      error: 'groupId is undefined',
      data: undefined,
    };
  }

  // Validate filename
  if (!filename) {
    return {
      success: false,
      error: 'filename is undefined',
      data: undefined,
    };
  }

  // Validate filename safety
  if (!isValidFilename(filename)) {
    return {
      success: false,
      error: 'invalid filename',
      data: undefined,
    };
  }

  // Fetch the file from filesystem
  const fetchResult = await fetchFromFilesystem(groupId, filename);

  if (!fetchResult.success) {
    return {
      success: false,
      error: fetchResult.error || 'fetch failed',
      data: undefined,
    };
  }

  return {
    success: true,
    error: undefined,
    data: fetchResult.data,
  };
};

Version 2

import fs from 'fs/promises';
import { StorageFunction, StorageFunctionOptions, StorageFunctionResult } from '../types';
import { getStorageFilePath, isValidFilename } from '../utils';
import type { CwcStorageConfig } from '../../../config';

// Payload type for this storage function
type Payload = {
  groupId: string;
  filename: string;
};

/**
 * Fetches a file from the filesystem storage
 * @param storageVolumePath - Base path to storage volume
 * @param groupId - Group identifier
 * @param filename - Name of the file to fetch
 * @returns Buffer containing file contents or undefined if not found
 */
const fetchFromFilesystem = async (
  storageVolumePath: string,
  groupId: string,
  filename: string
): Promise<StorageFunctionResult<Buffer>> => {
  const filePath = getStorageFilePath(storageVolumePath, groupId, filename);
  try {
    const data = await fs.readFile(filePath);

    return {
      success: true,
      error: undefined,
      data,
    };
  } catch (error) {
    // File not found or other read error
    const errorMessage =
      (error as NodeJS.ErrnoException).code === 'ENOENT'
        ? `file not found. ${filePath}`
        : `failed to read file. ${filePath}`;

    return {
      success: false,
      error: errorMessage,
      data: undefined,
    };
  }
};

/**
 * Creates a storage function to retrieve a file from filesystem storage
 */
export const createGetFromStorage = (config: CwcStorageConfig): StorageFunction<Buffer> => {
  return async ({ payload }: StorageFunctionOptions): Promise<StorageFunctionResult<Buffer>> => {
    const { groupId, filename } = payload as Payload;

    // Validate groupId
    if (!groupId) {
      return {
        success: false,
        error: 'groupId is undefined',
        data: undefined,
      };
    }

    // Validate filename
    if (!filename) {
      return {
        success: false,
        error: 'filename is undefined',
        data: undefined,
      };
    }

    // Validate filename safety
    if (!isValidFilename(filename)) {
      return {
        success: false,
        error: 'invalid filename',
        data: undefined,
      };
    }

    // Fetch the file from filesystem
    const fetchResult = await fetchFromFilesystem(config.storageVolumePath, groupId, filename);

    if (!fetchResult.success) {
      return {
        success: false,
        error: fetchResult.error || 'fetch failed',
        data: undefined,
      };
    }

    return {
      success: true,
      error: undefined,
      data: fetchResult.data,
    };
  };
};

Version 3 (latest)

import fs from 'fs/promises';
import { StorageFunction, StorageFunctionOptions, StorageFunctionResult } from '../types';
import { getStorageFilePath, isValidFilename } from '../utils';
import type { CwcStorageConfig } from '../../../config';

// Payload type for this storage function
type Payload = {
  projectId: string;
  filename: string;
};

/**
 * Fetches a file from the filesystem storage
 * @param storageVolumePath - Base path to storage volume
 * @param projectId - Project identifier
 * @param filename - Name of the file to fetch
 * @returns Buffer containing file contents or undefined if not found
 */
const fetchFromFilesystem = async (
  storageVolumePath: string,
  projectId: string,
  filename: string
): Promise<StorageFunctionResult<Buffer>> => {
  const filePath = getStorageFilePath(storageVolumePath, projectId, filename);
  try {
    const data = await fs.readFile(filePath);

    return {
      success: true,
      error: undefined,
      data,
    };
  } catch (error) {
    // File not found or other read error
    const errorMessage =
      (error as NodeJS.ErrnoException).code === 'ENOENT'
        ? `file not found. ${filePath}`
        : `failed to read file. ${filePath}`;

    return {
      success: false,
      error: errorMessage,
      data: undefined,
    };
  }
};

/**
 * Creates a storage function to retrieve a file from filesystem storage
 */
export const createGetFromStorage = (config: CwcStorageConfig): StorageFunction<Buffer> => {
  return async ({ payload }: StorageFunctionOptions): Promise<StorageFunctionResult<Buffer>> => {
    const { projectId, filename } = payload as Payload;

    // Validate projectId
    if (!projectId) {
      return {
        success: false,
        error: 'projectId is undefined',
        data: undefined,
      };
    }

    // Validate filename
    if (!filename) {
      return {
        success: false,
        error: 'filename is undefined',
        data: undefined,
      };
    }

    // Validate filename safety
    if (!isValidFilename(filename)) {
      return {
        success: false,
        error: 'invalid filename',
        data: undefined,
      };
    }

    // Fetch the file from filesystem
    const fetchResult = await fetchFromFilesystem(config.storageVolumePath, projectId, filename);

    if (!fetchResult.success) {
      return {
        success: false,
        error: fetchResult.error || 'fetch failed',
        data: undefined,
      };
    }

    return {
      success: true,
      error: undefined,
      data: fetchResult.data,
    };
  };
};

packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/putInStorage.ts

3 versions

Version 1

import fs from 'fs/promises';
import path from 'path';
import { StorageFunctionOptions, StorageFunctionResult } from '../types';
import { config } from '../../../configuration';
import { getStorageFilePath, ensureDirectoryExists, isValidFilename } from '../utils';

// Payload type for this storage function
type Payload = {
  groupId: string;
  filename: string;
  dataUri: string;
};

/**
 * Writes a file to the filesystem storage
 * @param groupId - Group identifier
 * @param filename - Name of the file to save
 * @param dataUri - File data as string (will be converted to Buffer)
 * @returns true if successful
 */
const writeToFilesystem = async (
  groupId: string,
  filename: string,
  dataUri: string
): Promise<boolean> => {
  const filePath = getStorageFilePath(config.storageVolumePath, groupId, filename);
  const dirPath = path.dirname(filePath);

  // Ensure the group directory exists
  await ensureDirectoryExists(dirPath);

  // Convert dataUri to Buffer and write to file
  const data = Buffer.from(dataUri);
  await fs.writeFile(filePath, data);

  return true;
};

/**
 * Storage function to save a file to filesystem storage
 */
export const putInStorage = async ({
  payload,
}: StorageFunctionOptions): Promise<StorageFunctionResult<string>> => {
  const { groupId, filename, dataUri } = payload as Payload;

  // Validate groupId
  if (!groupId) {
    return {
      success: false,
      error: 'groupId is undefined',
      data: undefined,
    };
  }

  // Validate filename
  if (!filename) {
    return {
      success: false,
      error: 'filename is undefined',
      data: undefined,
    };
  }

  // Validate filename safety
  if (!isValidFilename(filename)) {
    return {
      success: false,
      error: 'invalid filename',
      data: undefined,
    };
  }

  // Validate dataUri
  if (!dataUri) {
    return {
      success: false,
      error: 'dataUri is undefined',
      data: undefined,
    };
  }

  try {
    // Write the file to filesystem
    await writeToFilesystem(groupId, filename, dataUri);

    return {
      success: true,
      error: undefined,
      data: filename, // return the filename when successful
    };
  } catch (error) {
    return {
      success: false,
      error: 'putInStorage failed',
      data: undefined,
    };
  }
};

Version 2

import fs from 'fs/promises';
import path from 'path';
import { StorageFunction, StorageFunctionOptions, StorageFunctionResult } from '../types';
import { getStorageFilePath, ensureDirectoryExists, isValidFilename } from '../utils';
import type { CwcStorageConfig } from '../../../config';

// Payload type for this storage function
type Payload = {
  groupId: string;
  filename: string;
  dataUri: string;
};

/**
 * Writes a file to the filesystem storage
 * @param storageVolumePath - Base path to storage volume
 * @param groupId - Group identifier
 * @param filename - Name of the file to save
 * @param dataUri - File data as string (will be converted to Buffer)
 * @returns true if successful
 */
const writeToFilesystem = async (
  storageVolumePath: string,
  groupId: string,
  filename: string,
  dataUri: string
): Promise<boolean> => {
  const filePath = getStorageFilePath(storageVolumePath, groupId, filename);
  const dirPath = path.dirname(filePath);

  // Ensure the group directory exists
  await ensureDirectoryExists(dirPath);

  // Convert dataUri to Buffer and write to file
  const data = Buffer.from(dataUri);
  await fs.writeFile(filePath, data);

  return true;
};

/**
 * Creates a storage function to save a file to filesystem storage
 */
export const createPutInStorage = (config: CwcStorageConfig): StorageFunction<string> => {
  return async ({ payload }: StorageFunctionOptions): Promise<StorageFunctionResult<string>> => {
    const { groupId, filename, dataUri } = payload as Payload;

    // Validate groupId
    if (!groupId) {
      return {
        success: false,
        error: 'groupId is undefined',
        data: undefined,
      };
    }

    // Validate filename
    if (!filename) {
      return {
        success: false,
        error: 'filename is undefined',
        data: undefined,
      };
    }

    // Validate filename safety
    if (!isValidFilename(filename)) {
      return {
        success: false,
        error: 'invalid filename',
        data: undefined,
      };
    }

    // Validate dataUri
    if (!dataUri) {
      return {
        success: false,
        error: 'dataUri is undefined',
        data: undefined,
      };
    }

    try {
      // Write the file to filesystem
      await writeToFilesystem(config.storageVolumePath, groupId, filename, dataUri);

      return {
        success: true,
        error: undefined,
        data: filename, // return the filename when successful
      };
    } catch {
      return {
        success: false,
        error: 'putInStorage failed',
        data: undefined,
      };
    }
  };
};

Version 3 (latest)

import fs from 'fs/promises';
import path from 'path';
import { StorageFunction, StorageFunctionOptions, StorageFunctionResult } from '../types';
import { getStorageFilePath, ensureDirectoryExists, isValidFilename } from '../utils';
import type { CwcStorageConfig } from '../../../config';

// Payload type for this storage function
type Payload = {
  projectId: string;
  filename: string;
  dataUri: string;
};

/**
 * Writes a file to the filesystem storage
 * @param storageVolumePath - Base path to storage volume
 * @param projectId - Project identifier
 * @param filename - Name of the file to save
 * @param dataUri - File data as string (will be converted to Buffer)
 * @returns true if successful
 */
const writeToFilesystem = async (
  storageVolumePath: string,
  projectId: string,
  filename: string,
  dataUri: string
): Promise<boolean> => {
  const filePath = getStorageFilePath(storageVolumePath, projectId, filename);
  const dirPath = path.dirname(filePath);

  // Ensure the project directory exists
  await ensureDirectoryExists(dirPath);

  // Convert dataUri to Buffer and write to file
  const data = Buffer.from(dataUri);
  await fs.writeFile(filePath, data);

  return true;
};

/**
 * Creates a storage function to save a file to filesystem storage
 */
export const createPutInStorage = (config: CwcStorageConfig): StorageFunction<string> => {
  return async ({ payload }: StorageFunctionOptions): Promise<StorageFunctionResult<string>> => {
    const { projectId, filename, dataUri } = payload as Payload;

    // Validate projectId
    if (!projectId) {
      return {
        success: false,
        error: 'projectId is undefined',
        data: undefined,
      };
    }

    // Validate filename
    if (!filename) {
      return {
        success: false,
        error: 'filename is undefined',
        data: undefined,
      };
    }

    // Validate filename safety
    if (!isValidFilename(filename)) {
      return {
        success: false,
        error: 'invalid filename',
        data: undefined,
      };
    }

    // Validate dataUri
    if (!dataUri) {
      return {
        success: false,
        error: 'dataUri is undefined',
        data: undefined,
      };
    }

    try {
      // Write the file to filesystem
      await writeToFilesystem(config.storageVolumePath, projectId, filename, dataUri);

      return {
        success: true,
        error: undefined,
        data: filename, // return the filename when successful
      };
    } catch {
      return {
        success: false,
        error: 'putInStorage failed',
        data: undefined,
      };
    }
  };
};

packages/cwc-storage/src/apis/StorageApiV1/StorageHandler.ts

2 versions

Version 1

'use strict';

import { Logger } from '../../Logger';
import { RequestPayload } from '../../types';
import {
  StorageHandlerResponse,
  StorageRouteHandler,
  StorageRouteHandlerOptions,
  StorageFunction,
  StorageFunctionResult,
} from './types';
import { requestError, requestFailed } from './utils';

import { config } from '../../configuration';

const codeLocation = './src/apis/StorageApiV1/StorageHandler.ts';

export class StorageHandler implements StorageRouteHandler {
  public get serviceFunctionType() {
    return 'storage';
  }
  private payload: RequestPayload;
  private path: string;
  private debug: boolean = false;
  private worker: StorageFunction<unknown>;
  private logger: Logger;

  constructor({ payload, routeConfig }: StorageRouteHandlerOptions) {
    this.logger = new Logger({
      logPath: config.logPath,
      serviceName: 'cwc-storage',
      debugMode: config.debugMode,
    });
    this.payload = payload;
    this.path = routeConfig.path;
    this.debug = Boolean(routeConfig.debug);
    this.worker = routeConfig.worker as StorageFunction<unknown>;

    this.debugInfo('constructor', { path: this.path });
  }

  private debugInfo(description: string, info: unknown) {
    if (this.debug) {
      this.logger.logInformation({
        username: undefined,
        codeLocation,
        message: `${this.path} - ${description}`,
        value: { info },
      });
    }
  }

  public async processRequest(): Promise<StorageHandlerResponse> {
    try {
      // Execute the worker function with the payload
      const workerResult: StorageFunctionResult<unknown> = await this.worker({
        payload: this.payload,
      });

      if (!workerResult.success || !workerResult.data || workerResult.error) {
        this.logger.logError({
          username: undefined,
          codeLocation,
          message: 'processRequest',
          error: workerResult.error,
          value: undefined,
          request: { path: this.path, payload: this.payload },
        });
        return requestFailed(workerResult.error || 'storage operation failed');
      }

      // Successfully processed the request
      const result: StorageHandlerResponse = {
        statusCode: 200,
        success: true,
        data: workerResult.data,
        error: undefined,
      };
      return result;
    } catch (error) {
      this.logger.logError({
        username: undefined,
        codeLocation,
        message: 'processRequest',
        error,
        value: undefined,
        request: { path: this.path, payload: this.payload },
      });
      return await requestError(error);
    }
  }
}

Version 2 (latest)

'use strict';

import { Logger } from '../../Logger';
import { RequestPayload } from '../../types';
import {
  StorageHandlerResponse,
  StorageRouteHandler,
  StorageRouteHandlerOptions,
  StorageFunction,
  StorageFunctionResult,
} from './types';
import { requestError, requestFailed } from './utils';
import type { CwcStorageConfig } from '../../config';

const codeLocation = './src/apis/StorageApiV1/StorageHandler.ts';

export class StorageHandler implements StorageRouteHandler {
  public get serviceFunctionType(): string {
    return 'storage';
  }
  private payload: RequestPayload;
  private path: string;
  private debug: boolean = false;
  private worker: StorageFunction<unknown>;
  private logger: Logger;

  constructor({ payload, routeConfig }: StorageRouteHandlerOptions, config: CwcStorageConfig) {
    this.logger = new Logger({
      logPath: config.logPath,
      serviceName: 'cwc-storage',
      debugMode: config.debugMode,
    });
    this.payload = payload;
    this.path = routeConfig.path;
    this.debug = Boolean(routeConfig.debug);
    this.worker = routeConfig.worker as StorageFunction<unknown>;

    this.debugInfo('constructor', { path: this.path });
  }

  private debugInfo(description: string, info: unknown): void {
    if (this.debug) {
      this.logger.logInformation({
        username: undefined,
        codeLocation,
        message: `${this.path} - ${description}`,
        value: { info },
      });
    }
  }

  public async processRequest(): Promise<StorageHandlerResponse> {
    try {
      // Execute the worker function with the payload
      const workerResult: StorageFunctionResult<unknown> = await this.worker({
        payload: this.payload,
      });

      if (!workerResult.success || !workerResult.data || workerResult.error) {
        this.logger.logError({
          username: undefined,
          codeLocation,
          message: 'processRequest',
          error: workerResult.error,
          value: undefined,
          request: { path: this.path, payload: this.payload },
        });
        return requestFailed(workerResult.error || 'storage operation failed');
      }

      // Successfully processed the request
      const result: StorageHandlerResponse = {
        statusCode: 200,
        success: true,
        data: workerResult.data,
        error: undefined,
      };
      return result;
    } catch (error) {
      this.logger.logError({
        username: undefined,
        codeLocation,
        message: 'processRequest',
        error,
        value: undefined,
        request: { path: this.path, payload: this.payload },
      });
      return await requestError(error);
    }
  }
}

packages/cwc-storage/src/apis/StorageApiV1/utils.ts

3 versions

Version 1

import path from 'path';
import fs from 'fs/promises';
import { StorageHandlerResponse, StorageFunctionResult } from './types';

export const requestFailed = (error: unknown): StorageHandlerResponse => {
  if (typeof error !== 'string') {
    error = 'server error';
  }
  return {
    statusCode: 400, // bad request
    success: false,
    data: undefined,
    error,
  };
};

export const requestError = async (error: unknown): Promise<StorageHandlerResponse> => {
  return requestFailed(error);
};

export const fetchSuccess = <ResultType>(
  data: ResultType | undefined
): StorageFunctionResult<ResultType> => {
  return {
    success: true,
    error: undefined,
    data,
  };
};

export const fetchFailed = <ResultType>(
  error: string | unknown
): StorageFunctionResult<ResultType> => {
  return {
    success: false,
    error,
    data: undefined,
  };
};

/**
 * Constructs the full filesystem path for a storage file
 * @param storageVolumePath - Base path to the storage volume
 * @param groupId - Group identifier
 * @param filename - Name of the file
 * @returns Full path to the file
 */
export const getStorageFilePath = (
  storageVolumePath: string,
  groupId: string,
  filename: string
): string => {
  return path.join(storageVolumePath, groupId, filename);
};

/**
 * Ensures that a directory exists, creating it if necessary
 * @param dirPath - Directory path to ensure exists
 */
export const ensureDirectoryExists = async (dirPath: string): Promise<void> => {
  try {
    await fs.mkdir(dirPath, { recursive: true });
  } catch (error) {
    // If error is not "already exists", rethrow
    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
      throw error;
    }
  }
};

/**
 * Validates that a filename is safe (no path traversal attempts)
 * @param filename - Filename to validate
 * @returns true if filename is safe
 */
export const isValidFilename = (filename: string): boolean => {
  if (!filename || typeof filename !== 'string') {
    return false;
  }
  // Reject filenames with path separators or relative path indicators
  if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
    return false;
  }
  // Reject empty or whitespace-only filenames
  if (filename.trim().length === 0) {
    return false;
  }
  return true;
};

Version 2

import path from 'path';
import fs from 'fs/promises';
import { StorageHandlerResponse, StorageFunctionResult } from './types';

// Note: fs is used by ensureDirectoryExists

export const requestFailed = (error: unknown): StorageHandlerResponse => {
  if (typeof error !== 'string') {
    error = 'server error';
  }
  return {
    statusCode: 400, // bad request
    success: false,
    data: undefined,
    error,
  };
};

export const requestError = async (error: unknown): Promise<StorageHandlerResponse> => {
  return requestFailed(error);
};

export const fetchSuccess = <ResultType>(
  data: ResultType | undefined
): StorageFunctionResult<ResultType> => {
  return {
    success: true,
    error: undefined,
    data,
  };
};

export const fetchFailed = <ResultType>(
  error: string | unknown
): StorageFunctionResult<ResultType> => {
  return {
    success: false,
    error,
    data: undefined,
  };
};

/**
 * Constructs the full filesystem path for a storage file
 * @param storageVolumePath - Base path to the storage volume
 * @param groupId - Group identifier
 * @param filename - Name of the file
 * @returns Full path to the file
 */
export const getStorageFilePath = (
  storageVolumePath: string,
  groupId: string,
  filename: string
): string => {
  return path.join(storageVolumePath, groupId, filename);
};

/**
 * Ensures that a directory exists, creating it if necessary
 * @param dirPath - Directory path to ensure exists
 */
export const ensureDirectoryExists = async (dirPath: string): Promise<void> => {
  try {
    await fs.mkdir(dirPath, { recursive: true });
  } catch (error) {
    // If error is not "already exists", rethrow
    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
      throw error;
    }
  }
};

/**
 * Validates that a filename is safe (no path traversal attempts)
 * @param filename - Filename to validate
 * @returns true if filename is safe
 */
export const isValidFilename = (filename: string): boolean => {
  if (!filename || typeof filename !== 'string') {
    return false;
  }
  // Reject filenames with path separators or relative path indicators
  if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
    return false;
  }
  // Reject empty or whitespace-only filenames
  if (filename.trim().length === 0) {
    return false;
  }
  return true;
};

Version 3 (latest)

import path from 'path';
import fs from 'fs/promises';
import { StorageHandlerResponse, StorageFunctionResult } from './types';

// Note: fs is used by ensureDirectoryExists

export const requestFailed = (error: unknown): StorageHandlerResponse => {
  if (typeof error !== 'string') {
    error = 'server error';
  }
  return {
    statusCode: 400, // bad request
    success: false,
    data: undefined,
    error,
  };
};

export const requestError = async (error: unknown): Promise<StorageHandlerResponse> => {
  return requestFailed(error);
};

export const fetchSuccess = <ResultType>(
  data: ResultType | undefined
): StorageFunctionResult<ResultType> => {
  return {
    success: true,
    error: undefined,
    data,
  };
};

export const fetchFailed = <ResultType>(
  error: string | unknown
): StorageFunctionResult<ResultType> => {
  return {
    success: false,
    error,
    data: undefined,
  };
};

/**
 * Constructs the full filesystem path for a storage file
 * @param storageVolumePath - Base path to the storage volume
 * @param projectId - Project identifier
 * @param filename - Name of the file
 * @returns Full path to the file
 */
export const getStorageFilePath = (
  storageVolumePath: string,
  projectId: string,
  filename: string
): string => {
  return path.join(storageVolumePath, projectId, filename);
};

/**
 * Ensures that a directory exists, creating it if necessary
 * @param dirPath - Directory path to ensure exists
 */
export const ensureDirectoryExists = async (dirPath: string): Promise<void> => {
  try {
    await fs.mkdir(dirPath, { recursive: true });
  } catch (error) {
    // If error is not "already exists", rethrow
    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
      throw error;
    }
  }
};

/**
 * Validates that a filename is safe (no path traversal attempts)
 * @param filename - Filename to validate
 * @returns true if filename is safe
 */
export const isValidFilename = (filename: string): boolean => {
  if (!filename || typeof filename !== 'string') {
    return false;
  }
  // Reject filenames with path separators or relative path indicators
  if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
    return false;
  }
  // Reject empty or whitespace-only filenames
  if (filename.trim().length === 0) {
    return false;
  }
  return true;
};

packages/cwc-storage/src/config/config.types.ts

2 versions

Version 1

import type { RuntimeEnvironment } from 'cwc-types';

/**
 * Configuration for the cwc-storage microservice
 */
export type CwcStorageConfig = {
  // Environment
  runtimeEnvironment: RuntimeEnvironment;
  isProduction: boolean;
  isDevelopment: boolean;
  isTest: boolean;
  isUnitTest: boolean;
  isEndToEnd: boolean;

  // Service
  servicePort: number;

  // Security
  corsOrigin: string;
  storageApiKey: string;

  // Rate limiting
  rateLimiterPoints: number;
  rateLimiterDuration: number;

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

  // Debugging
  debugMode: boolean;

  // Storage-specific settings
  storageVolumePath: string;
  logPath: string;
};

Version 2 (latest)

import type { RuntimeEnvironment } from 'cwc-types';

/**
 * Configuration for the cwc-storage microservice
 */
export type CwcStorageConfig = {
  // Environment
  runtimeEnvironment: RuntimeEnvironment;
  isProduction: boolean;
  isDevelopment: boolean;
  isTest: boolean;
  isUnitTest: boolean;
  isEndToEnd: boolean;

  // Service
  servicePort: number;

  // Security
  corsOrigin: string;
  storageApiKey: string;

  // Rate limiting
  rateLimiterPoints: number;
  rateLimiterDuration: number;

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

  // Debugging
  debugMode: boolean;

  // Storage-specific settings
  storageVolumePath: string;
  logPath: string;
};

packages/cwc-storage/src/config/index.ts

2 versions

Version 1

export { loadConfig } from './loadConfig';
export type { CwcStorageConfig } from './config.types';

Version 2 (latest)

export { loadConfig } from './loadConfig';
export type { CwcStorageConfig } from './config.types';

packages/cwc-storage/src/config/loadConfig.ts

2 versions

Version 1

import type { RuntimeEnvironment } from 'cwc-types';
import {
  requireEnv,
  optionalEnv,
  parseNumber,
  parseBoolean,
  parseJson,
} from 'cwc-backend-utils';
import type { CwcStorageConfig } from './config.types';

/**
 * Validates runtime environment value
 */
function validateRuntimeEnvironment(value: string): RuntimeEnvironment {
  const validEnvironments = ['dev', 'test', 'prod', 'unit', 'e2e'];
  if (!validEnvironments.includes(value)) {
    throw new Error(
      `Invalid RUNTIME_ENVIRONMENT: ${value}. Must be one of: ${validEnvironments.join(', ')}`
    );
  }
  return value as RuntimeEnvironment;
}

/**
 * Loads and validates configuration from environment variables
 * Caches the configuration on first load
 */
let cachedConfig: CwcStorageConfig | undefined;

export function loadConfig(): CwcStorageConfig {
  // Return cached config if already loaded
  if (cachedConfig) {
    return cachedConfig;
  }

  try {
    // Parse runtime environment
    const runtimeEnvironment = validateRuntimeEnvironment(requireEnv('RUNTIME_ENVIRONMENT'));

    // Derive environment booleans
    const isProduction = runtimeEnvironment === 'prod';
    const isDevelopment = runtimeEnvironment === 'dev';
    const isTest = runtimeEnvironment === 'test';
    const isUnitTest = runtimeEnvironment === 'unit';
    const isEndToEnd = runtimeEnvironment === 'e2e';

    // Parse configuration
    const config: CwcStorageConfig = {
      // Environment
      runtimeEnvironment,
      isProduction,
      isDevelopment,
      isTest,
      isUnitTest,
      isEndToEnd,

      // Service
      servicePort: parseNumber('SERVICE_PORT', 5004),

      // Security
      corsOrigin: requireEnv('CORS_ORIGIN'),
      storageApiKey: requireEnv('STORAGE_API_KEY'),

      // Rate limiting
      rateLimiterPoints: parseNumber('RATE_LIMITER_POINTS', 15),
      rateLimiterDuration: parseNumber('RATE_LIMITER_DURATION', 1),

      // Development settings
      devMachines: parseJson<{ name: string; ip: string }[]>('DEV_MACHINES', []),
      devCorsOrigin: optionalEnv('DEV_CORS_ORIGIN', ''),

      // Debugging
      debugMode: parseBoolean('DEBUG_MODE', false),

      // Storage-specific settings
      storageVolumePath: requireEnv('STORAGE_VOLUME_PATH'),
      logPath: optionalEnv('LOG_PATH', './logs'),
    };

    // Validate port
    if (config.servicePort < 1 || config.servicePort > 65535) {
      throw new Error('SERVICE_PORT must be between 1 and 65535');
    }

    // Validate storage volume path is not empty
    if (config.storageVolumePath.trim() === '') {
      throw new Error('STORAGE_VOLUME_PATH cannot be empty');
    }

    // Cache the configuration
    cachedConfig = config;

    // Log configuration in debug mode (redact sensitive data)
    if (config.debugMode) {
      console.log('[cwc-storage] Configuration loaded:');
      console.log(`  Environment: ${config.runtimeEnvironment}`);
      console.log(`  Service Port: ${config.servicePort}`);
      console.log(`  CORS Origin: ${config.corsOrigin}`);
      console.log(`  Storage API Key: [REDACTED]`);
      console.log(`  Rate Limiter: ${config.rateLimiterPoints} points / ${config.rateLimiterDuration}s`);
      console.log(`  Storage Volume Path: ${config.storageVolumePath}`);
      console.log(`  Log Path: ${config.logPath}`);
      console.log(`  Debug Mode: ${config.debugMode}`);
    }

    return config;
  } catch (error) {
    console.error('[cwc-storage] Failed to load configuration:');
    if (error instanceof Error) {
      console.error(`  ${error.message}`);
    } else {
      console.error(error);
    }
    console.error('\nPlease check your environment variables and try again.');
    process.exit(1);
  }
}

Version 2 (latest)

import type { RuntimeEnvironment } from 'cwc-types';
import {
  requireEnv,
  optionalEnv,
  parseNumber,
  parseBoolean,
  parseJson,
} from 'cwc-backend-utils';
import type { CwcStorageConfig } from './config.types';

/**
 * Validates runtime environment value
 */
function validateRuntimeEnvironment(value: string): RuntimeEnvironment {
  const validEnvironments = ['dev', 'test', 'prod', 'unit', 'e2e'];
  if (!validEnvironments.includes(value)) {
    throw new Error(
      `Invalid RUNTIME_ENVIRONMENT: ${value}. Must be one of: ${validEnvironments.join(', ')}`
    );
  }
  return value as RuntimeEnvironment;
}

/**
 * Loads and validates configuration from environment variables
 * Caches the configuration on first load
 */
let cachedConfig: CwcStorageConfig | undefined;

export function loadConfig(): CwcStorageConfig {
  // Return cached config if already loaded
  if (cachedConfig) {
    return cachedConfig;
  }

  try {
    // Parse runtime environment
    const runtimeEnvironment = validateRuntimeEnvironment(requireEnv('RUNTIME_ENVIRONMENT'));

    // Derive environment booleans
    const isProduction = runtimeEnvironment === 'prod';
    const isDevelopment = runtimeEnvironment === 'dev';
    const isTest = runtimeEnvironment === 'test';
    const isUnitTest = runtimeEnvironment === 'unit';
    const isEndToEnd = runtimeEnvironment === 'e2e';

    // Parse configuration
    const config: CwcStorageConfig = {
      // Environment
      runtimeEnvironment,
      isProduction,
      isDevelopment,
      isTest,
      isUnitTest,
      isEndToEnd,

      // Service
      servicePort: parseNumber('SERVICE_PORT', 5004),

      // Security
      corsOrigin: requireEnv('CORS_ORIGIN'),
      storageApiKey: requireEnv('STORAGE_API_KEY'),

      // Rate limiting
      rateLimiterPoints: parseNumber('RATE_LIMITER_POINTS', 15),
      rateLimiterDuration: parseNumber('RATE_LIMITER_DURATION', 1),

      // Development settings
      devMachines: parseJson<{ name: string; ip: string }[]>('DEV_MACHINES', []),
      devCorsOrigin: optionalEnv('DEV_CORS_ORIGIN', ''),

      // Debugging
      debugMode: parseBoolean('DEBUG_MODE', false),

      // Storage-specific settings
      storageVolumePath: requireEnv('STORAGE_VOLUME_PATH'),
      logPath: optionalEnv('LOG_PATH', './logs'),
    };

    // Validate port
    if (config.servicePort < 1 || config.servicePort > 65535) {
      throw new Error('SERVICE_PORT must be between 1 and 65535');
    }

    // Validate storage volume path is not empty
    if (config.storageVolumePath.trim() === '') {
      throw new Error('STORAGE_VOLUME_PATH cannot be empty');
    }

    // Cache the configuration
    cachedConfig = config;

    // Log configuration in debug mode (redact sensitive data)
    if (config.debugMode) {
      console.log('[cwc-storage] Configuration loaded:');
      console.log(`  Environment: ${config.runtimeEnvironment}`);
      console.log(`  Service Port: ${config.servicePort}`);
      console.log(`  CORS Origin: ${config.corsOrigin}`);
      console.log(`  Storage API Key: [REDACTED]`);
      console.log(`  Rate Limiter: ${config.rateLimiterPoints} points / ${config.rateLimiterDuration}s`);
      console.log(`  Storage Volume Path: ${config.storageVolumePath}`);
      console.log(`  Log Path: ${config.logPath}`);
      console.log(`  Debug Mode: ${config.debugMode}`);
    }

    return config;
  } catch (error) {
    console.error('[cwc-storage] Failed to load configuration:');
    if (error instanceof Error) {
      console.error(`  ${error.message}`);
    } else {
      console.error(error);
    }
    console.error('\nPlease check your environment variables and try again.');
    process.exit(1);
  }
}

packages/cwc-storage/src/environment.d.ts

2 versions

Version 1

declare namespace NodeJS {
  interface ProcessEnv {
    ENVIRONMENT: string; // 'dev' | 'prod' | 'test';

    // CONFIG SETTINGS
    CORS_ORIGIN: string;

    // rate limiter
    RATE_LIMITER_POINTS: string;
    RATE_LIMITER_DURATION: string;

    // logging
    DEBUG_MODE: 'OFF' | 'ON';

    // development settings
    DEV_MACHINES: string;
    DEV_CORS_ORIGIN: string;

    // filesystem storage
    STORAGE_VOLUME_PATH: string;
    LOG_PATH: string;

    // SECRETS
    STORAGE_API_KEY: string;
  }
}

Version 2 (latest)

declare namespace NodeJS {
  interface ProcessEnv {
    // Environment
    RUNTIME_ENVIRONMENT: string; // 'dev' | 'prod' | 'test' | 'unit' | 'e2e'

    // Service
    SERVICE_PORT: string;

    // Security
    CORS_ORIGIN: string;
    STORAGE_API_KEY: string;

    // Rate limiter
    RATE_LIMITER_POINTS: string;
    RATE_LIMITER_DURATION: string;

    // Development settings
    DEV_MACHINES: string;
    DEV_CORS_ORIGIN: string;

    // Debugging
    DEBUG_MODE: 'OFF' | 'ON';

    // Storage-specific settings
    STORAGE_VOLUME_PATH: string;
    LOG_PATH: string;
  }
}

packages/cwc-storage/src/index.ts

3 versions

Version 1

// cwc-storage - File storage service for CWC application
// This package provides file storage capabilities

export {};

Version 2

import { config } from './configuration';
import { createExpressService } from 'cwc-backend-utils';
import { StorageApi } from './types';

import { StorageApiV1 } from './apis/StorageApiV1';

console.log(`
 .d8888b. 88888888888 .d88888b.  8888888b.         d8888  .d8888b.  8888888888
d88P  Y88b    888    d88P" "Y88b 888   Y88b       d88888 d88P  Y88b 888
Y88b.         888    888     888 888    888      d88P888 888    888 888
 "Y888b.      888    888     888 888   d88P     d88P 888 888        8888888
    "Y88b.    888    888     888 8888888P"     d88P  888 888  88888 888
      "888    888    888     888 888 T88b     d88P   888 888    888 888
Y88b  d88P    888    Y88b. .d88P 888  T88b   d8888888888 Y88b  d88P 888
 "Y8888P"     888     "Y88888P"  888   T88b d88P     888  "Y8888P88 8888888888
`);

const apis: StorageApi[] = [new StorageApiV1()];

const service = createExpressService({
  config,
  serviceName: 'cwc-storage',
  apis,
  allowGet: false,
  allowOptions: true,
  allowPost: true,
  payloadLimit: '2mb',
});
service.start(apis);

// exported for jest/supertest testing
export { service };

Version 3 (latest)

import {
  loadDotEnv,
  createExpressService,
  type ExpressApi,
  type BackendUtilsConfigBasic,
} from 'cwc-backend-utils';
import type { RuntimeEnvironment } from 'cwc-types';
import type { CwcStorageConfig } from './config';
import { loadConfig } from './config';
import { StorageApiV1 } from './apis/StorageApiV1';

console.log(`
 .d8888b. 88888888888 .d88888b.  8888888b.         d8888  .d8888b.  8888888888
d88P  Y88b    888    d88P" "Y88b 888   Y88b       d88888 d88P  Y88b 888
Y88b.         888    888     888 888    888      d88P888 888    888 888
 "Y888b.      888    888     888 888   d88P     d88P 888 888        8888888
    "Y88b.    888    888     888 8888888P"     d88P  888 888  88888 888
      "888    888    888     888 888 T88b     d88P   888 888    888 888
Y88b  d88P    888    Y88b. .d88P 888  T88b   d8888888888 Y88b  d88P 888
 "Y8888P"     888     "Y88888P"  888   T88b d88P     888  "Y8888P88 8888888888
`);

/**
 * Converts CwcStorageConfig to BackendUtilsConfigBasic for createExpressService
 */
function createBackendUtilsConfig(storageConfig: CwcStorageConfig): BackendUtilsConfigBasic {
  return {
    debugMode: storageConfig.debugMode,
    isDevelopment: storageConfig.isDevelopment,
    isTest: storageConfig.isTest,
    isProduction: storageConfig.isProduction,
    isUnitTest: storageConfig.isUnitTest,
    isEndToEnd: storageConfig.isEndToEnd,
    corsOrigin: storageConfig.corsOrigin,
    servicePort: storageConfig.servicePort,
    rateLimiterPoints: storageConfig.rateLimiterPoints,
    rateLimiterDuration: storageConfig.rateLimiterDuration,
    devMachines: storageConfig.devMachines,
    devCorsOrigin: storageConfig.devCorsOrigin,
  };
}

/**
 * Main entry point for the cwc-storage microservice
 */
async function main(): Promise<void> {
  try {
    console.log('[cwc-storage] Starting cwc-storage microservice...');

    // Load environment variables
    loadDotEnv({
      serviceName: 'cwc-storage',
      environment: (process.env['RUNTIME_ENVIRONMENT'] as RuntimeEnvironment) || 'dev',
      debug: process.env['DEBUG_MODE'] === 'ON',
    });

    // Load and validate configuration
    const config = loadConfig();

    console.log('[cwc-storage] Configuration loaded successfully');

    // Create API instances
    const apis: ExpressApi[] = [new StorageApiV1(config)];

    // Create Express service
    const service = createExpressService({
      config: createBackendUtilsConfig(config),
      serviceName: 'cwc-storage',
      apis,
      allowGet: false,
      allowOptions: true,
      allowPost: true,
      payloadLimit: '2mb',
    });

    // Start the service
    service.start(apis);

    console.log('');
    console.log('='.repeat(60));
    console.log(`[cwc-storage] Service started successfully`);
    console.log(`[cwc-storage] Environment: ${config.runtimeEnvironment}`);
    console.log(`[cwc-storage] Port: ${config.servicePort}`);
    console.log(`[cwc-storage] Storage Volume: ${config.storageVolumePath}`);
    console.log(`[cwc-storage] Debug: ${config.debugMode ? 'enabled' : 'disabled'}`);
    console.log('='.repeat(60));
    console.log('');

    // Handle graceful shutdown
    const shutdown = async (signal: string): Promise<void> => {
      console.log(`\n[cwc-storage] Received ${signal}, shutting down gracefully...`);

      try {
        // Close HTTP server
        await new Promise<void>((resolve, reject) => {
          service.httpServer.close((err) => {
            if (err) {
              reject(err);
            } else {
              resolve();
            }
          });
        });

        console.log('[cwc-storage] HTTP server closed');
        console.log('[cwc-storage] Shutdown complete');
        process.exit(0);
      } catch (error) {
        console.error('[cwc-storage] Error during shutdown:', error);
        process.exit(1);
      }
    };

    // Register shutdown handlers
    process.on('SIGTERM', () => shutdown('SIGTERM'));
    process.on('SIGINT', () => shutdown('SIGINT'));

    // Handle uncaught errors
    process.on('unhandledRejection', (reason, promise) => {
      console.error('[cwc-storage] Unhandled Rejection at:', promise, 'reason:', reason);

      // Don't exit on unhandled rejection in production
      if (!config.isProduction) {
        process.exit(1);
      }
    });

    process.on('uncaughtException', (error) => {
      console.error('[cwc-storage] Uncaught Exception:', error);

      // Always exit on uncaught exception
      process.exit(1);
    });
  } catch (error) {
    console.error('[cwc-storage] Failed to start service:', error);
    process.exit(1);
  }
}

// Start the service
main();

// Export for testing
export { main };

packages/cwc-storage/src/types.ts

2 versions

Version 1

import { RequestHandler } from 'express';
import { RuntimeEnvironment } from 'cwc-types';

// **************************************************************************************
// cwc-storage service types
// **************************************************************************************

export interface Secrets {
  storageApiKey?: string;
}

export interface Configuration {
  environment: RuntimeEnvironment;
  corsOrigin: string;
  rateLimiterPoints: number;
  rateLimiterDuration: number;
  debugMode: boolean;
  // development settings
  devMachines:
    | undefined
    | {
        name: string;
        ip: string;
      }[];
  devCorsOrigin: string;

  // filesystem storage config settings
  storageVolumePath: string;
  logPath: string;

  // secrets
  secrets: Secrets | undefined;
}

export interface CachedConfiguration extends Configuration {
  name: string;
  servicePort: number;
  isProduction: boolean;
  isTest: boolean;
  isDevelopment: boolean;
  isUnitTest: boolean;
  isEndToEnd: boolean;
}

// // *************
// // api
// // *************

export interface StorageApi {
  version: number;
  handler: RequestHandler;
  path: string;
}

export type RequestPayloadValue = string | number | boolean | object | undefined;

export type RequestPayload = {
  [key: string]: RequestPayloadValue;
};

Version 2 (latest)

import { RequestHandler } from 'express';

// **************************************************************************************
// cwc-storage service types
// **************************************************************************************

// Note: Configuration types are now in src/config/config.types.ts

// *************
// api
// *************

export type StorageApi = {
  version: number;
  handler: RequestHandler;
  path: string;
};

export type RequestPayloadValue = string | number | boolean | object | undefined;

export type RequestPayload = {
  [key: string]: RequestPayloadValue;
};

packages/cwc-storage/tsconfig.json

2 versions

Version 1

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

Version 2 (latest)

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

packages/cwc-types/src/entityTypes.ts

2 versions

Version 1

/**
 * CWC Database Entity Types
 *
 * This file contains TypeScript type definitions for all database entities.
 * Generated from the database schema in packages/cwc-database/schema-definition/
 *
 * Type Generation Conventions:
 * - All entity types prefixed with 'Cwc' to avoid naming conflicts
 * - Union types fully qualified with entity context to prevent ambiguity
 * - Use 'type' (not 'interface') for entity definitions
 * - Use string literal union types (not enums) for enum-like VARCHAR fields
 * - DATETIME columns mapped to string (ISO 8601 format)
 * - TINYINT columns mapped to boolean
 * - All fields required by default (even if DB allows NULL)
 * - Optional fields (?) only for business-critical reasons
 *
 * Working with Incomplete Data:
 * When working with partial entity data (e.g., during INSERT operations
 * where PkId doesn't exist yet, or multi-step processes), use TypeScript's
 * Partial<T> utility type:
 *
 * @example
 * // For INSERT operations (omit auto-generated fields)
 * type UserInsert = Omit<CwcUser, 'userPkId' | 'createdDate' | 'modifiedDate'>;
 *
 * // For partial updates
 * const partialUser: Partial<CwcUser> = { email: 'new@example.com' };
 *
 * // For specific operation requirements
 * type UserUpdate = Partial<UserInsert> & Pick<CwcUser, 'userPkId'>;
 */

// ============================================================================
// Union Types for Enum-like VARCHAR Fields
// ============================================================================

/**
 * Status values for abuse reports
 */
export type CwcAbuseReportStatus =
  | 'submitted'
  | 'investigation'
  | 'dismissed'
  | 'resolved'
  | 'retracted';

/**
 * Entity types that can be commented on
 * Note: Each entity using this type may have different allowed values
 */
export type CwcCommentEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

/**
 * Content types for coding session content blocks
 */
export type CwcCodingSessionContentType = 'prompt' | 'response' | 'note' | 'attachment';

/**
 * MIME types for coding session attachments
 */
export type CwcCodingSessionAttachmentMimeType = 'image/png' | 'image/jpg';

/**
 * Entity types that can be reported for inappropriate content
 * Note: May differ from comment entity types in the future
 */
export type CwcContentReportEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

/**
 * Status values for content reports
 */
export type CwcContentReportStatus =
  | 'submitted'
  | 'investigation'
  | 'dismissed'
  | 'resolved'
  | 'retracted';

/**
 * Error log severity/type levels
 */
export type CwcErrorLogType = 'error' | 'info' | 'warn' | 'debug';

/**
 * Service names for error logging
 */
export type CwcErrorLogServiceName =
  | 'cwc-auth'
  | 'cwc-api'
  | 'cwc-sql'
  | 'cwc-website'
  | 'cwc-admin-api';

/**
 * Feature flag type classification
 */
export type CwcFeatureFlagType = 'feature' | 'system';

/**
 * Platform targets for feature flags
 */
export type CwcFeatureFlagPlatform = 'all' | 'web' | 'android' | 'ios' | 'mobile';

/**
 * Service names for feature flag targeting
 */
export type CwcFeatureFlagServiceName =
  | 'all'
  | 'frontend'
  | 'backend'
  | 'cwc-app'
  | 'cwc-sql'
  | 'cwc-auth'
  | 'cwc-api'
  | 'cwc-admin-api'
  | 'cwc-dashboard';

/**
 * Value types for feature flag values
 */
export type CwcFeatureFlagValueType = 'boolean' | 'number' | 'string' | 'object';

/**
 * Login/authentication types
 * Shared by user and signupInfo entities
 */
export type CwcLoginType = 'cwc' | 'facebook' | 'google';

/**
 * Project type classifications
 */
export type CwcProjectType = 'web' | 'mobile' | 'backend' | 'ai';

/**
 * Reaction emoji names
 */
export type CwcReactionName = 'love' | 'funny' | 'sad' | 'wow' | 'thumbs-up';

/**
 * Entity types that can receive reactions
 * Note: May differ from comment/report entity types in the future
 */
export type CwcReactionEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

// ============================================================================
// Entity Types
// ============================================================================

/**
 * Abuse Report
 * Tracks user reports of abusive behavior or accounts
 */
export type CwcAbuseReport = {
  abuseReportPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  usernames: string;
  message: string;
  status: CwcAbuseReportStatus;
};

/**
 * Admin User
 * Administrative users for the dashboard
 */
export type CwcAdminUser = {
  adminUserPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  adminUsername: string;
  password: string;
};

/**
 * Admin User JWT
 * JWT validation/revocation for admin users
 * Contains only JWT ID for lookup; payload contains full user context
 */
export type CwcAdminUserJwt = {
  adminUserJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  adminUserJwtId: string;
};

/**
 * Coding Session
 * Individual coding sessions within a project
 * Stores metadata and reference to session data in cwc-storage
 */
export type CwcCodingSession = {
  codingSessionPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  description: string;
  published: boolean;
  sessionId: string;
  storageKey: string;
  startTimestamp: string;
  endTimestamp: string;
  gitBranch: string;
  model: string;
  messageCount: number;
  filesModifiedCount: number;
};

/**
 * Coding Session Attachment
 * Images and files attached to coding sessions
 */
export type CwcCodingSessionAttachment = {
  codingSessionAttachmentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  codingSessionPkId: number;
  filename: string;
  mimeType: CwcCodingSessionAttachmentMimeType;
  height: number;
  width: number;
};

/**
 * Coding Session Content
 * Content blocks (prompts, responses, notes, attachments) within a session
 * Uses displayIndex for rendering order of all content types
 * Polymorphic: text OR attachment based on contentType
 */
export type CwcCodingSessionContent = {
  codingSessionContentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  contentType: CwcCodingSessionContentType;
  codingSessionPkId: number;
  codingSessionAttachmentPkId?: number; // Optional: only present when contentType='attachment'
  displayIndex: number;
  text?: string; // Optional: NULL for pure attachment blocks, or optional caption for attachments
};

/**
 * Comment
 * User comments on various entities (polymorphic relationship)
 * Uses entityPkId + entityType pattern to reference any commentable entity
 */
export type CwcComment = {
  commentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectPkId: number;
  userPkId: number;
  entityPkId: number;
  entityType: CwcCommentEntityType;
  text: string;
};

/**
 * Content Report
 * User reports of inappropriate content (polymorphic relationship)
 */
export type CwcContentReport = {
  contentReportPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  entityPkId: number;
  entityType: CwcContentReportEntityType;
  message: string;
  status: CwcContentReportStatus;
};

/**
 * Email Verify
 * Email verification tracking (standalone, not tied to signup/reset)
 */
export type CwcEmailVerify = {
  emailVerifyPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  confirmationCode: string;
  email: string;
  deviceId: string;
  confirmed: boolean;
  emailVerificationId: string;
};

/**
 * Error Log
 * Centralized error logging for all microservices
 */
export type CwcErrorLog = {
  errorLogPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId?: number | undefined; // Optional: errors can occur without user context
  projectPkId?: number | undefined; // Optional: errors can occur without project context
  serviceName: CwcErrorLogServiceName;
  codeLocation: string;
  dismissed: boolean;
  errorType: CwcErrorLogType;
  errorMessage: string;
  error: string;
  stack: string;
  data: string;
  request: string;
};

/**
 * Feature Flag
 * Runtime feature toggles and configuration
 */
export type CwcFeatureFlag = {
  featureFlagPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  featureFlagType: CwcFeatureFlagType;
  featureFlagId: string;
  valueType: CwcFeatureFlagValueType;
  value: string;
  description: string;
  platform: CwcFeatureFlagPlatform;
  serviceName: CwcFeatureFlagServiceName;
};

/**
 * Password Reset Info
 * Tracks password reset process state
 * Stores denormalized user data collected during the reset flow
 */
export type CwcPasswordResetInfo = {
  passwordResetInfoPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  username: string;
  password?: string; // Optional: not set until user provides new password
  email: string;
  emailVerificationId: string;
  emailConfirmed: boolean;
  deviceId: string;
  passwordResetAttempts: number;
};

/**
 * Project
 * User projects that contain coding sessions
 */
export type CwcProject = {
  projectPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectId: string;
  projectSessionFolder: string;
  projectType: CwcProjectType;
  userPkId: number;
};

/**
 * Reaction
 * User reactions (emoji-style) to various entities
 */
export type CwcReaction = {
  reactionPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectPkId: number;
  userPkId: number;
  entityPkId: number;
  entityType: CwcReactionEntityType;
  reactionName: CwcReactionName;
};

/**
 * Signup Info
 * Tracks signup process state
 * Stores denormalized user data collected during the signup flow
 */
export type CwcSignupInfo = {
  signupInfoPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  loginType: CwcLoginType;
  userPkId?: number; // Optional: not set until signup completes
  username: string;
  password?: string; // Optional: NULL for OAuth signups or until provided
  email: string;
  emailVerificationId: string;
  emailConfirmed: boolean;
  deviceId: string;
  signupAttempts: number;
};

/**
 * Temp JWT
 * JWT validation/revocation for temporary multi-step processes
 * Contains only JWT ID for lookup; payload contains process context
 */
export type CwcTempJwt = {
  tempJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  tempJwtId: string;
};

/**
 * User
 * Primary user accounts
 */
export type CwcUser = {
  userPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  username: string;
  loginType: CwcLoginType;
  loginDate: string;
  password?: string; // Optional: NULL for OAuth users
  email: string;
  emailConfirmed: boolean;
  deviceId: string;
  otpSecret?: string; // Optional: only present if 2FA enabled
  otpValidated: boolean;
};

/**
 * User JWT
 * JWT validation/revocation for regular users
 * Contains only JWT ID for lookup; payload contains full user context
 */
export type CwcUserJwt = {
  userJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userJwtId: string;
};

Version 2 (latest)

/**
 * CWC Database Entity Types
 *
 * This file contains TypeScript type definitions for all database entities.
 * Generated from the database schema in packages/cwc-database/schema-definition/
 *
 * Type Generation Conventions:
 * - All entity types prefixed with 'Cwc' to avoid naming conflicts
 * - Union types fully qualified with entity context to prevent ambiguity
 * - Use 'type' (not 'interface') for entity definitions
 * - Use string literal union types (not enums) for enum-like VARCHAR fields
 * - DATETIME columns mapped to string (ISO 8601 format)
 * - TINYINT columns mapped to boolean
 * - All fields required by default (even if DB allows NULL)
 * - Optional fields (?) only for business-critical reasons
 *
 * Working with Incomplete Data:
 * When working with partial entity data (e.g., during INSERT operations
 * where PkId doesn't exist yet, or multi-step processes), use TypeScript's
 * Partial<T> utility type:
 *
 * @example
 * // For INSERT operations (omit auto-generated fields)
 * type UserInsert = Omit<CwcUser, 'userPkId' | 'createdDate' | 'modifiedDate'>;
 *
 * // For partial updates
 * const partialUser: Partial<CwcUser> = { email: 'new@example.com' };
 *
 * // For specific operation requirements
 * type UserUpdate = Partial<UserInsert> & Pick<CwcUser, 'userPkId'>;
 */

// ============================================================================
// Union Types for Enum-like VARCHAR Fields
// ============================================================================

/**
 * Status values for abuse reports
 */
export type CwcAbuseReportStatus =
  | 'submitted'
  | 'investigation'
  | 'dismissed'
  | 'resolved'
  | 'retracted';

/**
 * Entity types that can be commented on
 * Note: Each entity using this type may have different allowed values
 */
export type CwcCommentEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

/**
 * Content types for coding session content blocks
 */
export type CwcCodingSessionContentType = 'prompt' | 'response' | 'note' | 'attachment';

/**
 * MIME types for coding session attachments
 */
export type CwcCodingSessionAttachmentMimeType = 'image/png' | 'image/jpg';

/**
 * Entity types that can be reported for inappropriate content
 * Note: May differ from comment entity types in the future
 */
export type CwcContentReportEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

/**
 * Status values for content reports
 */
export type CwcContentReportStatus =
  | 'submitted'
  | 'investigation'
  | 'dismissed'
  | 'resolved'
  | 'retracted';

/**
 * Error log severity/type levels
 */
export type CwcErrorLogType = 'error' | 'info' | 'warn' | 'debug';

/**
 * Service names for error logging
 */
export type CwcErrorLogServiceName =
  | 'cwc-auth'
  | 'cwc-api'
  | 'cwc-sql'
  | 'cwc-storage'
  | 'cwc-website'
  | 'cwc-admin-api';

/**
 * Feature flag type classification
 */
export type CwcFeatureFlagType = 'feature' | 'system';

/**
 * Platform targets for feature flags
 */
export type CwcFeatureFlagPlatform = 'all' | 'web' | 'android' | 'ios' | 'mobile';

/**
 * Service names for feature flag targeting
 */
export type CwcFeatureFlagServiceName =
  | 'all'
  | 'frontend'
  | 'backend'
  | 'cwc-app'
  | 'cwc-sql'
  | 'cwc-auth'
  | 'cwc-api'
  | 'cwc-admin-api'
  | 'cwc-dashboard';

/**
 * Value types for feature flag values
 */
export type CwcFeatureFlagValueType = 'boolean' | 'number' | 'string' | 'object';

/**
 * Login/authentication types
 * Shared by user and signupInfo entities
 */
export type CwcLoginType = 'cwc' | 'facebook' | 'google';

/**
 * Project type classifications
 */
export type CwcProjectType = 'web' | 'mobile' | 'backend' | 'ai';

/**
 * Reaction emoji names
 */
export type CwcReactionName = 'love' | 'funny' | 'sad' | 'wow' | 'thumbs-up';

/**
 * Entity types that can receive reactions
 * Note: May differ from comment/report entity types in the future
 */
export type CwcReactionEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

// ============================================================================
// Entity Types
// ============================================================================

/**
 * Abuse Report
 * Tracks user reports of abusive behavior or accounts
 */
export type CwcAbuseReport = {
  abuseReportPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  usernames: string;
  message: string;
  status: CwcAbuseReportStatus;
};

/**
 * Admin User
 * Administrative users for the dashboard
 */
export type CwcAdminUser = {
  adminUserPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  adminUsername: string;
  password: string;
};

/**
 * Admin User JWT
 * JWT validation/revocation for admin users
 * Contains only JWT ID for lookup; payload contains full user context
 */
export type CwcAdminUserJwt = {
  adminUserJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  adminUserJwtId: string;
};

/**
 * Coding Session
 * Individual coding sessions within a project
 * Stores metadata and reference to session data in cwc-storage
 */
export type CwcCodingSession = {
  codingSessionPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  description: string;
  published: boolean;
  sessionId: string;
  storageKey: string;
  startTimestamp: string;
  endTimestamp: string;
  gitBranch: string;
  model: string;
  messageCount: number;
  filesModifiedCount: number;
};

/**
 * Coding Session Attachment
 * Images and files attached to coding sessions
 */
export type CwcCodingSessionAttachment = {
  codingSessionAttachmentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  codingSessionPkId: number;
  filename: string;
  mimeType: CwcCodingSessionAttachmentMimeType;
  height: number;
  width: number;
};

/**
 * Coding Session Content
 * Content blocks (prompts, responses, notes, attachments) within a session
 * Uses displayIndex for rendering order of all content types
 * Polymorphic: text OR attachment based on contentType
 */
export type CwcCodingSessionContent = {
  codingSessionContentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  contentType: CwcCodingSessionContentType;
  codingSessionPkId: number;
  codingSessionAttachmentPkId?: number; // Optional: only present when contentType='attachment'
  displayIndex: number;
  text?: string; // Optional: NULL for pure attachment blocks, or optional caption for attachments
};

/**
 * Comment
 * User comments on various entities (polymorphic relationship)
 * Uses entityPkId + entityType pattern to reference any commentable entity
 */
export type CwcComment = {
  commentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectPkId: number;
  userPkId: number;
  entityPkId: number;
  entityType: CwcCommentEntityType;
  text: string;
};

/**
 * Content Report
 * User reports of inappropriate content (polymorphic relationship)
 */
export type CwcContentReport = {
  contentReportPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  entityPkId: number;
  entityType: CwcContentReportEntityType;
  message: string;
  status: CwcContentReportStatus;
};

/**
 * Email Verify
 * Email verification tracking (standalone, not tied to signup/reset)
 */
export type CwcEmailVerify = {
  emailVerifyPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  confirmationCode: string;
  email: string;
  deviceId: string;
  confirmed: boolean;
  emailVerificationId: string;
};

/**
 * Error Log
 * Centralized error logging for all microservices
 */
export type CwcErrorLog = {
  errorLogPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId?: number | undefined; // Optional: errors can occur without user context
  projectPkId?: number | undefined; // Optional: errors can occur without project context
  serviceName: CwcErrorLogServiceName;
  codeLocation: string;
  dismissed: boolean;
  errorType: CwcErrorLogType;
  errorMessage: string;
  error: string;
  stack: string;
  data: string;
  request: string;
};

/**
 * Feature Flag
 * Runtime feature toggles and configuration
 */
export type CwcFeatureFlag = {
  featureFlagPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  featureFlagType: CwcFeatureFlagType;
  featureFlagId: string;
  valueType: CwcFeatureFlagValueType;
  value: string;
  description: string;
  platform: CwcFeatureFlagPlatform;
  serviceName: CwcFeatureFlagServiceName;
};

/**
 * Password Reset Info
 * Tracks password reset process state
 * Stores denormalized user data collected during the reset flow
 */
export type CwcPasswordResetInfo = {
  passwordResetInfoPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  username: string;
  password?: string; // Optional: not set until user provides new password
  email: string;
  emailVerificationId: string;
  emailConfirmed: boolean;
  deviceId: string;
  passwordResetAttempts: number;
};

/**
 * Project
 * User projects that contain coding sessions
 */
export type CwcProject = {
  projectPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectId: string;
  projectSessionFolder: string;
  projectType: CwcProjectType;
  userPkId: number;
};

/**
 * Reaction
 * User reactions (emoji-style) to various entities
 */
export type CwcReaction = {
  reactionPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectPkId: number;
  userPkId: number;
  entityPkId: number;
  entityType: CwcReactionEntityType;
  reactionName: CwcReactionName;
};

/**
 * Signup Info
 * Tracks signup process state
 * Stores denormalized user data collected during the signup flow
 */
export type CwcSignupInfo = {
  signupInfoPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  loginType: CwcLoginType;
  userPkId?: number; // Optional: not set until signup completes
  username: string;
  password?: string; // Optional: NULL for OAuth signups or until provided
  email: string;
  emailVerificationId: string;
  emailConfirmed: boolean;
  deviceId: string;
  signupAttempts: number;
};

/**
 * Temp JWT
 * JWT validation/revocation for temporary multi-step processes
 * Contains only JWT ID for lookup; payload contains process context
 */
export type CwcTempJwt = {
  tempJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  tempJwtId: string;
};

/**
 * User
 * Primary user accounts
 */
export type CwcUser = {
  userPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  username: string;
  loginType: CwcLoginType;
  loginDate: string;
  password?: string; // Optional: NULL for OAuth users
  email: string;
  emailConfirmed: boolean;
  deviceId: string;
  otpSecret?: string; // Optional: only present if 2FA enabled
  otpValidated: boolean;
};

/**
 * User JWT
 * JWT validation/revocation for regular users
 * Contains only JWT ID for lookup; payload contains full user context
 */
export type CwcUserJwt = {
  userJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userJwtId: string;
};

Session 13: cwc storage

Session 13: cwc storage

Summary of Imported Code

What Needs to Be Done

1. Add Dependencies to package.json

2. Update BackendServiceName Type

3. Align Configuration Types

4. Logger Differences

5. Interface Alignment

Questions for You

Configuration Pattern Comparison

cwc-storage (Imported Code) Pattern

cwc-sql Pattern

Key Differences

Recommendation

Proposed Changes for cwc-storage

Summary

1. Added Config Parsing Helpers to cwc-backend-utils

2. Refactored cwc-storage Configuration

3. Updated Main Entry Point

4. Dependency Injection Throughout

5. Type Updates

6. Cleaned Up

Plan: Replace group-storage with coding-session-data-storage

Overview

Storage Structure

Files to Modify

1. packages/cwc-storage/src/apis/StorageApiV1/routes.ts

2. packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/getFromStorage.ts

3. packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/putInStorage.ts

4. packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/deleteFromStorage.ts

5. packages/cwc-storage/src/apis/StorageApiV1/utils.ts

6. packages/cwc-storage/CLAUDE.md

API After Refactoring

Implementation Steps

Notes

Plan: Replace group-storage with coding-session-data-storage

Overview

Storage Structure

Files to Modify

1. packages/cwc-storage/src/apis/StorageApiV1/routes.ts

2. packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/getFromStorage.ts

3. packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/putInStorage.ts

4. packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/deleteFromStorage.ts

5. packages/cwc-storage/src/apis/StorageApiV1/utils.ts

6. packages/cwc-storage/CLAUDE.md

API After Refactoring

Implementation Steps

Notes

Summary

Route Changes

Payload Changes

Files Modified

Storage Structure

Plan: Remove cwc-storage from CwcErrorLogServiceName

Problem

Fix

Verification

Note

Session 13: cwc storage

CLAUDE.md

CRITICAL: Role and Professional Standards

Required Due Diligence for Every Task

Cross-Package Feature Planning

Package-Specific Documentation

Project Overview

What is codingwithclaude?

Project name & aliases

Proactive Documentation Philosophy

CLAUDE.md File Specification

Documentation Organization in Monorepos

File Access Restrictions and Security Boundaries

Workspace Boundaries

Prohibited File Access

Git Workflow

Architecture Overview

Monorepo Structure (future plan)

Development Tooling & Infrastructure

Monorepo Management

Node.js Version

2. Update `BackendServiceName` Type

1. `packages/cwc-storage/src/apis/StorageApiV1/routes.ts`

2. `packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/getFromStorage.ts`

3. `packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/putInStorage.ts`

4. `packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/deleteFromStorage.ts`

5. `packages/cwc-storage/src/apis/StorageApiV1/utils.ts`

6. `packages/cwc-storage/CLAUDE.md`

1. `packages/cwc-storage/src/apis/StorageApiV1/routes.ts`

2. `packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/getFromStorage.ts`

3. `packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/putInStorage.ts`

4. `packages/cwc-storage/src/apis/StorageApiV1/storageFunctions/deleteFromStorage.ts`

5. `packages/cwc-storage/src/apis/StorageApiV1/utils.ts`

6. `packages/cwc-storage/CLAUDE.md`