# Listify API Roadmap

This roadmap captures the next practical milestones for the Listify API. The project is currently a NestJS service with registration, email verification, login, refresh-token rotation, a JWT guard, event-based mail handling, Helmet, and focused auth tests. Runtime state is still in memory, mail delivery is logged/stubbed, and the README is still the default NestJS starter text.

## Guiding Goals

- Build a reliable API for user accounts and list management.
- Move from prototype in-memory state to durable, observable production services.
- Keep security and test coverage ahead of user-facing feature expansion.
- Document setup, environment variables, and release workflows clearly enough for repeatable development.

## Phase 1: Foundation Hardening

- Replace in-memory user and refresh-token maps with a database-backed persistence layer.
- Choose and configure the data stack, including migrations, local development setup, and test database strategy.
- Move configuration into a typed config module with explicit validation for JWT secrets, token lifetimes, base URLs, mail settings, and port.
- Replace the hard-coded verification URL with environment-aware URL generation.
- Add validation pipes globally so DTO validation is enforced consistently at API boundaries.
- Add CORS policy configuration for the intended frontend origins.
- Update the README with real Listify setup, scripts, environment variables, and testing instructions.

## Phase 2: Authentication And Account Management

- Persist users, email verification tokens, refresh tokens, and token revocation metadata.
- Add logout and logout-all-devices endpoints.
- Add password reset request and password reset confirmation flows.
- Add resend verification email support with rate limiting.
- Strengthen password policy and add account lockout or throttling for repeated login failures.
- Add authenticated profile endpoints for viewing and updating basic account details.
- Add tests for persistence behavior, token expiry paths, logout, reset flows, and guard-protected routes.

## Phase 3: Listify Product API

- Define the core domain model for lists, list items, ownership, ordering, completion state, and timestamps.
- Add CRUD endpoints for lists and list items.
- Enforce authorization so users can only access their own lists unless explicit sharing is introduced.
- Support item reordering, bulk completion, archive/delete flows, and basic filtering.
- Add pagination and query limits where list or item collections can grow.
- Add OpenAPI documentation for auth and list endpoints.
- Expand e2e coverage across the main account and list workflows.

## Phase 4: Mail And Event Reliability

- Replace the stub mail service with a real provider integration behind the existing mail service boundary.
- Add HTML/text templates for verification and password reset emails.
- Add provider error handling, retries, and structured logging for mail delivery failures.
- Persist outbound email intent or event processing state if reliable delivery becomes required.
- Add tests around event listeners and mail provider adapters.

## Phase 5: Platform Readiness

- Add structured request logging with correlation IDs.
- Add health and readiness endpoints for deployment checks.
- Add rate limiting for auth and high-volume endpoints.
- Add CI for linting, tests, coverage, and build verification.
- Add Docker or equivalent deployment packaging if the target runtime needs it.
- Add production environment documentation, secret management guidance, and rollback notes.
- Add dependency update and security audit routines.

## Phase 6: Collaboration And Sharing

- Introduce list sharing or team/workspace concepts if required by the product direction.
- Add invitation flows, roles, and permissions for shared lists.
- Add audit-friendly activity events for important list and account changes.
- Consider real-time list updates once the core REST API is stable.

## Open Decisions

- Database choice and migration tooling.
- Mail provider and whether delivery must be durable/retryable.
- Frontend base URL and allowed production origins.
- API versioning strategy.
- Whether shared lists are part of the initial product scope or a later collaboration feature.

## Suggested Immediate Next Steps

1. Select the database and migration approach.
2. Add a typed configuration module and global validation pipe.
3. Replace the default NestJS README with project-specific documentation.
4. Implement persistent auth storage before expanding the list domain.