Uhakiki Migration Guide: v2 → v3

1Executive Summary

The legacy Uhakiki application is an Angular 18 SSR app built on 13 NgModules and 105 components, mixing five UI toolkits (ng-zorro-antd, Angular Material, PrimeNG, Bootstrap 5 / ngx-bootstrap, plus jQuery and SweetAlert2). State is managed through mutable service fields and ~650 manual subscribe() calls; the JWT access token is AES-encrypted with a hardcoded key and persisted in localStorage.

The replacement, uhakiki-v3, has been scaffolded on Angular 22.0.5 with SSR + client hydration, Vitest, TypeScript 6 strict mode, and Zard UI (46 shadcn-style components vendored into src/app/shared/components, styled with Tailwind CSS v4). The scaffold implements the full architectural skeleton mandated by the project standards: 7 lazy-loaded features, a core/ layer with signal-based auth, functional interceptors and guards, and 28 empty page components mirroring the legacy route surface. The scaffold builds cleanly, passes its 40 specs, and SSR-renders with working guard redirects.

The migration is organized into seven phases (Section 9), ordered so that shared infrastructure lands first, the highest-traffic public funnel (landing → auth → registration) lands early, and the largest module (individual, 12 pages) is split into independently shippable slices. Each page follows the same mechanical recipe (Section 10), which keeps reviews predictable.

2System Comparison

3Architectural Decisions (Scaffolding Phase)

Every decision below is already implemented in the scaffold and traces to the project standards (CLAUDE.md). They are binding for all migrated code.

3.1 Feature-based structure, all lazy

The legacy modules/ directory was analyzed and mapped to 7 lazy features: landing, auth, home, individual (12 pages), employer (2), facility (4), sponsor (4). Each feature owns a default-exported *.routes.ts (loaded via loadChildren), a data/ layer (service + model), and pages/ with the 3-file component split. The build confirms each feature emits its own chunk. Features never import another feature's internals; anything shared moves to shared/ or core/.

3.2 Signals-first state, no store library

No NgRx/Redux. Feature data services own state as private writable signals exposed via asReadonly(); derived values are computed(); reads from the server are httpResource/rxResource; mutations are plain HttpClient calls followed by resource.reload(). AuthService already models this pattern.

3.3 Functional HTTP pipeline, no hardcoded URLs

provideHttpClient(withInterceptors([authInterceptor, errorInterceptor])) is configured once in app.config.ts. authInterceptor attaches the Bearer header from the token signal; errorInterceptor centralizes 401 handling (clear session → redirect to /auth/login with returnUrl) so no component handles 401 itself. All service URLs derive from the API_BASE_URL injection token, backed by src/environments/ (apiBaseUrl: '/api' — mirror the legacy proxy.conf.json during development).

3.4 Component conventions

• Standalone by default — never write standalone: true; never write changeDetection: OnPush (it is the v22 default).
• Class names without the Component suffix (IndividualDashboard, not IndividualDashboardComponent).
• inject() everywhere; no constructor logic; no ngOnInit data loading — resources and computed replace it.
• Signal-based input()/output()/model(); native control flow (@if/@for with track); host object instead of @HostBinding/@HostListener; class/style bindings instead of ngClass/ngStyle.

3.5 @Injectable({ providedIn: 'root' }), not @Service()

The Angular 22 CLI now generates the new @Service() decorator. Per the org standard, all scaffolded services were converted to @Injectable({ providedIn: 'root' }) for consistency — keep doing this for every migrated service until the org tooling formally adopts @Service.

3.6 SSR posture

app.routes.server.ts uses RenderMode.Server (the app is auth-gated and dynamic — prerendering is wrong for it). Hydration with event replay is on. Browser-only APIs must go through SSR-safe wrappers: StorageService (guards with isPlatformBrowser) already exists; follow the same pattern for geolocation, device detection, and anything touching window/document. The dark-mode class is applied by an inline script in index.html before first paint to avoid a flash.

4Tooling Decisions & Known Gotchas

These were discovered the hard way during scaffolding — respect them to avoid re-losing the time.

5Target Structure Reference

Legacy → v3 route mapping: modules/landing-page → features/landing, shared/login → features/auth/pages/login, modules/home → features/home, each modules/<domain>/<screen> → features/<domain>/pages/<screen> (dashboards renamed: individual/individual → individual-dashboard, etc.).

6UI Component Migration Map

The legacy app uses ng-zorro in ~90 templates, Material in 8, SweetAlert2 in 46 files, plus Bootstrap/ngx-bootstrap markup and jQuery. All of it maps onto the vendored Zard set. None of the legacy UI packages are installed in v3 — a template does not compile until fully converted, which is the intended forcing function.

7State Management & Data-Fetching Migration

The legacy codebase has ~650 subscribe() calls across 91 files, mostly subscribe-in-ngOnInit HTTP reads plus cross-component BehaviorSubject buses (global.services.ts, facilityGlobal.services.ts, transfer.service.ts, TabSelectionService). The v3 rules eliminate almost all of them:

Canonical feature data service shape

@Injectable({ providedIn: 'root' })
export class IndividualService {
  private readonly http = inject(HttpClient);
  private readonly apiBaseUrl = inject(API_BASE_URL);

  readonly selectedMemberId = signal<string | null>(null);

  readonly member = httpResource<Member | null>(
    () => this.selectedMemberId()
      ? `${this.apiBaseUrl}/members/${this.selectedMemberId()}`
      : undefined,
    { defaultValue: null },
  );

  readonly dependents = computed(() => this.member.value()?.dependents ?? []);

  async updateMember(changes: Partial<Member>): Promise<void> {
    await firstValueFrom(
      this.http.put(`${this.apiBaseUrl}/members/${this.selectedMemberId()}`, changes),
    );
    this.member.reload();
  }
}

8Authentication & Security Migration

Guard placement is already correct in app.routes.ts: landing and auth are public; home, individual, employer, facility, sponsor sit behind canActivate: [authGuard]. Never rely on hiding buttons as authorization.

9Prioritized Migration Plan

Ordering rationale: shared plumbing first (everything depends on it), then the public acquisition funnel (landing → login → new registration) because it has the most traffic and no auth dependencies, then authenticated dashboards by module size — smallest first (employer) to bake the recipe before the 12-page individual module. Each phase is independently shippable and ends with build + tests green and a signed commit.

10Per-Page Migration Recipe

Every legacy screen migrates through the same nine steps. Do not batch multiple pages into one PR.

1. Read the legacy component (modules/<domain>/<screen>): list its API calls, route params, form fields, dialogs, and cross-component state.
2. Model first: add/extend the interfaces in features/<domain>/data/<domain>.model.ts from the actual API payloads (no any).
3. Data service: add resources (reads) and async mutation methods (writes) to the feature data service; derived state as computed. No HTTP in the component.
4. Template: rewrite the HTML with Zard components + Tailwind using the Section 6 map; native control flow only; every @for tracked by a stable id; loading via isLoading() + skeleton; errors via the shared notification service.
5. Forms: Signal Forms with schema validation mirroring the legacy validators; server remains source of truth; submit disabled in flight.
6. Kill the leftovers: no subscribe() without takeUntilDestroyed() (and only for true event streams), no jQuery, no Swal, no Bootstrap classes, no console.log.
7. Specs: Vitest spec for the page (renders, key states) and for any new service logic.
8. Checklist: run the CLAUDE.md performance checklist + an AXE pass on the page.
9. Commit: one page per signed commit (gs skill, git commit -S); the lazy-chunk build output should show the feature chunk grew as expected and the initial bundle did not.

11Risks, Gaps & Open Decisions

12Definition of Done (per page and for cutover)

• Feature parity with the legacy screen verified against the same backend.
• Zero legacy UI dependencies (ng-zorro, Material, PrimeNG, Bootstrap, jQuery, SweetAlert2, ngx-toastr) in package.json.
• All reads via httpResource/rxResource; all derived state computed; no un-torn-down subscriptions.
• Signal Forms on every new form; classic Reactive Forms nowhere.
• Every feature in its own lazy chunk; bundle budgets green; heavy content behind @defer.
• AXE clean, WCAG AA met; SSR renders without browser-API crashes.
• Vitest suite green in CI; each page has at least a render + primary-flow spec.
• Auth: in-memory access token, HttpOnly refresh cookie, centralized 401, guards on every private route.
• v2 traffic fully drained and repository archived.