From 0009bd0efe33053954e1b71ac7f0d486ed8dfff2 Mon Sep 17 00:00:00 2001
From: ai-implementer <ai-implementer@gitea-ai-sdlc.scopicdev.com>
Date: Tue, 21 Jul 2026 10:12:48 +0000
Subject: [PATCH] [WCTAS-2] Add CLAUDE.md with project documentation

Document build/test/dev commands, project structure, architecture notes,
and code style for the word-counter-api-docs repository.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3b188ff
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,86 @@
+# 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:
+```bash
+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:
+```bash
+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:
+```bash
+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`.