Context
The current Katteke marketing site is a working React application. Katteke’s engineering direction favors KISS, lean delivery, static content where possible, and raw or progressive JavaScript over a large client runtime.
Replacing the whole marketing site in one change would mix product work, visual parity, routing, accessibility, metadata, forms, consent behavior, and deployment risk. Continuing to expand React would deepen a stack Katteke has decided not to use for new product surfaces.
Decision
Use a phased migration:
- keep the existing React marketing application operational while it is the current production implementation;
- do not make React the default for new Katteke pages or LinuxMice interfaces;
- build
docs.katteke.comas an isolated Zola static site with raw CSS and minimal progressive JavaScript; - build LinuxMice web administration as Rust server-rendered HTML over stable CLI/API contracts, with vanilla JavaScript only when it materially helps;
- migrate marketing routes in bounded slices after content, behavior, accessibility, metadata, redirects, and Cloudflare deployment parity are verified; and
- remove React dependencies only when the final route has a proven replacement.
Maintenance inside the existing React site may use its current native patterns when that is the smallest safe fix. It must not create a new shared React dependency for the documentation portal or LinuxMice.
Rationale
This keeps public behavior stable while every new surface moves toward the lighter target architecture. Small reversible slices make regressions easier to identify and avoid spending a long period on an all-or-nothing rewrite.
Consequences
- React remains visible in the marketing repository during the transition; its presence is not the target architecture.
- The Zola portal and LinuxMice interfaces keep separate dependency graphs and deployment outputs.
- Every migrated route needs an explicit parity check and rollback path.
- New client-side framework dependencies require a separate recorded decision.
Review trigger
Review when a marketing route is selected for migration, when the current Cloudflare routing model changes, or when all React routes have replacements and dependency removal can be scheduled.