# keirancpflynn/llmnesia-insights architecture

> Architecture diagram of the GitHub repository keirancpflynn/llmnesia-insights, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keirancpflynn/llmnesia-insights
- Repository: https://github.com/keirancpflynn/llmnesia-insights

## Overview

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: [`src/supabase.ts`](https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/supabase.ts) (Supabase), [`src/pipeline.ts`](https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/pipeline.ts) (Weekly pipeline), [`app/page.tsx`](https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/page.tsx) (Dashboard), [`src/growth-plan.ts`](https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/growth-plan.ts) (Growth planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_app_home["Dashboard<br/>page<br/>[page.tsx]"]
  node_app_growth["Growth page<br/>[page.tsx]"]
  node_app_strategy["Strategy page<br/>[page.tsx]"]
  node_app_login["Login<br/>auth page<br/>[page.tsx]"]
  node_api_run["Run API<br/>pipeline trigger<br/>[route.ts]"]
  node_api_chat["Insight chat<br/>analysis API<br/>[route.ts]"]
  node_api_corrections["Corrections API<br/>analysis API<br/>[route.ts]"]
  node_api_growth["Growth APIs<br/>workflow API"]
  node_api_strategy["Strategy API<br/>workflow API<br/>[route.ts]"]
  node_middleware["Middleware<br/>access control<br/>[middleware.ts]"]
end

subgraph group_pipeline["Pipeline"]
  node_pipeline_main["Weekly pipeline<br/>orchestration<br/>[pipeline.ts]"]
  node_collectors["Metrics adapters<br/>ingestion<br/>[posthog.ts]"]
  node_analysis["Analysis layer<br/>prompt engine<br/>[analyse.ts]"]
  node_llm["LLM providers<br/>model gateway<br/>[llm.ts]"]
  node_growth_engine["Growth planner<br/>opportunity engine<br/>[growth-plan.ts]"]
  node_strategy_engine["Strategy planner<br/>strategy engine<br/>[strategy.ts]"]
end

subgraph group_data["Data layer"]
  node_supabase[("Supabase<br/>storage<br/>[supabase.ts]")]
  node_dashboard_lib["Dashboard shaping<br/>read model<br/>[dashboard.ts]"]
  node_growth_lib["Growth helpers<br/>domain model<br/>[growth.ts]"]
end

subgraph group_ui["UI kit"]
  node_chat_ui["Chat panels<br/>ui<br/>[ChatPanel.tsx]"]
  node_growth_ui["Growth UI"]
  node_strategy_ui["Strategy UI<br/>[StrategyPanel.tsx]"]
  node_charts_ui["Insight visuals<br/>ui<br/>[TrendCharts.tsx]"]
end

node_app_home -->|"reads"| node_dashboard_lib
node_dashboard_lib -->|"queries"| node_supabase
node_app_home -->|"renders"| node_charts_ui
node_app_home -->|"hosts"| node_chat_ui
node_api_chat -->|"updates"| node_supabase
node_api_corrections -->|"updates"| node_supabase
node_api_run -->|"triggers"| node_pipeline_main
node_pipeline_main -->|"collects"| node_collectors
node_pipeline_main -->|"analyzes"| node_analysis
node_analysis -->|"calls"| node_llm
node_pipeline_main -->|"writes"| node_supabase
node_collectors -->|"reads"| node_supabase
node_app_growth -->|"renders"| node_growth_ui
node_api_growth -->|"drives"| node_growth_engine
node_growth_engine -->|"calls"| node_llm
node_growth_engine -->|"stores"| node_supabase
node_app_strategy -->|"renders"| node_strategy_ui
node_api_strategy -->|"drives"| node_strategy_engine
node_strategy_engine -->|"calls"| node_llm
node_strategy_engine -->|"stores"| node_supabase
node_middleware -->|"permits"| node_app_login
node_middleware -->|"guards"| node_api_run
node_app_login -->|"auth"| node_supabase
node_api_growth -->|"uses"| node_growth_lib

click node_app_home "https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/page.tsx"
click node_app_growth "https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/growth/page.tsx"
click node_app_strategy "https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/strategy/page.tsx"
click node_app_login "https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/login/page.tsx"
click node_api_run "https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/api/run/route.ts"
click node_api_chat "https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/api/chat/route.ts"
click node_api_corrections "https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/api/corrections/route.ts"
click node_api_strategy "https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/api/strategy/route.ts"
click node_middleware "https://github.com/keirancpflynn/llmnesia-insights/blob/main/middleware.ts"
click node_pipeline_main "https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/pipeline.ts"
click node_collectors "https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/posthog.ts"
click node_analysis "https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/analyse.ts"
click node_llm "https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/llm.ts"
click node_growth_engine "https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/growth-plan.ts"
click node_strategy_engine "https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/strategy.ts"
click node_supabase "https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/supabase.ts"
click node_dashboard_lib "https://github.com/keirancpflynn/llmnesia-insights/blob/main/lib/dashboard.ts"
click node_growth_lib "https://github.com/keirancpflynn/llmnesia-insights/blob/main/lib/growth.ts"
click node_chat_ui "https://github.com/keirancpflynn/llmnesia-insights/blob/main/components/ChatPanel.tsx"
click node_growth_ui "https://github.com/keirancpflynn/llmnesia-insights/blob/main/components/GrowthDashboard.tsx"
click node_strategy_ui "https://github.com/keirancpflynn/llmnesia-insights/blob/main/components/StrategyPanel.tsx"
click node_charts_ui "https://github.com/keirancpflynn/llmnesia-insights/blob/main/components/TrendCharts.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_home,node_app_growth,node_app_strategy,node_app_login,node_api_run,node_api_chat,node_api_corrections,node_api_growth,node_api_strategy,node_middleware toneBlue
class node_pipeline_main,node_collectors,node_analysis,node_llm,node_growth_engine,node_strategy_engine toneAmber
class node_supabase,node_dashboard_lib,node_growth_lib toneMint
class node_chat_ui,node_growth_ui,node_strategy_ui,node_charts_ui toneRose
```

## Components

### Web app

Dashboard, planner, strategy, login, and route handlers.

- [Dashboard](https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/page.tsx): page · Weekly insights entry point and primary read model. · `app/page.tsx`
- [Growth page](https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/growth/page.tsx): page · SEO and traffic opportunity planning surface. · `app/growth/page.tsx`
- [Strategy page](https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/strategy/page.tsx): page · Monetization and product strategy surface. · `app/strategy/page.tsx`
- [Login](https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/login/page.tsx): auth page · Password-based access gate. · `app/login/page.tsx`
- [Run API](https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/api/run/route.ts): pipeline trigger · Button or cron entry point that launches the weekly pipeline. · `app/api/run/route.ts`
- [Insight chat](https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/api/chat/route.ts): analysis API · Chat and correction loop for weekly insights. · `app/api/chat/route.ts`
- [Corrections API](https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/api/corrections/route.ts): analysis API · Applies structured revisions to stored weekly analysis. · `app/api/corrections/route.ts`
- **Growth APIs**: workflow API · Growth brief, goal, plan, revise, sync, chat, and actions endpoints.
- [Strategy API](https://github.com/keirancpflynn/llmnesia-insights/blob/main/app/api/strategy/route.ts): workflow API · Strategy chat, goal, decision, and revise endpoints. · `app/api/strategy/route.ts`
- [Middleware](https://github.com/keirancpflynn/llmnesia-insights/blob/main/middleware.ts): access control · Protects authenticated routes and runtime entry points. · `middleware.ts`

### Pipeline

Shared collection, analysis, and write path for weekly insight generation.

- [Weekly pipeline](https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/pipeline.ts): orchestration · Shared collect → analyse → save workflow. · `src/pipeline.ts`
- [Metrics adapters](https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/posthog.ts): ingestion · PostHog, GA4, GSC, and Bing ingestion adapters. · `src/posthog.ts`
- [Analysis layer](https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/analyse.ts): prompt engine · Briefing, analysis, strategy, and growth-plan generation. · `src/analyse.ts`
- [LLM providers](https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/llm.ts): model gateway · Provider and model selection across Claude, DeepSeek, and OpenAI. · `src/llm.ts`
- [Growth planner](https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/growth-plan.ts): opportunity engine · Ranks opportunities and drafts weekly growth plans. · `src/growth-plan.ts`
- [Strategy planner](https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/strategy.ts): strategy engine · Generates week-aware product and revenue strategy. · `src/strategy.ts`

### Data layer

Supabase-backed persistence and local shaping helpers.

- [Supabase](https://github.com/keirancpflynn/llmnesia-insights/blob/main/src/supabase.ts): storage · Persistent store for weekly insights and growth/strategy state. · `src/supabase.ts`
- [Dashboard shaping](https://github.com/keirancpflynn/llmnesia-insights/blob/main/lib/dashboard.ts): read model · Flattens weekly records into chart- and view-friendly data. · `lib/dashboard.ts`
- [Growth helpers](https://github.com/keirancpflynn/llmnesia-insights/blob/main/lib/growth.ts): domain model · Shared growth-state shaping and status logic. · `lib/growth.ts`

### UI kit

Reusable panels, cards, selectors, and editors.

- [Chat panels](https://github.com/keirancpflynn/llmnesia-insights/blob/main/components/ChatPanel.tsx): ui · Reusable chat and correction interfaces. · `components/ChatPanel.tsx`
- [Growth UI](https://github.com/keirancpflynn/llmnesia-insights/blob/main/components/GrowthDashboard.tsx): ui · Growth dashboard, opportunities, action board, and plan views. · `components/GrowthDashboard.tsx`
- [Strategy UI](https://github.com/keirancpflynn/llmnesia-insights/blob/main/components/StrategyPanel.tsx): ui · Strategy panel, goal editor, and chat surface. · `components/StrategyPanel.tsx`
- [Insight visuals](https://github.com/keirancpflynn/llmnesia-insights/blob/main/components/TrendCharts.tsx): ui · Summary cards, trend charts, selectors, and editors. · `components/TrendCharts.tsx`

## Connections

- 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.