diff --git a/plan-for-devs.md b/plan-for-devs.md new file mode 100644 index 0000000..9e6fb75 --- /dev/null +++ b/plan-for-devs.md @@ -0,0 +1,114 @@ +Below is a **road-map of concrete tasks** that will take your three-developer team from today’s scaffold to a production-ready “AI Bulk Image Renamer” SaaS. The work is organised in phases so that each developer always has an autonomous slice to own, while touch-points (API contracts, queues, WebSockets) stay thin and testable. Citations are woven in wherever external best-practice or spec language underpins a task. + +--- + +## Phase 0 – 1 recap (done last week) + +Skeleton repo, Docker Compose, OAuth stub, queue stub, drag-and-drop, WebSocket progress, and dummy review table were delivered. +*Specification refs §18, 26-32, 73-77* + +--- + +## Phase 2 – Minimum Viable Rename (Weeks 2-4) + +### Dev A – Backend / API + +* **Harden Google OAuth flow**: add state + PKCE, token verification, refresh‐token rotation ([Google for Developers][1], [DEV Community][2]) +* **Finish REST endpoints** `/api/batch`, `/status`, `/zip`, `/keywords/enhance`, wiring them to DB via Prisma. +* **Implement atomic quota decrement** when each image job is en-queued §56-57 +* **Create cron job** using node-crond to reset quotas at UTC 00:00 monthly §58 +* **Write integration tests** (Vitest) for the above. + +### Dev B – Worker & Vision + +* **Swap dummy worker for real BullMQ worker**; configure 5-attempt exponential back-off §65 +* **Integrate ClamAV scan** for each file before Vision call ([Transloadit][3], [DEV Community][4]) (fulfils §62). +* **Call Azure AI Vision v4 tagging API** and persist tags ≥0.40 confidence §38-41 +* **Implement filename generation algorithm** satisfying §43-48, including stop-word removal and collision suffixes . +* **Stream progress via WebSocket** (`images/{id}/status`) when each step finishes §77 . + +### Dev C – Front-end / UX + +* **Keyword chip-list & “Enhance” button** with optimistic UI §33-37 . +* **Review Table** with inline-edit, regenerate-name, and shimmer placeholders §49-53, 70 . +* **Download ZIP** trigger once all rows DONE (§54-55) and show quota bar (§67). +* **Accessibility pass** (keyboard navigation, aria labels) towards Lighthouse ≥90 §59, 85 . + +--- + +## Phase 3 – Paid Plans & Quota Enforcement (Weeks 5-8) + +### Dev A + +* **Stripe Billing integration**: Checkout, customer portal, webhooks updating `plan` & `quota_remaining` ([Stripe][5], [Stripe][6]). +* **Usage-meter rows** in `payments` table; expose `/api/usage` for dashboard. +* **Automated downgrade** to Basic on cancellation (§25). + +### Dev B + +* **Batch ZIP assembly** in worker using archiver; preserve EXIF (§54-55). +* **S3-compatible storage move to MinIO production cluster** with signed URLs (spec §30 + MinIO docs) ([min.io][7]). +* **Queue metrics** to Prometheus histogram (§84). + +### Dev C + +* **Billing page & upgrade modal** (§22-24, 71). +* **Plan badge & quota reset animation** after webhook arrives via SSE. +* **Error states UI** (e.g., virus detected, vision failure). + +--- + +## Phase 4 – Production Hardening (Weeks 9-12) + +*All Devs participate; primary owner noted* + +| Owner | Task | +| ------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| **A** | **OpenTelemetry tracing + Sentry error capture** (§82-83). | +| **B** | **Load testing and queue autoscale rules**; follow BullMQ robustness guidance ([Medium][8]). | +| **C** | **Lighthouse & a11y polish** to hit 90/90 (§59, 85). | +| **A** | **Prisma `migrate deploy` pipeline** and expand-and-contract strategy ([GitHub][9], [wasp.sh][10]). | +| **B** | **Security review**: ClamAV update job, Redis auth, secrets manager (§61-63). | +| **All** | **CI/CD**: ESLint, unit + e2e, Docker multi-stage build < 300 MB (§87) ([Docker Documentation][11], [blacksmith.sh][12], [GitHub][13]). | + +--- + +## Phase 5 – Growth & Ecosystem (Quarter 2) + +* **CLI uploader & public API token auth** (Dev A). +* **LLM-powered keyword enhancement quality tuning** (Dev B). +* **Multi-language UI groundwork** (Dev C, extracting i18n JSON; spec §86). +* **Admin analytics dashboard** (collab). +* **Optional: marketplace listing & SEO content marketing** (team). + +--- + +## Cross-cutting, continuous duties + +* **Code-review rotation**: each PR must be reviewed by one dev outside its domain. +* **Weekly demo** to keep UI/APIcontracts honest. +* **Error budget & on-call**: 24 h chat response for prod issues once paying users arrive. +* **Documentation**: keep `/docs/ARCHITECTURE.md` and API schema up-to-date. + +--- + +### Why this works + +*Each developer owns a vertical slice* so they can deliver value independently and learn the adjacent stack surface. *Shared DevOps, security, and reviews* prevent silos. The plan aligns strictly with the numbered requirements in your spec §10-90 while following industry best-practices for OAuth ([Google for Developers][1], [DEV Community][2]), queues ([docs.bullmq.io][14], [Medium][8]), database migrations ([GitHub][9], [wasp.sh][10]), malware scanning ([Transloadit][3], [DEV Community][4]), computer-vision tagging ([Microsoft Learn][15], [Microsoft Learn][16]), billing ([Stripe][5], [Stripe][6]), object storage ([min.io][7]), and container builds ([Docker Documentation][11], [GitHub][13]). Follow this sequence and the team will ship a monetisable, secure, and maintainable SaaS on schedule. + +[1]: https://developers.google.com/identity/protocols/oauth2/resources/best-practices?utm_source=chatgpt.com "Best Practices | Authorization Resources" +[2]: https://dev.to/hamzakhan/mastering-oauth-20-in-modern-web-applications-security-best-practices-for-2024-26ed?utm_source=chatgpt.com "🔒 Mastering OAuth 2.0 in Modern Web Applications ..." +[3]: https://transloadit.com/devtips/implementing-server-side-malware-scanning-with-clamav-in-node-js/?utm_source=chatgpt.com "Implementing server-side malware scanning with ClamAV ..." +[4]: https://dev.to/jfbloom22/how-to-virus-scan-file-users-upload-using-clamav-2i5d?utm_source=chatgpt.com "How to virus scan file users upload using ClamAV" +[5]: https://stripe.com/in/billing?utm_source=chatgpt.com "Stripe Billing | Recurring Payments & Subscription Solutions" +[6]: https://stripe.com/billing/usage-based-billing?utm_source=chatgpt.com "Stripe Usage-Based Billing Software" +[7]: https://min.io/docs/minio/container/index.html?utm_source=chatgpt.com "MinIO Object Storage for Container" +[8]: https://medium.com/%40karthiks05/how-we-built-a-robust-message-queue-using-bullmq-part-1-2d5ad1016958?utm_source=chatgpt.com "How We Built a Robust Message Queue Using BullMQ" +[9]: https://github.com/prisma/prisma/discussions/24571?utm_source=chatgpt.com "How should migration be done to Production? #24571" +[10]: https://wasp.sh/blog/2025/04/02/an-introduction-to-database-migrations?utm_source=chatgpt.com "A Gentle Introduction to Database Migrations in Prisma ..." +[11]: https://docs.docker.com/build/building/best-practices/?utm_source=chatgpt.com "Building best practices" +[12]: https://www.blacksmith.sh/blog/understanding-multi-stage-docker-builds?ref=geeknest.ru&utm_source=chatgpt.com "Understanding Multi-Stage Docker Builds" +[13]: https://github.com/goldbergyoni/nodebestpractices?utm_source=chatgpt.com "The Node.js best practices list (July 2024)" +[14]: https://docs.bullmq.io/guide/retrying-failing-jobs?utm_source=chatgpt.com "Retrying failing jobs" +[15]: https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/whats-new?utm_source=chatgpt.com "What's new in Azure AI Vision?" +[16]: https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/concept-tag-images-40?utm_source=chatgpt.com "Content tags - Image Analysis 4.0 - Azure AI services"