# bis-med-it/marco-bis architecture

> Architecture diagram of the GitHub repository bis-med-it/marco-bis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bis-med-it/marco-bis
- Repository: https://github.com/bis-med-it/marco-bis

## Overview

MaRCo@BIS is an AI-assisted macroeconometric research framework, combining a human-confirmed research workflow with a Python estimation library and canonical replications. The main journey is a researcher’s question through mode triage, model/specification decisions, data preparation, estimation, diagnostics, and reporting; users can then curate or continue the work. The README documents the workflow and broader capabilities; source-level edges below are limited to relationships visible in excerpts or the source index, so unsampled integrations are not inferred.

Main entry points: [`scripts/lib/data/loader.py`](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/data/loader.py) (Dataset loading), [`skills/orchestrator/SKILL.md`](https://github.com/bis-med-it/marco-bis/blob/main/skills/orchestrator/SKILL.md) (Mode triage), [`scripts/lib/data/fetcher.py`](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/data/fetcher.py) (Fetch and cache), [`scripts/lib/identification.py`](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/identification.py) (Shock identification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Research workflow"]
  node_knowledge["Knowledge context"]
  node_triage["Mode triage<br/>[SKILL.md]"]
  node_model_entry["Model or paper entry"]
  node_specification["Specification<br/>[specs.py]"]
  node_human_gates["Confirmation gates<br/>[SKILL.md]"]
end

subgraph group_data["Data and preparation"]
  node_data_sources["Data sources"]
  node_fetching["Fetch and cache<br/>[fetcher.py]"]
  node_dataset_registry[("Dataset registry<br/>[registry.py]")]
  node_dataset_loading["Dataset loading<br/>[loader.py]"]
  node_transforms["Transforms<br/>[transforms.py]"]
  node_preprocessing["Preprocessing"]
end

subgraph group_analysis["Econometric analysis"]
  node_var_models["VAR and BVAR<br/>[var.py]"]
  node_advanced_models["Advanced models"]
  node_identification["Shock identification<br/>[identification.py]"]
  node_inference["IRF inference<br/>[inference.py]"]
  node_forecasting["Forecasting<br/>[forecast.py]"]
end

subgraph group_results["Results and curation"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
  node_sensitivity["Sensitivity checks<br/>[sensitivity.py]"]
  node_reporting["Reports<br/>[report.py]"]
  node_replications["Canonical replications"]
  node_disposition["Disposition and curation"]
end

node_researcher(("Researcher"))
node_claude(("Claude Code agent"))

node_researcher -->|"asks question"| node_claude
node_claude -->|"loads context"| node_knowledge
node_claude -->|"triages mode"| node_triage
node_triage -->|"retrieves or drafts"| node_model_entry
node_triage -->|"designs specification"| node_specification
node_specification -->|"requests confirmation"| node_human_gates
node_human_gates -->|"confirms decisions"| node_researcher
node_claude -->|"selects data"| node_data_sources
node_data_sources -.->|"provides series"| node_fetching
node_fetching -->|"registers dataset"| node_dataset_registry
node_fetching -->|"provides cached data"| node_dataset_loading
node_dataset_loading -->|"reads registry"| node_dataset_registry
node_dataset_loading -->|"uses transforms"| node_transforms
node_dataset_loading -.->|"prepares data"| node_preprocessing
node_claude -->|"loads data"| node_dataset_loading
node_claude -->|"runs estimation"| node_var_models
node_claude -.->|"runs estimation"| node_advanced_models
node_var_models -->|"supplies VAR fit"| node_identification
node_identification -->|"draws uncertainty"| node_inference
node_identification -->|"uses VAR utilities"| node_var_models
node_claude -.->|"forecasts"| node_forecasting
node_claude -->|"checks results"| node_diagnostics
node_claude -->|"tests sensitivity"| node_sensitivity
node_diagnostics -.->|"summarizes findings"| node_reporting
node_claude -->|"generates report"| node_reporting
node_model_entry -->|"selects replication"| node_replications
node_claude -->|"runs script"| node_replications
node_reporting -->|"presents results"| node_researcher
node_researcher -->|"chooses disposition"| node_disposition

click node_knowledge "https://github.com/bis-med-it/marco-bis/tree/main/skills"
click node_triage "https://github.com/bis-med-it/marco-bis/blob/main/skills/orchestrator/SKILL.md"
click node_model_entry "https://github.com/bis-med-it/marco-bis/tree/main/skills/model-dictionary/entries"
click node_specification "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/specs.py"
click node_human_gates "https://github.com/bis-med-it/marco-bis/blob/main/skills/orchestrator/SKILL.md"
click node_data_sources "https://github.com/bis-med-it/marco-bis/tree/main/scripts/lib/data/fetchers"
click node_fetching "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/data/fetcher.py"
click node_dataset_registry "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/data/registry.py"
click node_dataset_loading "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/data/loader.py"
click node_transforms "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/data/transforms.py"
click node_preprocessing "https://github.com/bis-med-it/marco-bis/tree/main/scripts/lib/preprocess"
click node_var_models "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/var.py"
click node_advanced_models "https://github.com/bis-med-it/marco-bis/tree/main/scripts/lib"
click node_identification "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/identification.py"
click node_inference "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/inference.py"
click node_forecasting "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/forecast.py"
click node_diagnostics "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/diagnostics.py"
click node_sensitivity "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/sensitivity.py"
click node_reporting "https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/report.py"
click node_replications "https://github.com/bis-med-it/marco-bis/tree/main/scripts/replications"
click node_disposition "https://github.com/bis-med-it/marco-bis/tree/main/skills"

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_knowledge,node_triage,node_model_entry,node_specification,node_human_gates toneBlue
class node_data_sources,node_fetching,node_dataset_registry,node_dataset_loading,node_transforms,node_preprocessing toneAmber
class node_var_models,node_advanced_models,node_identification,node_inference,node_forecasting toneMint
class node_diagnostics,node_sensitivity,node_reporting,node_replications,node_disposition toneRose
class node_researcher,node_claude toneIndigo
```

## Components

### Research workflow

- [Knowledge context](https://github.com/bis-med-it/marco-bis/tree/main/skills): `skills`
- [Mode triage](https://github.com/bis-med-it/marco-bis/blob/main/skills/orchestrator/SKILL.md): `skills/orchestrator/SKILL.md`
- [Model or paper entry](https://github.com/bis-med-it/marco-bis/tree/main/skills/model-dictionary/entries): `skills/model-dictionary/entries`
- [Specification](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/specs.py): `scripts/lib/specs.py`
- [Confirmation gates](https://github.com/bis-med-it/marco-bis/blob/main/skills/orchestrator/SKILL.md): `skills/orchestrator/SKILL.md`

### Data and preparation

- [Data sources](https://github.com/bis-med-it/marco-bis/tree/main/scripts/lib/data/fetchers): `scripts/lib/data/fetchers`
- [Fetch and cache](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/data/fetcher.py): `scripts/lib/data/fetcher.py`
- [Dataset registry](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/data/registry.py): `scripts/lib/data/registry.py`
- [Dataset loading](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/data/loader.py): `scripts/lib/data/loader.py`
- [Transforms](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/data/transforms.py): `scripts/lib/data/transforms.py`
- [Preprocessing](https://github.com/bis-med-it/marco-bis/tree/main/scripts/lib/preprocess): `scripts/lib/preprocess`

### Econometric analysis

- [VAR and BVAR](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/var.py): `scripts/lib/var.py`
- [Advanced models](https://github.com/bis-med-it/marco-bis/tree/main/scripts/lib): `scripts/lib`
- [Shock identification](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/identification.py): `scripts/lib/identification.py`
- [IRF inference](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/inference.py): `scripts/lib/inference.py`
- [Forecasting](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/forecast.py): `scripts/lib/forecast.py`

### Results and curation

- [Diagnostics](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/diagnostics.py): `scripts/lib/diagnostics.py`
- [Sensitivity checks](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/sensitivity.py): `scripts/lib/sensitivity.py`
- [Reports](https://github.com/bis-med-it/marco-bis/blob/main/scripts/lib/report.py): `scripts/lib/report.py`
- [Canonical replications](https://github.com/bis-med-it/marco-bis/tree/main/scripts/replications): `scripts/replications`
- [Disposition and curation](https://github.com/bis-med-it/marco-bis/tree/main/skills): `skills`

### Other components

- **Researcher**
- **Claude Code agent**

## Connections

- Researcher → Claude Code agent: asks question (evidence: `README.md`)
- Claude Code agent → Knowledge context: loads context (evidence: `README.md`)
- Claude Code agent → Mode triage: triages mode (evidence: `README.md`)
- Mode triage → Model or paper entry: retrieves or drafts (evidence: `README.md`)
- Mode triage → Specification: designs specification (evidence: `README.md`)
- Specification → Confirmation gates: requests confirmation (evidence: `README.md`)
- Confirmation gates → Researcher: confirms decisions (evidence: `README.md`)
- Claude Code agent → Data sources: selects data (evidence: `README.md`)
- Data sources → Fetch and cache: provides series (evidence: `README.md`)
- Fetch and cache → Dataset registry: registers dataset (evidence: `scripts/lib/data/fetcher.py`)
- Fetch and cache → Dataset loading: provides cached data (evidence: `scripts/lib/data/fetcher.py`)
- Dataset loading → Dataset registry: reads registry (evidence: `scripts/lib/data/loader.py`)
- Dataset loading → Transforms: uses transforms (evidence: `scripts/lib/data/loader.py`)
- Dataset loading → Preprocessing: prepares data
- Claude Code agent → Dataset loading: loads data (evidence: `README.md`)
- Claude Code agent → VAR and BVAR: runs estimation (evidence: `README.md`)
- Claude Code agent → Advanced models: runs estimation (evidence: `README.md`)
- VAR and BVAR → Shock identification: supplies VAR fit (evidence: `scripts/lib/identification.py`)
- Shock identification → IRF inference: draws uncertainty (evidence: `scripts/lib/identification.py`)
- Shock identification → VAR and BVAR: uses VAR utilities (evidence: `scripts/lib/identification.py`)
- Claude Code agent → Forecasting: forecasts (evidence: `README.md`)
- Claude Code agent → Diagnostics: checks results (evidence: `README.md`)
- Claude Code agent → Sensitivity checks: tests sensitivity (evidence: `README.md`)
- Diagnostics → Reports: summarizes findings (evidence: `scripts/lib/report.py`)
- Claude Code agent → Reports: generates report (evidence: `README.md`)
- Model or paper entry → Canonical replications: selects replication (evidence: `README.md`)
- Claude Code agent → Canonical replications: runs script (evidence: `README.md`)
- Reports → Researcher: presents results (evidence: `README.md`)
- Researcher → Disposition and curation: chooses disposition (evidence: `README.md`)