How keirancpflynn/llmnesia-insights works
1. What this system is
- LLMnesia Insights is a Next.js-based analytics and planning app with two main product areas: a weekly insights dashboard and a separate SEO/traffic growth planner. It is not just a UI; it also contains the data collection pipeline, LLM analysis layer, and persistence in Supabase.
2. Primary runtime boundary
- The repository splits into three execution modes:
- Web app under app/ and components/ for the dashboard, strategy page, growth planner, login gate, and chat/correction flows.
- Pipeline/CLI under src/ for collecting metrics, calling LLMs, and writing weekly records.
- Scheduled API execution via app/api/run/route.ts, which triggers the same pipeline from a button or Vercel Cron.
3. Core weekly insights flow
- The main pipeline collects product metrics from external analytics services, passes them through an LLM analysis step, and stores the result in Supabase’s weekly_insights table.
- The dashboard then reads the latest or selected week and renders summary text, findings, action items, trend charts, and conversation/correction history.
4. Data collection layer
- src/posthog.ts, src/ga4.ts, src/gsc.ts, and src/bing.ts are the ingestion adapters for external telemetry and search data.
- These adapters are orchestrated by src/pipeline.ts, which is the shared “collect → analyse → save” path used by both the CLI and the API route.
- This layer is the main boundary between owned application logic and third-party data sources.
5. LLM/analysis layer
- src/analyse.ts, src/brief.ts, src/strategy.ts, src/growth-plan.ts, and src/prompts/* encapsulate prompt-driven reasoning.
- The app supports multiple providers, with provider/model selection controlled by environment variables and UI choices.
- The analysis output is structured, not freeform only: the result is mapped into typed records and persisted for later display and revision.
6. Persistence model in Supabase
- The weekly dashboard lives mostly in a single row-per-week table, weekly_insights, which stores metrics snapshots, summary text, findings, action items, chat history, corrections, revisions, and strategy-related fields.
- The growth planner uses a separate relational schema because it is multi-site and row-oriented: sites, gsc_rows, growth_opportunities, growth_plans, and growth_actions.
- This is an important architectural boundary: weekly insights are “snapshot documents,” while growth data is normalized operational data.
7. Dashboard UI structure
- app/page.tsx is the main dashboard entry point, backed by lib/dashboard.ts for flattening and shaping data for charts and views.
- The UI is composed of reusable panels and cards in components/, including summary displays, trend charts, action boards, chat panels, selectors, and editors.
- The dashboard is primarily a read model over Supabase plus a few write actions for regenerating analysis and applying corrections.
8. Interactive analysis workflow
- The dashboard includes chat and correction loops (components/ChatCore.tsx, ChatPanel.tsx, app/api/chat, app/api/corrections) so users can refine the weekly analysis without rerunning the whole ingestion pipeline.
- Revisions and chat state are stored in the weekly record, making the analysis artifact editable and historically traceable rather than one-shot.
9. Growth planner subsystem
- /growth is a separate subsystem for traffic opportunities and weekly action planning.
- It combines GSC and Bing search data with site metadata and previous actions to produce a ranked opportunity set, then uses an LLM to draft a balanced weekly plan.
- Its output is operationalized through an action board with statuses like planned, monitoring/actioned, needs adjustment, and ignored.
10. Strategy subsystem
- /strategy is an independent, week-aware planning surface focused on monetization and product strategy rather than traffic growth.
- It reads PROJECT_BRIEF.md, the latest weekly analysis, and prior decisions to generate a PM/revenue strategy, with its own chat and decision history.
- This makes strategy a distinct workflow from both the dashboard analysis and the SEO planner, even though it reuses the same weekly context.
11. Auth and access control
- Access is gated by a password-based login flow in app/login with middleware enforcement in middleware.ts.
- The pipeline endpoint also has a separate authorization path: button-triggered requests use app auth/cookies, while cron/automation calls are protected by a run secret.
12. Operational tooling
- The scripts/ directory contains consent helpers, diagnostics, seeding, and debugging tools for Google, Bing, GA4, and growth workflows.
- These scripts are not part of the normal web runtime, but they are important operationally because several integrations rely on OAuth setup and environment-specific credentials.
13. Important architectural dependencies
- External dependencies that materially shape the architecture are:
- Supabase for durable storage and queryable state.
- PostHog and GA4 for product usage metrics.
- Google Search Console and Bing Webmaster Tools for search visibility.
- LLM providers such as Claude, DeepSeek, and OpenAI for analysis/planning generation.
- Vercel Cron for weekly automated execution.
- The application is therefore a data-product orchestration system, not a purely frontend dashboard.
14. How to think about the diagram
- A good architecture diagram should show three main flows:
- Analytics flow: external metrics → pipeline → LLM analysis → Supabase weekly_insights → dashboard.
- Growth flow: GSC/Bing/site metadata → opportunity detection → LLM plan → growth tables → growth UI.
- Strategy flow: brief + weekly context + decisions → strategist LLM → strategy state/UI.
- The shared center is Supabase plus the prompt/LLM layer; the web app is mostly a presentation and control plane over those persisted artifacts.
Main entry points: supabase.ts Supabase · pipeline.ts Weekly pipeline · page.tsx Dashboard · growth-plan.ts Growth planner
Components 23
Web app
Dashboard, planner, strategy, login, and route handlers.
- Dashboard · Weekly insights entry point and primary read model.
app/page.tsx - Growth page · SEO and traffic opportunity planning surface.
app/growth/page.tsx - Strategy page · Monetization and product strategy surface.
app/strategy/page.tsx - Login · Password-based access gate.
app/login/page.tsx - Run API · Button or cron entry point that launches the weekly pipeline.
app/api/run/route.ts - Insight chat · Chat and correction loop for weekly insights.
app/api/chat/route.ts - Corrections API · Applies structured revisions to stored weekly analysis.
app/api/corrections/route.ts - Growth APIs · Growth brief, goal, plan, revise, sync, chat, and actions endpoints.
- Strategy API · Strategy chat, goal, decision, and revise endpoints.
app/api/strategy/route.ts - Middleware · Protects authenticated routes and runtime entry points.
middleware.ts
Pipeline
Shared collection, analysis, and write path for weekly insight generation.
- Weekly pipeline · Shared collect → analyse → save workflow.
src/pipeline.ts - Metrics adapters · PostHog, GA4, GSC, and Bing ingestion adapters.
src/posthog.ts - Analysis layer · Briefing, analysis, strategy, and growth-plan generation.
src/analyse.ts - LLM providers · Provider and model selection across Claude, DeepSeek, and OpenAI.
src/llm.ts - Growth planner · Ranks opportunities and drafts weekly growth plans.
src/growth-plan.ts - Strategy planner · Generates week-aware product and revenue strategy.
src/strategy.ts
Data layer
Supabase-backed persistence and local shaping helpers.
- Supabase · Persistent store for weekly insights and growth/strategy state.
src/supabase.ts - Dashboard shaping · Flattens weekly records into chart- and view-friendly data.
lib/dashboard.ts - Growth helpers · Shared growth-state shaping and status logic.
lib/growth.ts
UI kit
Reusable panels, cards, selectors, and editors.
- Chat panels · Reusable chat and correction interfaces.
components/ChatPanel.tsx - Growth UI · Growth dashboard, opportunities, action board, and plan views.
components/GrowthDashboard.tsx - Strategy UI · Strategy panel, goal editor, and chat surface.
components/StrategyPanel.tsx - Insight visuals · Summary cards, trend charts, selectors, and editors.
components/TrendCharts.tsx
Connections 24
- Dashboard → Dashboard shaping: reads · Shapes weekly insight records for display.
- Dashboard shaping → Supabase: queries · Loads weekly records, revisions, and stored context.
- Dashboard → Insight visuals: renders · Uses summary, trend, and week selection components.
- Dashboard → Chat panels: hosts · Provides chat and correction workflows.
- Insight chat → Supabase: updates · Stores chat turns, corrections, and revised analysis.
- Corrections API → Supabase: updates · Persists correction-driven revisions to weekly records.
- Run API → Weekly pipeline: triggers · Invokes the shared weekly execution path.
- Weekly pipeline → Metrics adapters: collects · Fetches metrics and search data from external sources.
- Weekly pipeline → Analysis layer: analyzes · Turns collected metrics into structured weekly insight.
- Analysis layer → LLM providers: calls · Uses provider-specific model access for generation.
- Weekly pipeline → Supabase: writes · Persists weekly insights and derived fields.
- Metrics adapters → Supabase: reads · Can use stored tokens, site metadata, or prior state.
- Growth page → Growth UI: renders · Shows opportunity list, action board, and weekly plan flow.
- Growth APIs → Growth planner: drives · Builds briefs, goals, plans, syncs, and revisions.
- Growth planner → LLM providers: calls · Uses the model layer to draft growth plans.
- Growth planner → Supabase: stores · Writes normalized growth tables and actions.
- Strategy page → Strategy UI: renders · Shows strategy planning, goals, and decision history.
- Strategy API → Strategy planner: drives · Generates strategy briefs, decisions, and revisions.
- Strategy planner → LLM providers: calls · Uses the model layer to draft strategy output.
- Strategy planner → Supabase: stores · Persists strategy state and history.
- Middleware → Login: permits · Protects access to authenticated application routes.
- Middleware → Run API: guards · Separates authenticated runs from secret-based automation.
- Login → Supabase: auth · Uses session and password-based access state.
- Growth APIs → Growth helpers: uses · Shares growth-state shaping and status logic.