docs(architecture): sync working spec + TAD from AI-SDLC (Gate 2)

architecture/working-spec.md

@@ -0,0 +1,44 @@
+# Working Spec
+
+## Overview
+
+SDLC WCNT is a small, self-contained REST API that accepts a piece of text and returns word and character counts. It is built with Node.js, Express, and TypeScript, operates entirely in memory (no persistence layer), and requires no authentication. The API is intended as a demonstration and end-to-end test target for the Introduction/Demos SDLC run.
+
+## Actors
+
+| Actor | Description |
+|---|---|
+| API Consumer | Any HTTP client (automated test suite, browser, curl, etc.) that calls the API endpoints to count words/characters or check service health. |
+
+## Functional Requirements
+
+1. **POST /count** — Accept a JSON request body `{ "text": string }` and return `{ "words": number, "characters": number }`.
+2. **Word count** — Split the `text` value on whitespace (one or more consecutive whitespace characters) to produce the word count; empty string returns 0 words.
+3. **Character count** — Count every character in `text`, including spaces, to produce the character count.
+4. **GET /health** — Return HTTP 200 with body `{ "status": "ok" }` to signal the service is running.
+5. **Input validation — missing field** — If the request body omits the `text` field entirely, respond with HTTP 400 and a descriptive error message.
+6. **Input validation — wrong type** — If the `text` field is present but is not a string, respond with HTTP 400 and a descriptive error message.
+7. **Input validation — malformed body** — If the request body is not valid JSON, respond with HTTP 400 and a descriptive error message.
+8. **Unit tests** — The word-counting and character-counting logic must be covered by unit tests that exercise the splitting-on-whitespace and space-inclusion rules respectively.
+
+## Non-Functional Requirements
+
+| ID | Category | Requirement |
+|---|---|---|
+| NFR-1 | Runtime | Node.js (LTS) with TypeScript; compiled to JavaScript for execution. |
+| NFR-2 | Framework | Express.js for HTTP routing and middleware. |
+| NFR-3 | Persistence | In-memory only — no database, no file storage. |
+| NFR-4 | Security | No authentication or authorisation required. |
+| NFR-5 | Testing | Unit test suite (e.g. Jest or Vitest) covering counting logic; tests must pass in CI. |
+| NFR-6 | Simplicity | Single-repository, minimal dependencies; runnable with a standard `npm install && npm start`. |
+| NFR-7 | Portability | No platform-specific dependencies; must run in any standard Node.js Docker image or local environment. |
+
+## Assumptions
+
+- **A1** — The API does not need to persist any data between requests; each `POST /count` call is stateless.
+- **A2** — No rate-limiting, API keys, or other access controls are required for the initial delivery.
+- **A3** — Word-count splitting uses JavaScript `String.prototype.split(/\s+/)` semantics (splits on any whitespace, collapses consecutive whitespace); leading/trailing whitespace yields no extra empty tokens when trimmed before splitting.
+- **A4** — Character count is defined as `text.length` in JavaScript (UTF-16 code units); surrogate pairs count as 2. This matches the spec's plain "includes spaces" definition and is sufficient for the demo scope.
+- **A5** — The `POST /count` endpoint accepts `Content-Type: application/json` only; other content types may be rejected by Express's JSON body-parser middleware and return an appropriate 400 error.
+- **A6** — No HTTPS termination is required at the application layer; TLS is assumed to be handled by a reverse proxy or load balancer if needed in deployment.
+- **A7** — The service runs on a configurable port (defaulting to `3000`) via an environment variable (`PORT`).