feat: add mortgage rate microservice with API, UI, and dark mode

[devin-ai-integration]

What does this PR do?

Adds a new standalone Next.js 15 microservice at apps/mortgage-rates/ that displays current mortgage rates for different loan terms based on US state location.

Key components:

• REST API (/api/rates): Accepts state (required) and loanAmount (optional) query params. Returns rates for 6 mortgage products (30-year fixed, 15-year fixed, 5/1 ARM, 7/1 ARM, FHA, VA) with monthly payment calculations using the standard amortization formula.
• Frontend UI: Interactive dashboard with state selector dropdown, loan amount input with quick presets, and a responsive card grid displaying rates, APR, monthly payment, total interest, and total cost.
• Data service (mortgage-data-service.ts): Base national rates with per-state adjustment factors simulating regional variation across all 50 states.
• Dark/Light theme toggle: Fixed-position toggle button (top-right) with sun/moon icons. Uses React Context (ThemeProvider) with localStorage persistence and system preference detection via prefers-color-scheme. All components styled with Tailwind dark: variants.

The app runs on port 3100 and is self-contained within the monorepo workspace.

Note: Rates are simulated/hardcoded data — not sourced from a live provider. This is acknowledged in code comments and a user-facing disclaimer.

Updates since last revision

Added dark/light theme toggle feature:

• New files: ThemeProvider.tsx (React Context + localStorage + system preference detection), ThemeToggle.tsx (fixed-position button with sun/moon SVG icons)
• Modified: layout.tsx wraps app in ThemeProvider, globals.css adds @custom-variant dark for Tailwind CSS 4 class-based dark mode
• All UI components updated with dark: Tailwind variants: MortgageRateDashboard, RateCard, StateSelector, LoanAmountInput, RateResults, EmptyState, LoadingSpinner

Visual Demo

Video Demo:

Theme toggle demo — shows light mode with rates loaded, switching to dark mode, scrolling through cards, switching back, and verifying localStorage persistence across page reload:

View original video (rec-18d9dc07b439479c8df0789735f71b98-edited.mp4)

Image Demo:

Light mode:

Dark mode:

Mandatory Tasks (DO NOT REMOVE)

• I have self-reviewed the code (A decent size PR without self-review might be rejected).
• I have updated the developer docs in /docs if this PR makes changes that would require a documentation change. N/A — new standalone app, no docs changes needed.
• I confirm automated tests are in place that prove my fix is effective or that my feature works.

Items for Reviewer Attention

1. No automated tests — calculateMonthlyPayment, getTermYears, the API route, and the theme toggle logic have no unit tests.
2. Duplicate type definitions — RateWithPayment and RateApiResponse interfaces are defined in both MortgageRateDashboard.tsx and RateResults.tsx instead of a shared types file.
3. getTermYears is fragile — parses term length by checking if the display string .includes("30"), .includes("15"), etc. If term names change, this silently falls back to 30. Consider using a lookup map keyed on exact term strings.
4. ARM term display may confuse users — getTermYears returns 30 for both 5/1 and 7/1 ARM (correct for full amortization), but the RateCard UI shows "30-year term" for these products, which could mislead users about the fixed-rate period.
5. MonthlyPaymentEstimate type is unused — defined in types/mortgage.ts but never imported anywhere.
6. yarn.lock not committed — the lockfile change from adding the new workspace was left unstaged, so dependencies aren't locked for this app.
7. Not wired into monorepo turbo pipeline — no changes to root turbo.json; the new app won't be included in turbo run build/turbo run lint unless it's picked up by workspace globbing.
8. Potential flash of unstyled content (FOUC) on dark mode — The ThemeProvider initializes with theme="light" on SSR, then runs useEffect on mount to read localStorage and system preference. This means dark mode users may see a brief flash of light mode on initial page load. The suppressHydrationWarning on <html> suppresses the warning but doesn't prevent the visual flash.
9. @custom-variant dark is Tailwind CSS 4 syntax — verify this works with the project's Tailwind CSS 4.1.17 setup. This uses &:where(.dark, .dark *) selector which may have specificity implications.

How should this be tested?

Functional testing:

1. cd apps/mortgage-rates && yarn dev — app starts on http://localhost:3100
2. Select a state (e.g., "California") and adjust loan amount using presets
3. Verify rates update with debouncing (~300ms delay)
4. Test API directly: curl "http://localhost:3100/api/rates?state=CA&loanAmount=500000"
5. Verify error handling: invalid state codes and out-of-range loan amounts return 400 errors

Dark mode testing:

1. With app running, click the moon icon (top-right) to switch to dark mode
2. Verify all text is readable on dark backgrounds (header, labels, rate cards, disclaimer)
3. Verify the button changes to sun icon with aria-label "Switch to light mode"
4. Select a different state and verify dark mode persists
5. Reload the page — verify it stays in dark mode (localStorage persistence)
6. Click sun icon to switch back to light mode
7. Test system preference: set OS to dark mode, clear localStorage item mortgage-rates-theme, reload — should default to dark

Expected behavior:

• Rates vary by state (e.g., CA should have +0.12% adjustment, MS should have -0.11%)
• Monthly payment should match amortization formula: P = L[r(1+r)^n]/[(1+r)^n - 1] where r is monthly rate and n is total months
• UI should be responsive and accessible (keyboard navigation, proper labels)
• Theme toggle should work instantly with smooth transitions
• Theme preference should persist across page reloads

Environment:

• No environment variables required
• Uses React 18.2.0, Next.js 15.3.3, Tailwind CSS 4.1.17
• Biome lint and TypeScript strict mode passes

Checklist

• My code follows the style guidelines of this project (Biome lint passes)
• I have commented my code, particularly in hard-to-understand areas (JSDoc on data service functions, inline comments for key calculations)
• My changes generate no new warnings (TypeScript and Biome both pass clean)

---

Session: https://partner-workshops.devinenterprise.com/sessions/a3cceb8dccbd43cc9e5e6e71b653ac2a
Requested by: somasundaram.panneerselvam

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

Devin Review found 2 potential issues.

View 5 additional findings in Devin Review.

[devin-ai-integration]

🔴 Race condition: stale fetch responses can overwrite fresh data, showing wrong state's rates

The fetchRates callback uses fetch without an AbortController, and the debounce's clearTimeout only cancels pending timers—not in-flight network requests. This creates a classic race condition:

1. User selects "CA" → 300ms debounce fires → fetch for CA starts (in-flight)
2. User changes to "NY" → clearTimeout is a no-op (timer already fired) → new 300ms timer starts
3. After 300ms, fetch for NY starts
4. If the NY response arrives first and then the older CA response arrives later, setRateData(CA data) at MortgageRateDashboard.tsx:60 overwrites the correct NY data

The user now sees "Rates for California" (from RateResults.tsx:31) while the dropdown shows "New York". For a financial comparison tool, displaying rates for the wrong state is a data correctness issue that could mislead users.

Prompt for agents

The fetchRates function in MortgageRateDashboard.tsx (lines 42-67) performs fetch requests without any cancellation mechanism. When inputs change rapidly, an older response can arrive after a newer one and overwrite the correct data via setRateData.

To fix this, use an AbortController:
1. Create an AbortController inside the useEffect (not inside fetchRates)
2. Pass its signal to the fetch call
3. In the useEffect cleanup, call controller.abort() alongside clearTimeout
4. In the catch block, check if the error is an AbortError and skip updating state if so

This ensures that when inputs change, the in-flight request for the old inputs is cancelled and cannot overwrite the new data. The fetchRates function should accept an AbortSignal parameter, or the fetch logic should be moved inline into the useEffect.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 EmptyState and RateResults render simultaneously for ~300ms when user deselects state

When the user deselects a state (changes dropdown back to "-- Choose a state --"), selectedState becomes "" immediately, but rateData is only cleared to null after the 300ms debounce timer fires (inside fetchRates at line 44). During those 300ms, both render conditions at lines 105 and 107 are true simultaneously:

• !selectedState && !loading → true → renders EmptyState
• rateData && !loading → true → renders RateResults (with stale data)

This causes a visual glitch where both the "Select a state to get started" empty state and the previous state's rate cards are shown at the same time.

Suggested change

	{!selectedState && !loading && <EmptyState />}
	{rateData && !loading && <RateResults rateData={rateData} />}
	{!selectedState && !loading && !rateData && <EmptyState />}
	{rateData && !loading && selectedState && <RateResults rateData={rateData} />}

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Closing: this PR is older than 3 weeks. Reopen if still needed.

[devin-ai-integration]

❌ Cannot revive Devin session - the session is too old. Please start a new session instead.