Codex 5.3 Refactor Plan

Last updated: 2026-02-19

Goal

Refactor the codebase incrementally with Codex 5.3 while keeping production stable, reducing regression risk, and converging legacy week-by-week artifacts into a maintainable architecture.

Scope

• Application code under src/
• API routes under src/app/api/
• Shared domain logic under src/lib/
• Prisma schema + migrations under prisma/
• Documentation under root *.md and docs/*.md

Non-Goals

• No rewrite-from-scratch
• No database reset in production
• No destructive migration without rollback path

Refactor Principles

1. Preserve behavior first; improve structure second.
2. Move business rules from route handlers into src/lib/* modules.
3. Keep route handlers thin: parse input, call service, return response.
4. Standardize role/permission checks through shared auth helpers.
5. Prefer explicit types over any.
6. Add tests for critical workflow boundaries before high-risk changes.
7. Ship in small, reversible PRs.

Target Architecture

• src/app/(app)/...: UI composition + page-level state only.
• src/app/api/...: transport layer only.
• src/lib/candidates/*: candidate domain orchestration.
• src/lib/documents/*: upload, validation, analysis triggers.
• src/lib/auth/*: session, role, permission, candidate access.
• src/lib/notifications/*: event routing + templates + outbox.

Delivery Model

Each refactor slice should be shippable in one PR and reversible in one commit.

• PR size target:
  • Preferred: <= 8 files touched
  • Hard cap: <= 15 files unless docs-only
• Commit strategy:
  • 1 logical change per commit
  • Keep docs updates in the same commit as behavior changes
• Branching:
  • main stays deployable
  • Use short-lived branches for non-trivial slices

Risk Tiers

• Tier 1 (low):
  • Pure docs updates
  • Type-only tightening with no runtime behavior changes
• Tier 2 (medium):
  • Route handler extraction to services with unchanged payloads
  • UI state refactors within a single tab
• Tier 3 (high):
  • Candidate status transition logic
  • Auth/role resolution flows
  • Document upload and persistence paths

Tier 3 slices require explicit rollback notes and focused validation evidence.

Execution Phases

Phase 0: Baseline

• Freeze current behavior with smoke checks:
  • Auth/login/logout
  • Candidate list + detail tabs
  • Document upload paths
  • SMO decision + interview flow
• Capture high-risk routes and current payload shapes.

Phase 1: API Boundary Cleanup

• Normalize route error handling (401/403/404/500).
• Consolidate repeated response shape helpers.
• Remove route-level duplicated RBAC snippets by reusing shared guards.

Phase 2: Domain Extraction

• Extract candidate status transitions into dedicated services.
• Extract document lifecycle orchestration (upload record + analysis trigger).
• Keep route signatures unchanged while internals move to services.

Phase 3: UI Tab Hardening

• Reduce cross-tab state coupling.
• Standardize fetch patterns (no-store only where required).
• Add deterministic loading/empty/error states for each tab.

Phase 4: Type Safety and Contracts

• Replace any in candidate detail and related tabs.
• Introduce typed DTOs for API responses used in UI.
• Ensure Prisma enums map cleanly to UI role/status types.

Phase 5: Docs Consolidation

• Keep root week docs as historical records.
• Promote active docs in docs/ as canonical.
• Keep all docs linked to this file until consolidation is complete.

Working Agreement for Codex 5.3 Sessions

1. Start each task by identifying affected workflow + risks.
2. Prefer minimal blast-radius changes.
3. Run focused lint/tests for touched files.
4. Provide migration notes when touching API contracts or schema.
5. Update relevant docs in the same change.

Validation Checklist (per slice)

1. npm run lint on touched paths (or equivalent focused lint command).
2. Verify auth + role-sensitive flows if any auth logic changed.
3. Verify candidate detail tabs if shared candidate loaders changed.
4. Verify upload flow if document services or validation changed.
5. Record what was tested in PR notes.

Migration Safety Protocol

When Prisma schema or migration files are touched:

1. Include forward migration in same PR.
2. Document backward mitigation (data-preserving rollback path).
3. Avoid destructive column drops in same slice as logic rewrites.
4. Confirm application compatibility for both pre/post deploy migration windows when possible.

Done Criteria (per refactor slice)

• Behavior preserved for existing workflows.
• No new lint/type errors in touched files.
• API contract changes documented (if any).
• Rollback strategy is obvious (single commit or scoped revert).
• Tests or manual validation evidence captured.

Suggested Task Backlog

1. Replace any types in src/app/(app)/candidates/[id]/page.tsx.
2. Extract candidate detail data loading into src/lib/candidates/detail.ts.
3. Extract SMO interview upload orchestration into src/lib/documents/smoInterview.ts.
4. Normalize auth role resolution between page and tabs.
5. Add integration checks for GET /api/auth/me and candidate-role fallback behavior.