{ "schemaVersion": "1.1", "id": "spec-todo-api", "projectId": "proj-todo", "title": "Todo API", "description": "A small REST API for creating, listing, completing, and deleting todo items.", "status": "planning", "background": "Teams need a minimal, dependency-light service to track todo items behind a stable HTTP contract.", "goals": [ { "id": "goal-crud", "title": "Offer full todo lifecycle", "description": "Support creating, listing, completing, and deleting todo items over HTTP.", "type": "user", "successCriteria": [ "A todo can be created, completed, and deleted via the API", "Listing returns todos in a stable order" ] }, { "id": "goal-durable", "title": "Persist todos durably", "description": "Store todos in a relational database so they survive restarts.", "type": "technical", "successCriteria": [ "No todo is lost across a service restart" ] }, { "id": "goal-contract", "title": "Maintain a versioned contract", "description": "Expose a documented, backward-compatible REST contract.", "type": "business", "successCriteria": [ "Breaking changes are gated behind a new API version" ] } ], "requirements": [ { "id": "req-create", "title": "Create a todo", "description": "Clients can create a todo with a title and optional notes.", "type": "functional", "acceptanceCriteria": [ { "id": "ac-create", "given": "a valid todo payload", "when": "the client POSTs to /todos", "then": "the todo is persisted and returned with a generated id and createdAt", "order": 1 } ] }, { "id": "req-complete", "title": "Complete a todo", "description": "Clients can mark an existing todo as completed.", "type": "functional", "acceptanceCriteria": [ { "id": "ac-complete", "given": "an existing open todo", "when": "the client PATCHes /todos/{id} with completed=true", "then": "the todo is marked completed and the updated record is returned", "order": 1 } ] }, { "id": "req-validate", "title": "Validate input", "description": "Reject malformed payloads with a descriptive error.", "type": "business-rule", "acceptanceCriteria": [ { "id": "ac-validate", "given": "a todo payload without a title", "when": "the client POSTs to /todos", "then": "the request fails with a 400 and a field-level error", "order": 1 } ] } ], "architecture": "A stateless Node.js HTTP service exposing a REST API, backed by PostgreSQL for persistence. Requests are validated at the edge before reaching the data layer.", "scope": { "inScope": [ "Todo create, list, complete, and delete", "Request payload validation", "Relational persistence" ], "outOfScope": [ "Authentication and authorization", "Real-time updates" ], "assumptions": [ "A single PostgreSQL instance is available" ], "externalDependencies": [ "PostgreSQL 15+" ] }, "techStack": [ { "id": "tech-node", "name": "Node.js", "version": "20", "layer": "backend", "rationale": "Lightweight, ubiquitous runtime for small HTTP services." }, { "id": "tech-postgres", "name": "PostgreSQL", "version": "15", "layer": "database", "rationale": "Durable relational store with strong consistency guarantees." } ], "folderStructures": [ { "id": "fs-service", "scope": "service", "description": "Top-level layout of the HTTP service.", "content": "src/\n routes/todos.ts\n db/todos.ts\n validation/todo.ts\n server.ts" } ], "acceptanceCriteria": [ { "id": "spec-ac-1", "given": "the service is running", "when": "a client exercises the documented endpoints", "then": "each endpoint behaves per its requirement's acceptance criteria", "order": 1 } ], "nonFunctionalRequirements": [ { "id": "nfr-latency", "description": "Read endpoints respond quickly under nominal load.", "category": "performance", "metric": "p95 latency for GET /todos", "target": "< 100ms at 50 rps", "measurementMethod": "Load test with k6 against a staging instance" } ], "guardrails": [ { "id": "gr-no-pii", "description": "Todo content must not be used to store secrets or personal data.", "category": "regulatory", "rationale": "The service has no encryption-at-rest or access controls.", "consequence": "Storing sensitive data would create an uncontrolled data-exposure risk.", "scope": "spec" } ], "epics": [ { "id": "ep-core", "specificationId": "spec-todo-api", "title": "Core todo endpoints", "description": "Implement the create, list, complete, and delete endpoints with persistence.", "objective": "Deliver a working todo CRUD API backed by PostgreSQL.", "order": 0, "category": "functional", "tickets": [ { "id": "tkt-create", "epicId": "ep-core", "ticketNumber": 1, "title": "Implement POST /todos", "description": "Add the create-todo route with validation and persistence.", "ticketType": "implementation", "complexity": "medium", "estimatedMinutes": 90, "order": 0, "acceptanceCriteria": [ { "id": "ac-tkt-create", "given": "a valid payload", "when": "POST /todos is called", "then": "a 201 is returned with the persisted todo", "order": 1 } ], "implementationSteps": [ { "id": "step-1", "text": "Define the todo validation schema", "order": 1 }, { "id": "step-2", "text": "Add the POST /todos route handler", "order": 2 }, { "id": "step-3", "text": "Insert the todo via the data layer", "order": 3 } ], "filesToBeCreated": [ "src/routes/todos.ts", "src/validation/todo.ts" ], "filesToBeModified": [ "src/server.ts" ], "filesToBeDeleted": [], "filesToBeReferenced": [ "src/db/todos.ts" ], "testSpecification": { "testTypes": [ "unit", "integration" ], "qualityGates": [ "All new code paths covered by tests" ], "testCommands": [ "npm test" ], "coverageTarget": 80 }, "guardrails": [ "Reject payloads larger than 8KB" ], "codeReferences": [ { "filePath": "src/db/todos.ts", "symbol": "insertTodo", "description": "Existing insert helper to reuse" } ], "typeReferences": [ { "filePath": "src/types/todo.ts", "typeName": "Todo", "description": "Shared todo type" } ], "blueprintReferences": [ { "blueprintId": "bp-todo-flow", "context": "Create path" } ], "dependencies": [] }, { "id": "tkt-list", "epicId": "ep-core", "ticketNumber": 2, "title": "Implement GET /todos", "description": "Add the list-todos route returning todos in creation order.", "ticketType": "implementation", "complexity": "small", "estimatedMinutes": 45, "order": 1, "acceptanceCriteria": [ { "id": "ac-tkt-list", "given": "stored todos exist", "when": "GET /todos is called", "then": "a 200 is returned with todos in creation order", "order": 1 } ], "implementationSteps": [ { "id": "step-1", "text": "Add the GET /todos route handler", "order": 1 }, { "id": "step-2", "text": "Query todos ordered by createdAt", "order": 2 } ], "filesToBeCreated": [], "filesToBeModified": [ "src/routes/todos.ts" ], "filesToBeDeleted": [], "filesToBeReferenced": [ "src/db/todos.ts" ], "testSpecification": { "testTypes": [ "unit", "integration" ], "qualityGates": [ "List ordering verified by a test" ], "testCommands": [ "npm test" ], "coverageTarget": 80 }, "guardrails": [], "codeReferences": [ { "filePath": "src/db/todos.ts", "symbol": "listTodos" } ], "typeReferences": [ { "filePath": "src/types/todo.ts", "typeName": "Todo" } ], "blueprintReferences": [], "dependencies": [ { "ticketId": "tkt-create", "type": "requires" } ] } ] } ], "blueprints": [ { "id": "bp-todo-flow", "title": "Todo request flow", "description": "Sequence of a create-todo request from route to database.", "category": "sequence", "format": "mermaid", "coverageType": "all", "content": "sequenceDiagram\n Client->>API: POST /todos\n API->>DB: insertTodo()\n DB-->>API: row\n API-->>Client: 201 Created", "order": 0 } ] }