Ekehi platform has moved from hand-written HTML/CSS/JS pages to a typed, component-driven React 19 client and a module-based TypeScript Express/Node.js API.

0. Where we started and where we landed

Before. A static client built from per-page folders (landing/,
contributors/, login/, signup/, admin/), each shipping its own
index.html, a shared styles.css, and vanilla ES module scripts under
client/shared/. The server was an Express API written in plain JavaScript.

After.

The migration ran in two phases on separate branches:

• **Phase 1 — client rewrite.
• **Phase 2 — server rewrite.

1. Why this framework?

Choice: React 19, rendered as a client-side SPA through Vite 8, routed by TanStack Router.

TanStack Router was chosen rather than React Router because it
gives fully type-safe routes, first-class search-param typing, built-in code-splitting, and file-based route generation that pairs cleanly with Vite.

2. The folder and component structure

The client uses a feature-sliced layout: code is grouped by domain, not by
technical type.

client/src/
├── components/
│   ├── layout/         navbar.tsx, footer.tsx
│   └── ui/             button, input, modal, select, dropdown, ... (design system)
├── config/             env.ts, env-schema.ts, endpoints.ts
├── features/           one folder per domain
│   ├── auth/           auth.query.ts, auth.service.ts, auth.types.ts, components/, pages/
│   ├── opportunities/  pages/
│   ├── resources/      pages/
│   ├── submissions/    pages/
│   ├── admin/          pages/
│   └── site/           pages/ (landing, contributors)
├── lib/
│   ├── api/            request.ts, errors.ts, refresh.ts, types.ts  (HTTP client)
│   ├── auth/           token-store.ts
│   ├── query-client.ts
│   └── utils.ts
├── routes/             TanStack file-based route tree
├── router.tsx
├── routeTree.gen.ts    generated, do not edit
└── styles.css          Tailwind import + @theme tokens

The principle: a route file in routes/ is thin glue that points at a page component in the matching features/<domain>/pages/ folder. Domain logic (queries, services, types) lives next to the feature that owns it, so a single Claude or dev session can work one feature without touching another.

Imports use the #/* alias (defined in both package.json#imports and tsconfig.json#paths) so there are no ../../../ chains:

import { env } from '#/config/env'
import { getAccessToken } from '#/lib/auth/token-store'

3. Decompose the UI into reusable components

The old per-page markup was factored into a small design-system layer under components/ui/: button, input, password-input, textarea, select, checkbox, label, form-field, dropdown, modal, search-bar, skeleton.

Technique and libraries:

• Radix UI primitives (@radix-ui/react-dialog, react-dropdown-menu, react-slot) supply accessible, unstyled behaviour (focus traps, keyboard nav, ARIA). The team styles them rather than reimplementing accessibility.
• class-variance-authority (CVA) defines component variants (size, intent) as typed config instead of ad-hoc conditional class strings.
• clsx + tailwind-merge (wrapped in lib/utils.ts) merge class names and resolve Tailwind conflicts deterministically.
• lucide-react provides the icon set as tree-shakeable components.

Layout components (navbar, footer) live separately under
components/layout/ because they are app chrome, not reusable primitives.

4. Migrate static HTML sections into JSX

Each former page folder became a route + page component pair. The old
landing/index.html is now features/site/pages/landing-page.tsx mounted at
routes/(layout)/index.tsx; contributors/, login/, signup/, the admin screens, and the resource/opportunity pages followed the same move.

Shared chrome that used to be copy-pasted into every index.html now lives once:

• routes/__root.tsx is the application shell.
• routes/(layout)/route.tsx wraps every public page in the shared navbar/footer layout, so markup is defined a single time and inherited.

The vanilla client folders (client/shared/, client/landing/,
client/contributors/, etc.) and the root index.html/styles.css were deleted in the same release (see CHANGELOG.md [2.0.0] → Removed).

5. Migrate CSS with the framework's recommended approach

Styling moved to Tailwind CSS 4, installed as a Vite plugin
(@tailwindcss/vite) rather than a PostCSS pipeline — the v4 recommended path.

The single global stylesheet was replaced by a token-driven theme declared
with the new @theme directive in client/src/styles.css:

@import 'tailwindcss';

@theme {
  --color-purple-700: #730099;
  --color-primary: var(--color-purple-700);
  --color-surface: #ffffff;
  --color-surface-subtle: var(--color-neutral-50);
  /* ... */
}

Two deliberate techniques:

• Role-based token names. Raw scales (purple-700, neutral-50) are mapped to semantic roles (primary, surface, content, line) so components reference intent, not hex values. See refactor(client): rename color tokens to role-based names (surface/content/line).
• Deterministic class ordering. prettier-plugin-tailwindcss sorts utility classes on every format pass, so class lists never drift between authors.

Fonts are self-hosted via @fontsource-variable/inter and
@fontsource-variable/lora, and fontaine generates metric-matched fallback @font-face rules to eliminate layout shift on font swap.

6. Replace vanilla JS logic with framework equivalents

The biggest behavioural shift. Imperative fetch + DOM updates became declarative server-state managed by TanStack Query on top of a typed HTTP client.

The HTTP client (lib/api/request.ts). A makeRequest factory builds typed callers and centralises everything that used to be repeated per page:

• attaches the bearer token from lib/auth/token-store,
• serialises GET params vs JSON/FormData bodies,
• unwraps the server's { success, data, meta } envelope,
• and — critically — on a 401 it transparently calls refreshSession() and retries the original request once (skipping /auth/* routes to avoid loops):

if (response.status === 401 && !isRetry && !route.startsWith(AUTH_PATH_PREFIX)) {
  const refreshed = await refreshSession()
  if (refreshed) return executeRequest(route, method, options, true)
}

Server state via TanStack Query. Features expose typed hooks instead of inline fetch calls. Auth (features/auth/auth.query.ts) is representative:

export function useLoginMutation() {
  const queryClient = useQueryClient()
  return useMutation<LoginResponse, Error, LoginRequest>({
    mutationFn: (data) => AuthService.login({ data }).then((r) => r.data),
    onSuccess: (response) => {
      setTokens({ access_token: response.access_token,
                  refresh_token: response.refresh_token })
      queryClient.invalidateQueries({ queryKey: authKeys.me() })
    },
  })
}

Query keys are namespaced (authKeys), caching/invalidation is handled by the library, and useLogoutMutation clears the cache on settle. The shared client config lives in lib/query-client.ts.

Forms use React 19's useActionState. Login and signup wire the form action straight to the mutation, getting pending/error state from the framework with no manual loading flags.

Validation is shared end to end with Zod 4 — the same library validates client env, form input, and server request bodies.

7. Set up client-side routing

Routing is file-based through TanStack Router with autoCodeSplitting enabled in vite.config.ts, so every route is its own lazy chunk. The route tree under client/src/routes/ uses TanStack's grouping conventions:

routes/
├── __root.tsx                         app shell
├── (auth)/login.tsx, signup.tsx       auth pages (no app chrome)
├── (layout)/
│   ├── route.tsx                      shared navbar/footer layout
│   ├── index.tsx                      landing
│   ├── opportunities/index.tsx, $id.tsx
│   ├── resources/.../$id.tsx          training + guides, list + detail
│   └── (protected)/
│       ├── route.tsx                  auth guard
│       ├── submit.tsx, submissions.tsx, my-submissions.tsx
└── admin/index.tsx, queue.tsx, review.tsx

Three conventions do the heavy lifting:

• (group) folders organise routes without adding URL segments — (auth), (layout), (protected) are structural, not path segments.
• Pathless layout routes (route.tsx) inject shared UI and guards. The (protected)/route.tsx boundary enforces auth before any submission/admin page renders.
• $id.tsx dynamic segments handle detail pages with type-safe params.

The generated routeTree.gen.ts is produced by the router plugin (or pnpm generate-routes) and must not be hand-edited.

8. Push to GitHub with clear, meaningful commits

The repo enforces Conventional Commits repo-wide through git hooks installed at the workspace root:

• Husky 9 activates the hooks (.husky/).
• commit-msg runs commitlint (@commitlint/config-conventional) on every message — feat(client): ..., refactor(server): ..., chore: ....
• pre-commit runs lint-staged, auto-fixing staged files with eslint --fix and prettier --write so nothing unformatted lands.

Branching model (from CONTRIBUTING.md): branches start from and target development; main advances only via release merge. The migration itself

Server migration — JavaScript Express to TypeScript modules

Phase 2 rewrote the API in TypeScript 6 without changing the
runtime contract the client consumes.

Architecture: one module per domain. Each domain owns four files with a single responsibility each:

server/src/modules/<domain>/
├── <domain>.routes.ts       route table
├── <domain>.controller.ts   HTTP in/out only
├── <domain>.service.ts      business logic + Supabase calls
└── <domain>.schema.ts       Zod request validation

Domains: auth, admin, opportunities, trainings, guides, templates, profile, meta, health. The composition root is app.ts → routes.ts → each module's routes. Cross-cutting concerns live in middleware/
(authenticate, require-role, rate-limit, validate-request, upload, error-handler) and shared helpers in lib/ (response, http-error, async-handler, supabase, validation, storage, logger).

Toolchain:

• tsx runs the dev server with watch mode (tsx watch src/server.ts) — no precompile step in development.
• tsc + tsc-alias produce the production build, rewriting the #/* path alias to real relative paths in the emitted dist/.
• Typed database access. pnpm db:types generates src/types/database.ts from the live Supabase schema, so queries are checked against the real table shapes.
• Zod validates every request body before it reaches a controller, mirroring the client's use of the same library.

Security and ops middleware carried over and are now typed: helmet, cors, morgan, express-rate-limit, and multer for uploads.

Library reference

Every library introduced by the migration and the job it does.

Client

Server

Workspace

What the migration bought, measurably

• Type safety end to end — pnpm typecheck (client and server) and generated Supabase types catch contract drift before runtime.
• One quality gate — pnpm check runs lint + typecheck + tests + format on both packages; pre-commit blocks unformatted code; commit-msg blocks malformed history.
• Smaller, lazier bundles — autoCodeSplitting ships one chunk per route instead of one monolithic script.
• Zero cumulative layout shift on first paint via fontaine fallbacks.
• Reusable UI — a single design-system layer replaces per-page markup, so a button change lands everywhere at once.

Related docs

• CHANGELOG.md — [2.0.0] frontend rewrite entry with full Added/Changed/Removed.
• docs/pnpm-workspace-migration.md — the workspace consolidation.
• client/docs/tooling-plan.md — client tooling design notes.
• client/docs/migration-shared-components.md — component extraction notes.
• server/docs/system-design-case-study.md — server architecture rationale.
• server/docs/api/endpoints.md — API reference the client consumes.