Roadmap to v2

[arzafran]

Roadmap to Satus v2

Reduce cognitive load, accelerate onboarding, simplify maintenance — for darkroom and client teams alike.

Why

Satus is powerful but heavy. At ~33K LOC with 46 dependencies, it covers CMS, e-commerce, WebGL, animations, design tokens, and dev tools. Most projects use a fraction of this. The cost: cognitive load for new developers, maintenance overhead for the team, and dead weight for clients.

Goals

1. Lighter starts — New projects should only contain what they need. No stripping integrations via regex surgery.
2. Faster onboarding — A mid-level React developer should be productive in hours, not days. The CSS system, TypeScript config, and project conventions should be self-explanatory.
3. Easier handoffs — Client teams receiving a Satus-based codebase should find it approachable, not intimidating. Fewer files, clearer boundaries, less tribal knowledge required.
4. Lower maintenance — Fewer custom scripts, less documentation drift, fewer fragile build steps. The codebase should be easy to upgrade when Next.js, Tailwind, or React ship new majors.
5. Consistent quality — Eliminate inconsistencies (duplicate hooks, dead utilities, conflicting patterns) that erode trust in the codebase.

---

Phase 1: Reduce — Cut Weight and Confusion

#	Issue	Effort	Impact
1.1	#96 — Extract integrations into separate packages	High	Highest — removes 63 files from base, eliminates fragile regex transforms
1.2	#97 — Extract WebGL into @satus/webgl	Medium	Removes 27 files + 5 production deps from base starter
1.3	#98 — Unify documentation systems	Medium	Cuts ~2,200 lines of duplicate docs, prevents drift
1.4	#99 — Clean up codebase inconsistencies	Low	✅ Done — d5ff606
1.5	#100 — Add .nvmrc for Node 22	Trivial	✅ Done — b732a88

Phase 2: Simplify — Flatten Learning Curves

#	Issue	Effort	Impact
2.1	#101 — CSS system onboarding guide	Low	Onboarding from 1-2 days → 2-3 hours
2.2	#102 — Evaluate relaxing exactOptionalPropertyTypes	Trivial	-30 min per feature for unfamiliar developers
2.3	#103 — Auto-clean marketing homepage in setup:project	Low	-15 min per new project
2.4	#104 — Consolidate path aliases	Trivial	✅ Done — b732a88
2.5	#105 — Split Shopify index.ts monolith	Low	500 LOC file → 5 focused files
2.6	#106 — Simplify .env.example	Low	127 lines → 15 lines for base template

Phase 3: Harden — Long-term Maintainability

#	Issue	Effort	Impact
3.1	#107 — Replace regex code transforms with AST transforms	High	Eliminates most fragile maintenance burden
3.2	#108 — Add rate-limit tests and document Vercel limitation	Low	Prevents false security assumptions
3.3	#109 — Simplify prepare-handoff.ts	Medium	-500 lines of script to maintain
3.4	#110 — Stabilize Lighthouse CI workflow	Low	Prevent silent CI breakage
3.5	#111 — Publish stable hamo and tempus releases	Medium	Enables automated dependency management

---

The Big Architecture Decision

The single highest-impact change is extracting integrations and WebGL into packages (#96 + #97). This decision unlocks the most simplification and determines whether #107 (AST transforms) is even needed.

Approach	Pros	Cons
Current monolith	One repo, simple mental model	63 integration files always present, fragile regex removal
Monorepo (@satus/*)	Projects start lean, add what they need	Turborepo infra, publish pipeline
Separate repos	Cleanest separation	Coordination overhead

Recommendation: Monorepo with Turborepo.

---

Execution Notes

• Phase 1 is the structural foundation — [v2] Extract integrations into separate packages #96 is the critical decision
• Phase 2 items are all independent quick wins — can start immediately
• Phase 3 depends partly on Phase 1 decisions (if monorepo happens, [v2] Replace regex code transforms with AST transforms #107 is unnecessary)
• Phases can run in parallel where items don't depend on each other