word-counter-api-docs/CLAUDE.md

word-counter-api-docs

Documentation repository for the SDLC WCNT (Word Counter) REST API — a Node.js/Express/TypeScript service that accepts text and returns word and character counts.

About this Repository

This is a docs-only repository containing the working specification and technical architecture document. There is no source code here. For the implementation, see the companion implementation repository.

Project Structure

word-counter-api-docs/
├── README.md                   # Project overview (minimal)
├── architecture/
│   ├── working-spec.md         # Functional + non-functional requirements, actors, assumptions
│   └── tad.md                  # Technical Architecture Document (stack, components, data flow)

Build Commands

This repository contains no source code. No install, build, or compile steps apply.

For the implementation project described in these docs:

npm install       # Install dependencies
npm run build     # Compile TypeScript via tsc
npm start         # Run the compiled server

Test Commands

No tests exist in this repository.

For the implementation project:

npm test                                        # Run full test suite (Jest or Vitest)
npm test -- src/__tests__/counter.test.ts       # Run a single test file
npm test -- -t "countWords"                     # Run a single named test

Development Commands

No dev server in this repository.

For the implementation project:

PORT=3000 npm start    # Start server on port 3000 (PORT env var configurable)

Architecture Notes

The target implementation is a stateless REST API with two endpoints:

• POST /count — accepts { "text": string }, returns { "words": number, "characters": number }. Word count splits on /\s+/ (trims first, filters empty tokens). Character count is text.length (UTF-16 code units, spaces included).
• GET /health — returns { "status": "ok" } with HTTP 200.

Key component layout (in the implementation repo):

File	Role
src/server.ts	Express app bootstrap, middleware registration, server listen
src/routes/count.ts	POST /count handler
src/routes/health.ts	GET /health handler
src/middleware/validateCount.ts	Validates body: JSON parsed, text present, text is string; returns 400 on failure
src/middleware/errorHandler.ts	Global four-arg error handler; catches express.json() SyntaxErrors, returns 400
src/services/counter.ts	Pure functions countWords(text) and countCharacters(text)
src/__tests__/counter.test.ts	Unit tests for counting logic

Design decisions:

• No persistence layer; all state is request-scoped.
• No authentication or rate-limiting by design (demo scope).
• PORT environment variable controls the listen port (default 3000).
• Unicode surrogate pairs count as 2 (uses text.length; see Assumption A4 in working-spec.md).
• TLS is assumed to be terminated upstream; no HTTPS at the app layer.

Stack: Node.js LTS (≥ 20.x), TypeScript (≥ 5.x), Express.js (≥ 4.x), Jest or Vitest, tsc (no bundler).

Code Style

No linting or formatting config exists in this docs repository.

For the implementation project, follow standard TypeScript/Node.js conventions:

• TypeScript strict mode expected (per TAD: tsc compilation).
• Express middleware follows the four-argument (err, req, res, next) signature for error handlers.
• Pure functions in the counting service — no side effects, no I/O.
• Test file convention: src/__tests__/*.test.ts.