Imported from chlamaq/todo-list (AGENTS.md). Install upstream with npx skills add chlamaq/todo-list. Copyright stays with the author.

Project

SleekFlow TODO List

A working interview project that demonstrates a shared TODO list through a React web interface and a NestJS REST API. Users can create, edit, soft-delete, filter, sort, and progress TODOs while the system correctly handles dependencies, recurring schedules, concurrent edits, and lists of at least 10,000 items.

Core Value: Users can reliably manage interrelated and recurring TODOs without losing work or creating duplicate occurrences under concurrent access.

Constraints

Technology: React frontend, NestJS backend, TypeORM, and PostgreSQL/RDS - selected for relational dependencies, sorting, transactions, and optimistic concurrency.
Concurrency: Every aggregate mutation carries an expected version; stale writes return HTTP 409 and do not overwrite current data.
Recurring transaction: Completing an occurrence and inserting its successor happen in one TypeORM transaction. PostgreSQL rollback handles either-step failure.
Idempotency: Recurring completion accepts an idempotency key and enforces a database uniqueness constraint so retries and concurrent requests return one logical result.
Dependency integrity: Self-dependencies and cycles are rejected. A blocked TODO remains Not Started and cannot enter In Progress.
Recurrence semantics: The series anchor is the first due date. Late completion skips missed cycles and creates only the next due date strictly after completion time.
Custom recurrence: Hourly, daily, weekly selected weekdays, and monthly day-of-month rules are supported; the minimum interval is one hour.
Scale: List endpoints are paginated and database-filtered/sorted; the client never loads all 10,000 records at once.
Delivery: Core features and meaningful tests take priority over optional authentication, real-time updates, and bulk operations.

Technology Stack

Recommendation

Runtime and Tooling

Technology	Version	Purpose	Why
Node.js	`24.18.0` LTS	Runtime for frontend tooling and Nest API	Current LTS as of 2026-07-11; supported by Vite 8, Vitest 4, and Nest 11.
npm	Bundled with Node 24	Package manager and workspaces	Native workspaces are enough for `apps/web`, `apps/api`, and optional `packages/shared`; pnpm/Turborepo would add interview overhead.
TypeScript	`7.0.2`	Shared language	Keeps DTOs, API client types, React state, and Nest services strongly typed.
ESLint	`10.7.0`	Linting	Use flat config and TypeScript ESLint for both apps.
Prettier	`3.9.5`	Formatting	Removes style churn from interview review.
Docker Compose	Current Docker Desktop / Compose plugin	Local services	Runs PostgreSQL with the same class of database behavior as RDS.

Repository Layout

Frontend Stack

Technology	Version	Purpose	Why
React	`19.2.7`	UI framework	Locked choice; current official React line.
React DOM	`19.2.7`	Browser rendering	Pair with React version.
Vite	`8.1.4`	Static frontend build/dev server	Official Vite docs support `react-ts` templates, fast dev server, and optimized static production assets.
`@vitejs/plugin-react`	`6.0.3`	React transform plugin	Official React plugin for Vite.
React Router	`8.2.0`	Client routing	Useful even for a one-page app to keep filter/query state routable; avoid framework routing.
TanStack Query	`5.101.2`	Server-state cache	Handles list refetch, mutation invalidation, stale conflict recovery, and loading/error states without custom cache code.
TanStack Table	`8.21.3`	Dense list table model	Gives sorting/filtering/table state ergonomics while still delegating real filtering/sorting/pagination to the server.
React Hook Form	`7.81.0`	Forms	Lightweight create/edit/recurrence forms with good controlled-input ergonomics.
Zod	`4.4.3`	Client-side schema validation	Mirror API validation intent for form errors; keep server as authority.
date-fns	`4.4.0`	Date calculations/formatting	Small focused date utilities for due-date display; recurrence generation remains backend-owned.
lucide-react	`1.24.0`	Icons	Simple, tree-shakeable icon set for compact controls.

Backend Stack

Technology	Version	Purpose	Why
NestJS core/common/platform-express	`11.1.28`	REST API framework	Locked choice; modular monolith maps cleanly to TODO, dependency, and recurrence modules.
`@nestjs/cli`	`11.0.24`	Project generation/build scripts	Standard Nest project tooling.
`@nestjs/config`	`4.0.4`	Environment config	Official Nest configuration module; use typed config factories and validation.
`@nestjs/typeorm`	`11.0.3`	Nest-TypeORM integration	Current Nest adapter; peer range drives the TypeORM `0.3.x` recommendation.
TypeORM	`0.3.30`	ORM and migrations	Latest compatible `0.3.x`; supports DataSource, migrations, transactions, soft delete columns, version columns, and query builder.
pg	`8.22.0`	PostgreSQL driver	Official TypeORM PostgreSQL path.
`@nestjs/swagger`	`11.4.5`	Swagger/OpenAPI docs	Required by project; generate docs from controllers/DTOs.
class-validator	`0.15.1`	DTO validation	Official Nest ValidationPipe integration.
class-transformer	`0.5.1`	DTO transformation	Required with Nest validation.
reflect-metadata	`0.2.2`	Decorator metadata	Required by Nest/TypeORM decorator patterns.
rxjs	`7.8.2`	Nest dependency	Peer dependency for Nest.
Module	Owns	Notes
--------	------	-------
`TodoItemsModule`	CRUD, soft delete, list queries, lifecycle transitions, aggregate orchestration	Keep server-driven pagination/filter/sort here.
`TodoDependenciesModule`	Dependency edges, cycle checks, blocked-state derivation	Use database constraints plus service-level graph validation.
`RecurringTasksModule`	Recurrence validation and next occurrence generation	Completing an occurrence and inserting the successor must share one DB transaction.
`DatabaseModule`	TypeORM DataSource, migrations, transaction helper	Expose transaction utilities to avoid global manager usage inside transactions.

Database

Technology	Version	Purpose	Why
PostgreSQL	`18.4` locally via `postgres:18.4-alpine`	Relational persistence	Current supported PostgreSQL release; mirrors RDS-style relational behavior for constraints, transactions, indexes, and pagination.
AWS RDS PostgreSQL	PostgreSQL 18 if available in target region, otherwise latest RDS-supported major	Production target	Keep engine behavior aligned with local Docker PostgreSQL; do not substitute SQLite for tests.
Practice	Prescription
----------	--------------
Schema changes	Use TypeORM migrations. Set `synchronize: false` in every non-throwaway environment.
IDs	Use UUID primary keys for TODOs and recurrence series.
Soft delete	Use `@DeleteDateColumn` and TypeORM soft-delete APIs; ensure list queries exclude deleted rows by default.
Versioning	Add an integer `version` column with `@VersionColumn`, but do not rely on it alone for conflict-safe updates.
Conflict-safe writes	Use conditional updates: `WHERE id = :id AND version = :expectedVersion AND deleted_at IS NULL`, increment version in the same statement, and treat `affected === 0` as HTTP `409 Conflict` after refetching current state.
Recurring completion idempotency	Store idempotency keys in a table or nullable unique column scoped to occurrence completion; enforce a unique constraint so retries return one logical result.
Dependencies	Model as `todo_dependencies(todo_id, depends_on_id)` with a composite primary key, foreign keys, self-dependency check, and service-level cycle detection.
Pagination	Use deterministic `ORDER BY` with a stable tie-breaker (`id`) and indexed filter columns. Offset pagination is acceptable for 10,000 items; cursor pagination can be deferred.
Indexes	Add composite indexes for common list queries: `(deleted_at, status, priority, due_date, id)`, plus dependency lookups on both edge directions.

TypeORM Optimistic Lock Warning

Local Development Setup

Testing Stack

Layer	Tooling	Version	What to Cover
Frontend unit/component	Vitest `4.1.10`, React Testing Library `16.3.2`, Testing Library DOM peer, user-event `14.6.1`, jest-dom `6.9.1`, jsdom `29.1.1`	Current	Form validation, table controls, blocked-state display, `409` conflict UI.
Backend unit	Jest `30.4.2`, `@nestjs/testing` from Nest `11.1.28`	Current	Service rules: lifecycle guards, recurrence next-date calculation, dependency cycle detection.
Backend HTTP e2e	Jest + Supertest `7.2.2`	Current	REST contract, validation errors, Swagger-exposed routes, soft delete behavior.
DB integration	Testcontainers `12.0.4` with PostgreSQL module, or Docker Compose in CI	Current	Migrations, constraints, transactions, idempotency, version conflicts, dependency indexes.
Browser UAT	Playwright `1.61.1`	Current	Create/edit/delete, filter/sort/page, blocked dependency flow, stale-write recovery.

Installation

Alternatives Rejected

Category	Recommended	Alternative	Why Not
Frontend framework	Vite React static app	Next.js	React docs recommend frameworks generally, but the project explicitly wants a static React frontend and separate Nest backend; Next adds routing/server concepts not needed for the interview.
ORM	TypeORM `0.3.30`	TypeORM `1.0.0`	Latest tag exists, but Nest adapter peer range does not yet support stable 1.x.
ORM replacement	TypeORM	Prisma	Locked choice; TypeORM exposes the transaction/version/migration behavior the brief wants to demonstrate.
API shape	REST + OpenAPI	GraphQL	CRUD/filter/sort/pagination map cleanly to REST; Swagger/OpenAPI is explicitly required.
Local DB	Docker PostgreSQL 18	SQLite/in-memory	Would hide PostgreSQL constraints, transaction isolation, indexes, and TypeORM driver behavior.
Real-time updates	Explicit refresh/conflict recovery	WebSockets/SSE	Out of scope; version conflicts are sufficient for MVP concurrency.
Test DB	Testcontainers/PostgreSQL	Mocked repositories only	Repository mocks cannot verify migrations, constraints, idempotency, or concurrent writes.

Roadmap Implications

Sources

React docs, current React version and app setup guidance: https://react.dev/learn/creating-a-react-app
Vite docs, v8.1.4, scaffolding, Node engine, static build behavior: https://vite.dev/guide/
Node.js release schedule, Node 24 LTS status: https://nodejs.org/en/about/previous-releases
npm workspaces documentation: https://docs.npmjs.com/cli/v11/using-npm/workspaces/
NestJS validation docs: https://docs.nestjs.com/techniques/validation
NestJS configuration docs: https://docs.nestjs.com/techniques/configuration
NestJS OpenAPI docs: https://docs.nestjs.com/openapi/introduction
NestJS testing docs: https://docs.nestjs.com/fundamentals/testing
TypeORM docs, migrations warning against synchronize: true with production data: https://typeorm.io/docs/migrations/why/
TypeORM docs, transactions and transactional entity manager rule: https://typeorm.io/docs/transactions/
TypeORM docs, @DeleteDateColumn and @VersionColumn: https://typeorm.io/docs/help/decorator-reference/
TypeORM docs, pagination and lock modes: https://typeorm.io/docs/query-builder/select-query-builder/
TypeORM GitHub issue documenting optimistic lock not protecting update query builders: https://github.com/typeorm/typeorm/issues/2848
PostgreSQL 18.4 documentation: https://www.postgresql.org/docs/current/index.html
Docker official PostgreSQL image tags and Compose example: https://hub.docker.com/_/postgres
Vitest docs: https://vitest.dev/guide/
React Testing Library docs: https://testing-library.com/docs/react-testing-library/intro/
Testcontainers for Node.js docs: https://node.testcontainers.org/
Playwright docs: https://playwright.dev/docs/intro
npm package versions checked with npm view on 2026-07-11.

Conventions

Conventions not yet established. Will populate as patterns emerge during development.

Architecture

Architecture not yet mapped. Follow existing patterns found in the codebase.

Project Skills

No project skills found. Add skills to any of: .claude/skills/, .agents/skills/, .cursor/skills/, .github/skills/, or .codex/skills/ with a SKILL.md index file.

GSD Workflow Enforcement

Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.

Use these entry points:

/gsd-quick for small fixes, doc updates, and ad-hoc tasks
/gsd-debug for investigation and bug fixing
/gsd-execute-phase for planned phase work

Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.

Developer Profile

Profile not yet configured. Run /gsd-profile-user to generate your developer profile. This section is managed by generate-claude-profile -- do not edit manually.

todo-list

About