M. Resource & Timeline Estimate
← Back to README
Team Composition
| Role |
FTE |
Responsibilities |
| Principal Architect |
0.5 |
Architecture decisions, ADR authorship, cross-repo design, monorepo structure, code review gate |
| Full-Stack Engineer 1 |
1.0 |
reverb-backend Node upgrade, TypeScript migration, OpenAPI spec, Knex upgrades, Express 5 |
| Full-Stack Engineer 2 |
1.0 |
soreto-melissa upgrades (Next.js 13→16, React 18→19), monorepo bootstrap, @soreto/types |
| Full-Stack Engineer 3 |
1.0 |
reverb-react Next.js 16 rewrite, soreto-zoe modernization, affiliate processor testing |
Total: 4 people — 3 full-stack engineers + 1 principal architect (~3.5 FTE active)
All three engineers are full-stack: any can pick up frontend, backend, or DevOps tasks. The principal architect sets direction and unblocks — not a bottleneck. With AI assistance (Claude Code) throughout, engineers move significantly faster on scaffolding, migrations, type generation, and documentation.
Phase Timeline — AI-Assisted, 3 Engineers
Phases 3, 4, and 5 run in parallel across the three engineers after Phase 2 is complete. This is what makes 3–6 months achievable.
| Phase |
Owner(s) |
AI-Assisted |
Realistic |
| Phase 0 — Security fixes |
Any engineer |
Yes |
1–2 days |
| Phase 1 — Foundation (CI, .nvmrc, dep quick wins) |
All 3 (split) |
Yes |
2–3 weeks |
| Phase 2 — Monorepo bootstrap + melissa migration |
Eng 1 + Eng 2 |
Yes |
3–4 weeks |
| Phase 3 — Backend modernization (parallel) |
Eng 1 |
Yes |
4–6 weeks |
| Phase 4 — Zoe modernization (parallel with 3) |
Eng 3 |
Yes |
4–5 weeks |
| Phase 5 — reverb-react Next.js 16 rewrite (parallel with 3+4) |
Eng 2 + Eng 3 |
Yes |
5–8 weeks |
| Total (sequential phases + parallel tail) |
|
|
3–6 months |
Week 1 │ Phase 0 (security)
Week 2–4 │ Phase 1 (foundation — all 3 engineers split tasks)
Week 5–8 │ Phase 2 (monorepo + melissa — Eng 1 + Eng 2; Eng 3 begins zoe prep)
│
Week 9+ │ ┌─ Phase 3: backend (Eng 1) ──────────────────────┐
│ ├─ Phase 4: zoe (Eng 3) ─────────────────┐ │
│ └─ Phase 5: reverb-react rewrite (Eng 2+3)────────┘
│
Month 4–6 │ Integration, testing, gradual cut-over, decommission old Heroku apps
3 months (best case): Small reverb-react scope, seneca works on Node 24 without changes, reverb-backend has good test coverage, no cross-schema DB issues.
6 months (realistic): Average complexity across all phases, some unknowns take longer than expected (seneca, puppeteer, reverb-react route count). Product work continues in parallel without major interruptions.
Beyond 6 months: Only if seneca requires full replacement, or reverb-react has significantly more routes than estimated, or team bandwidth is reduced.
AI-Assisted Development Impact
Claude Code is used throughout as an active development tool — not just for documentation. This is built into the estimates above.
| Task type |
Without AI |
With AI |
Saving |
| Monorepo scaffold + tooling packages |
3–5 days |
3–6 hours |
-85% |
| TypeScript migration (new files + JSDoc) |
2 weeks |
3–4 days |
-70% |
| reverb-react → Next.js 16 route porting |
8–10 weeks |
4–6 weeks |
-40% |
| PrimeReact 1 → 10 component rewrite |
3–4 weeks |
1–2 weeks |
-60% |
| GitHub Actions CI setup (all repos) |
2–3 days |
3–5 hours |
-80% |
| OpenAPI spec from existing routes |
2 weeks |
3–5 days |
-65% |
| Test generation for new TypeScript code |
1–2 weeks |
2–3 days |
-75% |
| ADR and CLAUDE.md documentation |
1 week |
1–2 days |
-75% |
AI multiplier increases over time: After Phase 2, once the monorepo has @soreto/types, shared tsconfig, and per-app CLAUDE.md files, AI sessions gain full system context. Code generation accuracy and consistency improve significantly for Phases 3–5.
Timeline Variables
What speeds things up
| Variable |
Impact |
| Good reverb-backend test coverage |
Phase 3 Node upgrades go faster — automated regression detection |
| seneca compatible with Node 24 |
One less blocker in Phase 3 — no messaging layer rewrite |
| reverb-react has < 15 distinct routes |
Phase 5 rewrite scoped in 4 weeks instead of 8 |
| No cross-schema PostgreSQL queries (zoe ↔ reverb) |
Phase 4 Knex upgrade is simpler |
| Team has prior TypeScript + Next.js experience |
Less ramp-up on each migration task |
What slows things down
| Variable |
Impact |
| seneca breaks on Node 18+ |
Add 2–4 weeks to Phase 3 for messaging layer replacement |
| puppeteer 9→25 breaks affiliate processors |
Each broken processor adds 1–3 days of debugging |
| reverb-react has 20+ distinct routes |
Phase 5 rewrite pushes toward 8 weeks |
| Large production traffic on reverb-react |
Cut-over must be staged over weeks, not days |
| Competing product work pulls engineers off migration |
Each engineer split reduces effective capacity |
Biggest Unknowns (Resolve in Week 1)
| Unknown |
Impact |
How to resolve |
| reverb-backend test coverage % |
HIGH — drives Phase 3 Node upgrade risk |
Run nyc coverage report immediately |
| Is seneca compatible with Node 18+? |
HIGH — may add 2–4 weeks to Phase 3 |
Run test suite against Node 18 locally this week |
| How many routes in reverb-react? |
HIGH — drives Phase 5 scope estimate |
Count distinct routes in src/components/admin/ and src/components/client/ |
| Does zoe PostgreSQL schema cross-reference reverb schema? |
HIGH — Knex upgrade sequencing |
Query information_schema for cross-schema references |
| Current reverb-react user count |
MEDIUM — affects cut-over timing |
Check Heroku analytics / access logs |
| Is RabbitMQ actively used in production? |
MEDIUM — affects seneca decision |
Check Heroku service logs for AMQP connections |
ROI Estimate
Maintenance Overhead
| Category |
Before |
After |
Change |
| Dependency updates |
4× separate updates |
1 coordinated update |
-50 to -70% effort |
| Cross-repo bug investigation |
3–4 repo context switches |
Single session |
-60% time |
| Tooling configuration |
4 separate configs |
1 shared baseline |
-70% overhead |
| CI/CD management |
2 providers, 2 uncovered repos |
1 provider, full coverage |
-40% overhead |
Developer Experience
| Metric |
Before |
After |
Change |
| New engineer onboarding time |
Clone 4 repos, learn 4 stacks |
Clone 1 repo, 1 stack |
-50 to -60% |
| Cross-repo feature implementation |
3 PRs, 3 reviews, 3 deploys |
1 PR, 1 review, 1 deploy |
-60 to -70% |
| Type error surface |
Runtime only (across repos) |
Compile-time across system |
-80% runtime surprises |
| AI session effectiveness |
Partial context (one repo) |
Full system context |
+100% context quality |
Security Posture
| Item |
Before |
After |
| Leaked PAT |
⛔ Live exposure |
Revoked (Phase 0, Day 1) |
| Default secrets in config |
🔴 Silently active |
Validated env loading (Phase 3) |
| EOL Node versions |
3 of 4 repos |
0 of 4 repos |
| CI coverage |
50% (2 of 4 repos) |
100% |
Cost-Benefit by Phase
Each phase delivers standalone value — the migration returns ROI before it is complete:
| Phase complete |
Value delivered |
| Phase 0 |
Security incident closed; PAT revoked |
| Phase 1 |
All repos on GitHub Actions CI; no more undetected regressions |
| Phase 2 |
melissa in monorepo; @soreto/types live; AI sessions gain full context |
| Phase 3 |
reverb-backend on Node 24; TypeScript in new files; OpenAPI spec started |
| Phase 4 |
zoe on Node 24; processors typed; @soreto/api-client replaces local_modules/reverb |
| Phase 5 |
reverb-react live on Next.js 16 + Node 24; old Heroku app (Node 10) decommissioned |
Navigation