feat: Implement core application structure with new dashboard, settings, and help pages, and enhance opportunities management with persistence and filtering.

2026-02-03 20:05:30 +00:00
parent 609b9da020
commit 885bbbf954
21 changed files with 1282 additions and 106 deletions
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -13,3 +13,5 @@
 - Added missing `by_owner` index on `userId` to the `projects` table in `convex/schema.ts`
 - Removed redundant `.filter()` call in `convex/projects.ts` getProjects query

+- Changed global font from Montserrat back to Inter in `app/layout.tsx`
+
--- a/docs/phase-1-foundation.md
+++ b/docs/phase-1-foundation.md
@@ -0,0 +1,59 @@
+# Phase 1 — Foundation & Navigation Unification
+
+## Goals
+- Resolve the split navigation/layout systems and establish a single app shell.
+- Align routing so all authenticated app routes share a consistent layout.
+- Prepare the data model to store analysis and opportunities in Convex.
+
+## Scope
+- Choose a single sidebar layout system.
+- Move or consolidate routes so `/dashboard`, `/opportunities`, and other app pages live under the same layout.
+- Remove unused layout/components or mark deprecated ones.
+- Extend Convex schema to support analysis + opportunity storage.
+- Add indices required for efficient queries.
+
+## Detailed Tasks
+1. **Layout decision & consolidation**
+   - Pick one layout approach:
+     - Option A: Use `(app)` group layout (`app/(app)/layout.tsx`) + `components/sidebar.tsx`.
+     - Option B: Use `app/dashboard/layout.tsx` + `components/app-sidebar.tsx`.
+   - Confirm all protected routes render inside the chosen layout.
+   - Remove or archive the unused layout and sidebar component to avoid confusion.
+
+2. **Route structure alignment**
+   - Ensure `/dashboard`, `/opportunities`, `/settings`, `/help` sit under the chosen layout.
+   - Update sidebar links to match actual routes.
+   - Confirm middleware protects all app routes consistently.
+
+3. **Convex schema expansion (analysis/opportunities)**
+   - Add `analyses` table:
+     - `projectId`, `dataSourceId`, `createdAt`, `analysisVersion`, `productName`, `tagline`, `description`, `features`, `problemsSolved`, `personas`, `keywords`, `useCases`, `competitors`, `dorkQueries`.
+   - Add `opportunities` table:
+     - `projectId`, `analysisId`, `url`, `platform`, `title`, `snippet`, `relevanceScore`, `intent`, `status`, `suggestedApproach`, `matchedKeywords`, `matchedProblems`, `tags`, `notes`, `createdAt`, `updatedAt`.
+   - Indices:
+     - `analyses.by_project_createdAt`
+     - `opportunities.by_project_status`
+     - `opportunities.by_project_createdAt`
+     - Optional: `opportunities.by_project_url` for dedupe.
+
+4. **Convex API scaffolding**
+   - Queries:
+     - `analyses.getLatestByProject`
+     - `opportunities.listByProject` (filters: status, intent, minScore, pagination).
+   - Mutations:
+     - `opportunities.upsertBatch` (dedupe by URL + project).
+     - `opportunities.updateStatus`.
+
+## Dependencies
+- None. This phase unblocks persistence and UI work.
+
+## Acceptance Criteria
+- All app routes share one layout and sidebar.
+- Convex schema includes analysis + opportunities tables with indices.
+- Basic Convex queries/mutations exist for later phases.
+
+## Risks
+- Choosing a layout path may require minor refactors to route locations.
+
+## Notes
+- Confirm with product direction which sidebar design to keep.
--- a/docs/phase-2-onboarding-and-dashboard.md
+++ b/docs/phase-2-onboarding-and-dashboard.md
@@ -0,0 +1,49 @@
+# Phase 2 — Onboarding Persistence & Dashboard
+
+## Goals
+- Persist analysis results in Convex instead of localStorage.
+- Connect onboarding to project + data source records.
+- Build a functional dashboard that renders saved analysis.
+
+## Scope
+- Update onboarding flow to create or select a project.
+- Save analysis results to Convex and store IDs.
+- Render dashboard from Convex queries with empty/loading states.
+
+## Detailed Tasks
+1. **Onboarding persistence**
+   - When analysis completes:
+     - Ensure a default project exists (create if missing).
+     - Create a `dataSources` entry for the URL or manual input.
+     - Insert a new `analyses` record linked to project + data source.
+   - Stop using localStorage as the source of truth (can keep as cache if needed).
+   - Store analysisId in router state or query param if useful.
+
+2. **Manual input integration**
+   - Same persistence path as URL analysis.
+   - Mark data source type + metadata to indicate manual origin.
+
+3. **Dashboard implementation**
+   - Fetch latest analysis for selected project.
+   - Render:
+     - Product name + tagline + description.
+     - Summary cards (features, keywords, personas, competitors, use cases).
+     - Top features list + top problems solved.
+   - Add empty state if no analysis exists.
+
+4. **Project selection behavior**
+   - When project changes in sidebar, dashboard should re-query and update.
+
+## Dependencies
+- Requires Phase 1 schema and layout decisions.
+
+## Acceptance Criteria
+- Onboarding persists analysis to Convex.
+- Dashboard displays real data from Convex.
+- Refreshing the page keeps data intact.
+
+## Risks
+- Larger analysis objects may need pagination/partial display.
+
+## Notes
+- Keep UI fast by showing a small, curated subset of analysis data.
--- a/docs/phase-3-opportunities-and-workflow.md
+++ b/docs/phase-3-opportunities-and-workflow.md
@@ -0,0 +1,48 @@
+# Phase 3 — Opportunities Persistence & Workflow
+
+## Goals
+- Persist opportunity search results in Convex.
+- Enable lead management (status, notes, tags).
+- Add filtering, pagination, and basic bulk actions.
+
+## Scope
+- Write opportunities to Convex during search.
+- Read opportunities from Convex in the UI.
+- Implement lead status changes and notes/tags.
+
+## Detailed Tasks
+1. **Persist opportunities**
+   - Update `/api/opportunities` to call `opportunities.upsertBatch` after scoring.
+   - Dedupe by URL + projectId.
+   - Store analysisId + projectId on each opportunity.
+
+2. **Load opportunities from Convex**
+   - Replace local state-only data with Convex query.
+   - Add pagination and “Load more” to avoid giant tables.
+
+3. **Filtering & sorting**
+   - Filters: status, intent, platform, min relevance score.
+   - Sorting: relevance score, createdAt.
+
+4. **Lead workflow actions**
+   - Status change: new → viewed/contacted/responded/converted/ignored.
+   - Add notes + tags; persist via mutation.
+   - Optional: quick bulk action for selected rows.
+
+5. **UI feedback**
+   - Show counts by status.
+   - Empty states for no results or no saved opportunities.
+
+## Dependencies
+- Requires Phase 1 schema and Phase 2 project + analysis persistence.
+
+## Acceptance Criteria
+- Opportunities persist across refresh and sessions.
+- Status/notes/tags are stored and reflected in UI.
+- Filters and pagination are usable.
+
+## Risks
+- Serper or direct Google scraping limits; need clear UX for failed searches.
+
+## Notes
+- Keep raw search results transient; only store scored opportunities.
--- a/docs/phase-4-settings-help-reliability.md
+++ b/docs/phase-4-settings-help-reliability.md
@@ -0,0 +1,44 @@
+# Phase 4 — Settings, Help, Reliability, QA
+
+## Goals
+- Provide basic Settings and Help pages.
+- Improve reliability for long-running operations.
+- Add verification steps and basic test coverage.
+
+## Scope
+- Implement `/settings` and `/help` pages.
+- Add progress and error handling improvements for analysis/search.
+- Document manual QA checklist.
+
+## Detailed Tasks
+1. **Settings page**
+   - Account info display (name/email).
+   - API key setup instructions (OpenAI, Serper).
+   - Placeholder billing section (if needed).
+
+2. **Help page**
+   - Quickstart steps.
+   - Outreach best practices.
+   - FAQ for common errors (scrape failures, auth, API keys).
+
+3. **Reliability improvements**
+   - Move long-running tasks to Convex actions or background jobs.
+   - Track job status: pending → running → completed/failed.
+   - Provide progress UI and retry on failure.
+
+4. **QA checklist**
+   - Auth flow: sign up, sign in, sign out.
+   - Onboarding: URL analysis + manual analysis.
+   - Dashboard: correct rendering for project switch.
+   - Opportunities: search, save, status change.
+
+## Dependencies
+- Depends on Phases 1–3 to stabilize core flows.
+
+## Acceptance Criteria
+- `/settings` and `/help` routes exist and are linked.
+- Background tasks reduce timeouts and improve UX.
+- QA checklist is documented and executable.
+
+## Notes
+- Keep Settings minimal until billing/teams are defined.
--- a/docs/qa-checklist.md
+++ b/docs/qa-checklist.md
@@ -0,0 +1,27 @@
+# QA Checklist
+
+## Auth
+- Sign up with email/password.
+- Sign in with email/password.
+- Sign in with Google.
+- Redirect honors `next` query param.
+
+## Onboarding
+- URL analysis completes and redirects to dashboard.
+- Manual input analysis completes and redirects to dashboard.
+- Analysis persists after refresh.
+
+## Dashboard
+- Shows latest analysis for selected project.
+- Project switch updates dashboard data.
+- Empty states render when no analysis exists.
+
+## Opportunities
+- Search executes and persists results.
+- Status/notes/tags save and reload correctly.
+- Filters (status, intent, min score) work.
+- Load more increases result count.
+
+## Settings / Help
+- `/settings` and `/help` load under app layout.
+- Sidebar links navigate correctly.