0c45aeff1b
Documents the architecture, stack decisions, component layout, and code style guidelines for the Quote of the Day API implementation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
92 lines
3.4 KiB
Markdown
92 lines
3.4 KiB
Markdown
# 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
|