refactor feature architecture (#181)

* refactor: co-locate audit session and preference state

* refactor: separate course search and planner features

* refactor: organize audit UI and extension surfaces

* docs: align architecture with feature ownership

* button fix

Author: spotta85

README.md

@@ -21,9 +21,9 @@ _(Add a screenshot or a GIF of your extension in action here!)_
 
 - **Frontend:** React, TypeScript
 - **Styling:** Tailwind CSS
-- **State Management:** Redux Toolkit
-- **Backend & Data:** Supabase (for storing user-created plans)
-- **Platform:** Chrome Extension API (Manifest V3)
+- **State Management:** React Context and local component state
+- **Data:** Browser storage for audits/preferences and IndexedDB (Dexie) for the course catalog; no external backend
+- **Platform:** Chrome (Manifest V3) and Firefox extension APIs via WXT
 - **Build Tools:** WXT, Vite, Bun
 
 ## Installation

docs/architecture.md

@@ -0,0 +1,271 @@
+# Architecture
+
+Degree Audit Plus uses feature-owned modules with one-way dependencies. Code
+that changes for the same reason lives together; shared folders are reserved for
+application vocabulary, reusable UI primitives, and the extension message
+protocol.
+
+The main state seam is `features/audit/audit-provider.tsx`. The main persisted
+state seam is `features/audit/audit-storage.ts`. No separate planner store or
+global state library is needed.
+
+## Layout
+
+```text
+features/
+├── audit/                  # Audit state, persistence, mutations, calculations, UI
+│   └── ui/                 # Audit-specific pages, cards, panels, graph, navigation
+├── audit-scraping/         # UT audit acquisition and browser controllers
+├── catalog/                # Catalog data, IndexedDB, mapping, catalog parser
+│   └── scraping/           # Developer catalog-refresh parser
+├── course-search/          # Audit-aware catalog search and add-course modal
+├── planner/                # Planner UI and local interaction state
+├── session/                # UT authentication/session knowledge
+├── preferences/            # Preference persistence and React state
+├── popup/                  # Popup surface and popup-only state
+└── banner/                 # UT-page banner
+
+domain/                     # Framework-free application types and semester helpers
+components/ui/              # Reusable UI primitives
+lib/browser/                # Typed extension message protocol
+entrypoints/                # WXT registration and feature composition
+scripts/catalog/            # Developer-only catalog refresh and validation
+```
+
+## Dependency direction
+
+```mermaid
+flowchart TD
+    Domain["domain"]
+    Catalog["catalog"]
+    Preferences["preferences"]
+    AuditCore["audit core"]
+    CourseSearch["course-search"]
+    Planner["planner"]
+    AuditUI["audit/ui"]
+    Session["session"]
+    Messages["lib/browser"]
+    Scraping["audit-scraping"]
+    Surfaces["popup + banner"]
+    Entrypoints["entrypoints"]
+
+    Catalog --> Domain
+    Preferences --> Domain
+    AuditCore --> Domain
+    AuditCore --> Preferences
+    CourseSearch --> Catalog
+    CourseSearch --> AuditCore
+    CourseSearch --> Domain
+    Planner --> AuditCore
+    Planner --> CourseSearch
+    Planner --> Domain
+    Planner --> AuditUI
+    AuditUI --> AuditCore
+    AuditUI --> CourseSearch
+    AuditUI --> Preferences
+    Scraping --> AuditCore
+    Scraping --> Session
+    Scraping --> Messages
+    Surfaces --> AuditCore
+    Surfaces --> Session
+    Surfaces --> Messages
+    Entrypoints --> AuditUI
+    Entrypoints --> Planner
+    Entrypoints --> Scraping
+    Entrypoints --> Surfaces
+```
+
+The important constraints are:
+
+- Catalog is data-only. It imports domain types, Dexie, and its own files; it
+  never imports Audit, Course Search, Planner, or React.
+- Audit core never imports Audit UI, Course Search, Planner, Popup, Banner, or
+  Audit Scraping.
+- Course Search is the explicit join between Audit and Catalog. Recommendation
+  functions accept audit sections as arguments and do not use React.
+- Planner reuses Audit as the persisted state owner. Drag, menu, and preview
+  state stay local to Planner UI.
+- Audit Scraping contains no React/UI code. It writes through Audit Storage and
+  uses Session for authentication knowledge.
+- Features never import entrypoints. Entrypoints register controllers and
+  compose providers/components; features do not depend on them.
+
+## Feature responsibilities
+
+### Audit
+
+`audit-provider.tsx` loads and observes the selected audit, owns URL and
+last-selected-audit fallback, derives sections/progress/courses/semesters, and
+persists user intents. Its public React interface remains `AuditContextProvider`
+and `useAuditContext()`.
+
+`audit-storage.ts` is the only owner of audit browser-storage details. It owns
+the existing keys and stored shapes for:
+
+- audit history (`getAuditHistory`, `observeAuditHistory`, `saveAuditHistory`,
+  `renameAudit`);
+- individual audit data (`getAuditData`, `watchAuditData`, `saveAuditData`,
+  `getUncachedAuditIds`); and
+- saved audit combinations (`getCachedComposites`, `createComposite`,
+  `updateCachedComposite`, `deleteCachedComposite`, `loadCompositeAudit`).
+
+`observeAuditHistory` hides the initial read plus subsequent storage watch behind
+one cleanup function. It prevents a delayed initial read from overwriting a newer
+watched update.
+
+`audit-mutations.ts` contains immutable, browser-free changes to cached audit
+data: add, remove, wipe, and move planned courses. `audit-calculations.ts`
+contains side-effect-free composite/progress calculations. `section-groups.ts`
+contains the pure mapping from calculated sections to dashboard display groups.
+
+`audit/ui/` may consume Audit core, Preferences, Course Search, domain types,
+and shared UI utilities. It never reads browser storage directly. Planner reuses
+the audit-owned degree side panel because that panel displays audit progress; the
+dependency remains one-way and Audit UI does not import Planner.
+
+### Audit Scraping
+
+- `audit-page-parser.ts` converts one UT audit result document to
+  `CachedAuditData`.
+- `audit-history-parser.ts` converts history HTML to `AuditHistoryEntry[]`.
+- `parse-major.ts` owns UT program-name normalization.
+- `audit-history-sync.ts` fetches, parses, stores, and observes audit history,
+  then requests uncached audit scrapes.
+- `content-controller.ts` responds to content-script messages, parses the
+  visible result page, and records visible login state.
+- `background-controller.ts` coordinates scrape batches, timeouts, result
+  persistence, sync status, dashboard opening, and new-audit runs.
+- `scraper-window.ts` hides minimized window/tab creation, page-load waiting,
+  messaging, and cleanup.
+
+Login-page recognition is intentionally not in a parser. It belongs to Session.
+
+### Catalog and Course Search
+
+Catalog owns the bundled course data and its IndexedDB representation:
+
+- `catalog-db.ts` owns the Dexie schema and catalog queries.
+- `seed-catalog.ts` versions and seeds IndexedDB from the bundled JSON.
+- `department-map.ts` is static department data.
+- `catalog-course-mappers.ts` contains pure preview/planned-course transforms,
+  filtering, and deduplication.
+- `scraping/catalog-parser.ts` parses UT catalog HTML for the developer refresh
+  workflow in `scripts/catalog/`.
+
+Course Search owns the audit-aware user flow:
+
+- `course-recommendations.ts` joins audit requirements to Catalog queries using
+  plain function arguments.
+- `course-modal-provider.tsx` owns modal scope, recommendations, and loading
+  state, and receives current sections from Audit.
+- The remaining files render search results and the add-course flow. They call
+  Audit Provider intents rather than accessing audit storage.
+
+This split avoids an Audit ↔ Catalog dependency cycle: Audit UI can open Course
+Search, Course Search can read Audit core and Catalog, and Catalog remains
+independent.
+
+### Planner
+
+Planner has no storage or provider of its own. Persisted courses and semesters
+remain in Audit Provider; temporary DnD and menu state remains in Planner UI.
+Substantial future pure logic such as prerequisite validation or semester-load
+calculation may earn a planner calculation module, but no abstraction is added
+until that logic exists.
+
+### Session and Preferences
+
+`session/session.ts` is the only owner of UT authentication knowledge: the login
+cache, probe URL, cookie name/watch, login-page recognition, and login-tab
+opening. Popup and Audit Scraping consume this interface rather than knowing UT
+session details.
+
+`preferences-storage.ts` owns preference keys, defaults, and typed WXT storage
+items. `preferences-provider.tsx` owns the React state and document theme for
+sidebar, luminosity, view mode, and last-selected audit.
+
+### Popup and Banner
+
+Popup owns popup-only presentation state such as `showAll`, `runningAudit`, login
+presentation, and sync indicators. Banner owns only its open/closed state and
+the first available audit ID. Both receive history through Audit Storage; they do
+not duplicate persistence logic.
+
+## Runtime data flows
+
+### Audit acquisition
+
+```mermaid
+sequenceDiagram
+    participant Content as audit content controller
+    participant Sync as audit history sync
+    participant Store as audit storage
+    participant BG as background controller
+    participant Window as scraper window
+    participant Parser as audit page parser
+
+    Content->>Sync: startAuditHistorySync(document)
+    Sync->>Store: saveAuditHistory(entries)
+    Sync->>Store: getUncachedAuditIds(ids)
+    Sync->>BG: SCRAPE_ALL_AUDITS
+    loop each uncached audit
+        BG->>Window: create scraper tab
+        Window->>Content: RUN_SCRAPER
+        Content->>Parser: parseAuditPage(document)
+        Parser-->>Content: CachedAuditData
+        Content->>BG: AUDIT_RESULTS
+        BG->>Store: saveAuditData(id, audit)
+        BG->>Window: close scraper tab
+    end
+```
+
+### Dashboard state
+
+```mermaid
+flowchart LR
+    History["Audit Storage history"] --> Provider["Audit Provider"]
+    Data["Selected CachedAuditData"] --> Provider
+    Preferences["last audit preference"] --> Provider
+    Provider --> Calculations["pure calculations"]
+    Provider --> AuditUI["Audit UI"]
+    Provider --> Planner["Planner"]
+    Provider --> Search["Course Search"]
+    Search --> Catalog["Catalog queries"]
+    AuditUI -->|intent| Provider
+    Planner -->|intent| Provider
+    Search -->|add-course intent| Provider
+    Provider -->|persist| Data
+```
+
+Only canonical audit data is stored. Requirements, progress, course maps, and
+semester groups are derived in the provider so views do not maintain competing
+copies of the same state.
+
+## Shared code and entrypoints
+
+`domain/` contains plain TypeScript vocabulary and semester helpers with no
+React, browser, storage, or Dexie dependencies. `components/ui/` contains only
+genuinely reusable UI primitives. `lib/browser/messages.ts` owns the typed
+extension message union and send/response helpers.
+
+Entrypoints stay thin:
+
+- `background.ts` registers the Audit background controller.
+- `content.tsx` starts the Audit content controller and mounts the UT-page
+  banner.
+- `degree-audit/main.tsx` seeds Catalog, composes Preferences → Audit → Course
+  Search providers, and selects Audit versus Planner view.
+- `popup-app/main.tsx` creates the popup root and renders Popup.
+
+## Adding functionality
+
+Start in the feature whose vocabulary and state the change belongs to. Add pure
+logic beside that feature's existing calculations/mutations when possible, put
+persistence behind its storage interface, and keep temporary interaction state
+local to the UI. A new cross-feature module is justified only when it represents
+a real user workflow, as Course Search does between Audit and Catalog.
+
+Tests mirror ownership: audit state/storage tests live in `tests/audit`, browser
+controller tests in `tests/audit-scraping`, parser snapshots in `tests/scraping`,
+and catalog refresh tests in `tests/catalog`. Standalone validation scripts cover
+major parsing, requirement progress, composite loading, and saved combinations.

entrypoints/content.tsx

@@ -1,6 +1,6 @@
 import { startAuditContentController } from "@/features/audit-scraping/content-controller";
 import { createRoot } from "react-dom/client";
-import TryDAPBanner from "@/features/misc/try-dap-banner";
+import TryDAPBanner from "@/features/banner/try-dap-banner";
 import "./styles/content.css";
 
 function loadFonts(): void {

entrypoints/degree-audit/main.tsx

@@ -4,17 +4,17 @@ import { cn } from "@/lib/utils";
 import React from "react";
 import ReactDOM from "react-dom/client";
 import { HStack, VStack } from "@/components/ui/stack";
-import DegreeAuditPage from "@/features/degree-audit-app/audit-view/degree-audit-page";
-import CourseAddModal from "@/features/degree-audit-app/course-search/course-add-modal";
-import CourseModalContextProvider from "@/features/degree-audit-app/course-search/course-modal-provider";
-import DegreePlannerPage from "@/features/degree-audit-app/planner-view/degree-planner-page";
-import AuditContextProvider from "@/features/degree-audit-app/providers/audit-provider";
+import DegreeAuditPage from "@/features/audit/ui/degree-audit-page";
+import CourseAddModal from "@/features/course-search/course-add-modal";
+import CourseModalContextProvider from "@/features/course-search/course-modal-provider";
+import DegreePlannerPage from "@/features/planner/degree-planner-page";
+import AuditContextProvider from "@/features/audit/audit-provider";
 import {
   PreferencesProvider,
   usePreferences,
-} from "@/features/degree-audit-app/providers/preferences-provider";
-import Navbar from "@/features/degree-audit-app/shared/navbar";
-import Sidebar from "@/features/degree-audit-app/shared/sidebar";
+} from "@/features/preferences/preferences-provider";
+import Navbar from "@/features/audit/ui/navbar";
+import Sidebar from "@/features/audit/ui/sidebar";
 import ErrorBoundary from "@/components/error-boundary";
 
 const App = () => {

features/audit-scraping/audit-history-sync.ts

@@ -2,10 +2,10 @@ import type { AuditHistoryEntry } from "@/domain/audit";
 import {
   getUncachedAuditIds,
   saveAuditHistory,
-} from "@/lib/storage/audit-storage";
+} from "@/features/audit/audit-storage";
+import { isLoginPage } from "@/features/session/session";
 import { sendRuntimeMessage } from "@/lib/browser/messages";
 import { parseAuditHistory } from "./audit-history-parser";
-import { checkLoginRequired } from "./audit-page-parser";
 
 const AUDIT_HISTORY_URL =
   "https://utdirect.utexas.edu/apps/degree/audits/submissions/history/";
@@ -19,7 +19,7 @@ export async function fetchAuditHistory(): Promise<AuditHistoryEntry[]> {
     await response.text(),
     "text/html",
   );
-  if (checkLoginRequired(document)) {
+  if (isLoginPage(document)) {
     throw new Error("Not logged in to UT Direct");
   }
   // A logged-in student who has never requested an audit gets a history page

features/audit-scraping/audit-page-parser.ts

@@ -35,13 +35,6 @@ export function parseRequirementProgress(text: string): {
   };
 }
 
-export function checkLoginRequired(doc: Document): boolean {
-  return !!(
-    doc.querySelector('form[action*="login"]') ||
-    doc.querySelector('input[type="password"]')
-  );
-}
-
 export function getRuleStatus(classList: DOMTokenList): Status {
   if (classList.contains("fulfilled")) return "Completed";
   if (classList.contains("partial")) return "In Progress";

features/audit-scraping/background-controller.ts

@@ -1,5 +1,5 @@
 import type { CachedAuditData } from "@/domain/audit";
-import { saveAuditData } from "@/lib/storage/audit-storage";
+import { saveAuditData } from "@/features/audit/audit-storage";
 import {
   sendMessageResponse,
   sendRuntimeMessage,
@@ -15,7 +15,7 @@ import {
   openLoginTab,
   refreshLoginState,
   registerSessionCookieWatcher,
-} from "../../lib/login-state";
+} from "@/features/session/session";
 
 type ScrapeFailure = Extract<
   ExtensionMessage,

features/audit-scraping/content-controller.ts

@@ -2,9 +2,12 @@ import {
   sendRuntimeMessage,
   type ExtensionMessage,
 } from "@/lib/browser/messages";
-import { checkLoginRequired, parseAuditPage } from "./audit-page-parser";
+import {
+  isLoginPage,
+  recordLoginStateFromPage,
+} from "@/features/session/session";
+import { parseAuditPage } from "./audit-page-parser";
 import { startAuditHistorySync } from "./audit-history-sync";
-import { recordLoginStateFromPage } from "../../lib/login-state";
 
 export function startAuditContentController(document: Document): void {
   recordLoginStateFromPage(document);
@@ -16,7 +19,7 @@ export function startAuditContentController(document: Document): void {
   browser.runtime.onMessage.addListener((message: ExtensionMessage) => {
     if (message.type !== "RUN_SCRAPER") return;
 
-    if (checkLoginRequired(document)) {
+    if (isLoginPage(document)) {
       void sendRuntimeMessage({
         type: "AUDIT_SCRAPE_ERROR",
         auditId: message.auditId,