How cavart/revenue-decay-analyser works
Project type + purpose (what you’re diagramming)
This repository is a Python data/analytics pipeline tool (not a long-running service). Its purpose is to help SEO teams detect page-level organic “revenue/click decay” by:
• Extracting monthly data from GA4 and GSC
• Building a historical panel from stored monthly chunks
• Applying de-seasonalization (by page_type × month_of_year)
• Computing robust trend slopes (Theil–Sen with fallback)
• Producing decay risk scores
• Exporting charts + PPTX “attention pack”
The “system” is therefore best represented as a batch pipeline with multiple steps, inputs/outputs, and external dependencies (Google APIs + local storage + exported artifacts).
File tree cues → architectural decomposition
Key structural signals:
• scripts/
Thin CLI entrypoints for operators (“run X”). These are your execution triggers.
• src/pipelines/
The actual pipeline implementations; each file corresponds to one stage:
• ga4_organic_seo_extract.py
• gsc_organic_page_extract.py
• revenue_decay_chunked_pull.py
• revenue_decay_model_input.py
• revenue_decay_scoring.py
• revenue_decay_chart_pack.py
• revenue_decay_monthly_run.py (the orchestrator)
• src/common/config.py
• .env.example + README mention of secrets/
Indicates environment-driven config and credential files. Even if secrets/ isn’t in the repo tree, it’s an important runtime dependency.
• docs/*.md
Operational manuals. Use them to confirm intermediate artifacts and the operator workflow; they often imply storage formats/locations and run sequences.
What the README implies about runtime flow
The README’s “One Command (Monthly)” establishes a canonical orchestrated run:
scripts/run_revenue_decay_monthly_run.py --history-start-date ...
Scoring stage reads Model Input → outputs “Decay Risk Scores”
10. Chart Pack stage reads Scores (+ possibly Model Input/Historical Panel) → outputs Charts + PPTX
Architectural patterns/design principles visible here
• Pipeline / staged batch processing (each stage is its own module)
• Orchestration via a single “monthly run” entrypoint
• Idempotent-ish incremental data approach (“stored monthly chunks” suggests append/refresh strategy)
• Separation of concerns:
• extraction (API I/O)
• data assembly (panel build)
• transformation (de-seasonalize)
• analytics (robust slope)
• presentation (charts/PPTX)
• Configuration boundary (environment + secrets decoupled from code)
Relevant technologies/frameworks/libraries
• Python runtime
• Google Analytics 4 (GA4) API
• Google Search Console (GSC) API
• Statistical method: Theil–Sen slope estimator (+ fallback)
• Outputs: charts and PPTX generation (label generically if library not known)
Practical “don’t overthink it” approach: separate into many components
To maximize detail without getting lost: