# CLAUDE.md — Quote of the Day API Docs

This repository contains the **specifications and architecture documents** for the Quote of the Day REST API. It is a documentation-only repo; the actual implementation lives elsewhere.

---

## Build Commands

There is no source code in this repository — no build, install, or compilation steps apply.

---

## Test Commands

No test suite exists in this documentation repository. Tests for the API implementation should be run via:

```bash
npm test          # run full test suite (Jest + ts-jest, or Vitest)
npm run lint      # ESLint with TypeScript-aware ruleset; must exit cleanly
```

These commands apply to the **implementation repo**, not this one.

---

## Development Commands

No dev server is applicable here. For the API implementation:

```bash
PORT=3000 npm start    # start Express server (defaults to port 3000)
```

---

## Project Structure

```
quote-of-the-day-api-docs/
├── README.md                  # Minimal project title placeholder
└── architecture/
    ├── tad.md                 # Technical Architecture Document (stack, components, NFRs, risks)
    └── working-spec.md        # Working Specification (functional requirements, actors, assumptions)
```

---

## Architecture Notes

This repo documents the architecture of a small self-contained REST API. Key decisions for implementers:

**Stack** (from `architecture/tad.md`):
- Runtime: Node.js LTS ≥ 20
- Language: TypeScript strict mode, compiled to ES2020+, output to `dist/`
- Framework: Express.js v4 or v5
- Testing: Jest + `ts-jest` or Vitest (choice left to implementer)
- Linting: ESLint with `@typescript-eslint` ruleset

**Component layout** for the implementation repo:
| File | Responsibility |
|---|---|
| `server.ts` | Entry point; creates Express app, registers middleware, listens on `process.env.PORT \|\| 3000` |
| `routes/quotes.ts` | All four REST routes: `GET /health`, `GET /quote`, `GET /quotes`, `POST /quotes` |
| `store.ts` | In-memory quote repository — `getAll()`, `getRandom()`, `add(quote)`; seeded with 5 quotes at startup |
| `validation.ts` | Pure, side-effect-free functions that validate request bodies; return typed `Quote` or error string |
| `middleware/error.ts` | Four-argument Express error handler; logs server-side, returns `{ error: "Internal server error" }` on HTTP 500 — never leaks stack traces |

**Data model**:
```
Quote { text: string, author: string }
```
No ID field in v1. In-memory store only — data resets on restart by design.

**Key design constraints** (from `architecture/working-spec.md`):
- No persistence, no database, no external integrations
- No authentication — all endpoints publicly accessible
- No pagination — `GET /quotes` returns full list
- No rate limiting
- Single process; `GET /health` is the liveness probe endpoint

---

## Code Style

Applies to the **implementation repo** (not this docs repo):

- **TypeScript**: `strict: true`, `target: "ES2020"` in `tsconfig.json`
- **Linting**: ESLint with `@typescript-eslint` rules; `npm run lint` must exit cleanly — zero warnings on committed code
- **Validation**: Input validation logic lives in `validation.ts` as pure functions, called by route handlers before any store mutation
- **Responses**: All responses use `res.json(...)` and return `application/json`
- **Error responses**: 400 errors include a human-readable `error` field; 500 errors return `{ error: "Internal server error" }` only