# ibalajisivarajan/doomscroll-bias architecture

> Architecture diagram of the GitHub repository ibalajisivarajan/doomscroll-bias, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibalajisivarajan/doomscroll-bias
- Repository: https://github.com/ibalajisivarajan/doomscroll-bias
- Video tour (about a minute): https://gitdiagram.com/ibalajisivarajan/doomscroll-bias/video

## Overview

This repository implements a preregistered paired-vignette audit of LLM judgments about doomscrolling-related relationship conflict. The main workflow expands frozen vignette variants into model requests, caches responses, scores them, then runs statistical analysis and quality checks. Separate validation and finalization stages support blinded human coding, release readiness, and archival publication; a display-only Notion sync reports study progress. The map follows README capabilities and sampled source; some final release wiring is documented only indirectly, so uncertain orchestration links are omitted.

Main entry points: [`src/finalize_study.py`](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/finalize_study.py) (Study finalization), [`src/run.py`](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/run.py) (Task collection), [`results/tables`](https://github.com/ibalajisivarajan/doomscroll-bias/tree/main/results/tables) (Scored responses), [`src/notion_sync.py`](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/notion_sync.py) (Dashboard sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_study_design["Study design"]
  node_protocol["Study protocol<br/>[protocol.yaml]"]
  node_vignettes["Vignette set<br/>[vignettes.jsonl]"]
  node_control_key["Control key"]
end

subgraph group_collection["Collection"]
  node_collector["Task collection<br/>[run.py]"]
  node_models{{"LLM endpoints"}}
  node_raw_cache[("Raw response cache")]
  node_daily_caps[("Daily quota counts")]
end

subgraph group_analysis["Scoring and analysis"]
  node_scorer["Response scoring<br/>[score.py]"]
  node_scored[("Scored responses")]
  node_analysis_engine["Statistical analysis<br/>[analyze.py]"]
  node_analysis_outputs["Study results"]
end

subgraph group_validation["Validation and release"]
  node_control_check["Control QC<br/>[control_check.py]"]
  node_manual_sample["Validation sampling"]
  node_manual_files["Manual coding files"]
  node_agreement["Agreement analysis"]
  node_finalizer["Study finalization<br/>[finalize_study.py]"]
  node_frozen_release["Frozen release records"]
  node_zenodo_release["Zenodo publisher<br/>[zenodo_release.py]"]
end

subgraph group_operations["Operations"]
  node_notion_sync["Dashboard sync<br/>[notion_sync.py]"]
  node_notion{{"Notion dashboard"}}
end

node_researcher(("Researcher"))
node_human_coder(("Human coder"))
node_zenodo{{"Zenodo archive"}}

node_researcher -->|"defines study"| node_protocol
node_researcher -->|"starts collection"| node_collector
node_collector -->|"reads design"| node_protocol
node_collector -->|"loads variants"| node_vignettes
node_collector -->|"sends prompts"| node_models
node_models -->|"returns judgments"| node_collector
node_collector -->|"writes responses"| node_raw_cache
node_collector -->|"tracks requests"| node_daily_caps
node_scorer -->|"reads responses"| node_raw_cache
node_scorer -->|"reads scoring rules"| node_protocol
node_scorer -->|"writes scores"| node_scored
node_analysis_engine -->|"reads scores"| node_scored
node_analysis_engine -->|"reads statistics plan"| node_protocol
node_analysis_engine -->|"writes findings"| node_analysis_outputs
node_control_check -->|"reads scores"| node_scored
node_control_check -->|"reads criteria"| node_control_key
node_control_check -->|"writes QC summary"| node_analysis_outputs
node_manual_sample -->|"samples responses"| node_scored
node_manual_sample -->|"writes worksheet"| node_manual_files
node_human_coder -->|"adds labels"| node_manual_files
node_agreement -->|"reads labels"| node_manual_files
node_agreement -->|"writes agreement"| node_frozen_release
node_finalizer -->|"checks completion"| node_raw_cache
node_finalizer -->|"runs scoring"| node_scorer
node_finalizer -->|"runs QC"| node_control_check
node_finalizer -->|"creates sample"| node_manual_sample
node_finalizer -->|"runs analysis"| node_analysis_engine
node_finalizer -->|"checks coding gate"| node_manual_files
node_finalizer -->|"writes manifests"| node_frozen_release
node_notion_sync -->|"counts responses"| node_raw_cache
node_notion_sync -->|"summarizes scores"| node_scored
node_notion_sync -->|"reads QC state"| node_analysis_outputs
node_notion_sync -.->|"updates dashboard"| node_notion
node_researcher -.->|"publishes release"| node_zenodo_release
node_zenodo_release -->|"uploads archive"| node_zenodo

click node_protocol "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/config/protocol.yaml"
click node_vignettes "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/data/vignettes.jsonl"
click node_control_key "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/config/control_answer_key.json"
click node_collector "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/run.py"
click node_raw_cache "https://github.com/ibalajisivarajan/doomscroll-bias/tree/main/results/raw"
click node_daily_caps "https://github.com/ibalajisivarajan/doomscroll-bias/tree/main/results"
click node_scorer "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/score.py"
click node_scored "https://github.com/ibalajisivarajan/doomscroll-bias/tree/main/results/tables"
click node_analysis_engine "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/analyze.py"
click node_analysis_outputs "https://github.com/ibalajisivarajan/doomscroll-bias/tree/main/results/tables"
click node_control_check "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/control_check.py"
click node_manual_sample "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/sample_manual_validation.py"
click node_manual_files "https://github.com/ibalajisivarajan/doomscroll-bias/tree/main/results/tables"
click node_agreement "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/manual_validation_agreement.py"
click node_finalizer "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/finalize_study.py"
click node_notion_sync "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/notion_sync.py"
click node_zenodo_release "https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/zenodo_release.py"

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_protocol,node_vignettes,node_control_key toneBlue
class node_collector,node_models,node_raw_cache,node_daily_caps toneAmber
class node_scorer,node_scored,node_analysis_engine,node_analysis_outputs toneMint
class node_control_check,node_manual_sample,node_manual_files,node_agreement,node_finalizer,node_frozen_release,node_zenodo_release toneRose
class node_notion_sync,node_notion,node_researcher,node_human_coder,node_zenodo toneIndigo
```

## Components

### Study design

- [Study protocol](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/config/protocol.yaml): `config/protocol.yaml`
- [Vignette set](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/data/vignettes.jsonl): `data/vignettes.jsonl`
- [Control key](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/config/control_answer_key.json): `config/control_answer_key.json`

### Collection

- [Task collection](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/run.py): `src/run.py`
- **LLM endpoints**
- [Raw response cache](https://github.com/ibalajisivarajan/doomscroll-bias/tree/main/results/raw): `results/raw`
- [Daily quota counts](https://github.com/ibalajisivarajan/doomscroll-bias/tree/main/results): `results`

### Scoring and analysis

- [Response scoring](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/score.py): `src/score.py`
- [Scored responses](https://github.com/ibalajisivarajan/doomscroll-bias/tree/main/results/tables): `results/tables`
- [Statistical analysis](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/analyze.py): `src/analyze.py`
- [Study results](https://github.com/ibalajisivarajan/doomscroll-bias/tree/main/results/tables): `results/tables`

### Validation and release

- [Control QC](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/control_check.py): `src/control_check.py`
- [Validation sampling](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/sample_manual_validation.py): `src/sample_manual_validation.py`
- [Manual coding files](https://github.com/ibalajisivarajan/doomscroll-bias/tree/main/results/tables): `results/tables`
- [Agreement analysis](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/manual_validation_agreement.py): `src/manual_validation_agreement.py`
- [Study finalization](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/finalize_study.py): `src/finalize_study.py`
- **Frozen release records**
- [Zenodo publisher](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/zenodo_release.py): `src/zenodo_release.py`

### Operations

- [Dashboard sync](https://github.com/ibalajisivarajan/doomscroll-bias/blob/main/src/notion_sync.py): `src/notion_sync.py`
- **Notion dashboard**

### Other components

- **Researcher**
- **Human coder**
- **Zenodo archive**

## Connections

- Researcher → Study protocol: defines study
- Researcher → Task collection: starts collection
- Task collection → Study protocol: reads design
- Task collection → Vignette set: loads variants
- Task collection → LLM endpoints: sends prompts
- LLM endpoints → Task collection: returns judgments
- Task collection → Raw response cache: writes responses
- Task collection → Daily quota counts: tracks requests
- Response scoring → Raw response cache: reads responses
- Response scoring → Study protocol: reads scoring rules
- Response scoring → Scored responses: writes scores
- Statistical analysis → Scored responses: reads scores
- Statistical analysis → Study protocol: reads statistics plan
- Statistical analysis → Study results: writes findings
- Control QC → Scored responses: reads scores
- Control QC → Control key: reads criteria
- Control QC → Study results: writes QC summary
- Validation sampling → Scored responses: samples responses
- Validation sampling → Manual coding files: writes worksheet
- Human coder → Manual coding files: adds labels
- Agreement analysis → Manual coding files: reads labels
- Agreement analysis → Frozen release records: writes agreement
- Study finalization → Raw response cache: checks completion
- Study finalization → Response scoring: runs scoring
- Study finalization → Control QC: runs QC
- Study finalization → Validation sampling: creates sample
- Study finalization → Statistical analysis: runs analysis
- Study finalization → Manual coding files: checks coding gate
- Study finalization → Frozen release records: writes manifests
- Dashboard sync → Raw response cache: counts responses
- Dashboard sync → Scored responses: summarizes scores
- Dashboard sync → Study results: reads QC state
- Dashboard sync → Notion dashboard: updates dashboard
- Researcher → Zenodo publisher: publishes release
- Zenodo publisher → Zenodo archive: uploads archive