quote-of-the-day-api-docs/CLAUDE.md

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:

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:

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