# 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`.