# dhanumjayareddy/psyconstruct architecture

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

- Interactive diagram: https://gitdiagram.com/dhanumjayareddy/psyconstruct
- Repository: https://github.com/dhanumjayareddy/psyconstruct

## Overview

Psyconstruct is a research framework that turns smartphone sensor data into theory-mapped psychological construct scores. Its central workflow is sensor data → behavioral feature extraction → registry-guided aggregation and scores. Harmonization, configurable parameters, quality assessment, and provenance support that workflow. The README documents the four construct families and reproducibility capabilities; some subsystem connections are not shown in the sampled code, so those links are marked unverified or omitted.

Main entry points: [`constructs/aggregator.py`](https://github.com/dhanumjayareddy/psyconstruct/blob/main/constructs/aggregator.py) (Construct aggregator), [`config.py`](https://github.com/dhanumjayareddy/psyconstruct/blob/main/config.py) (Research configuration), [`preprocessing/harmonization.py`](https://github.com/dhanumjayareddy/psyconstruct/blob/main/preprocessing/harmonization.py) (Data harmonizer), [`features/behavioral_activation.py`](https://github.com/dhanumjayareddy/psyconstruct/blob/main/features/behavioral_activation.py) (Behavioral activation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_harmonizer["Data harmonizer<br/>[harmonization.py]"]
end

subgraph group_features["Feature extraction"]
  node_behavioral_activation["Behavioral activation"]
  node_avoidance["Avoidance<br/>[avoidance.py]"]
  node_social_engagement["Social engagement"]
  node_routine_stability["Routine stability"]
end

subgraph group_scoring["Construct scoring"]
  node_registry_loader["Registry loader<br/>[registry.py]"]
  node_registry_data["Construct registry<br/>[registry.json]"]
  node_aggregator["Construct aggregator<br/>[aggregator.py]"]
  node_construct_scores["Construct scores<br/>[aggregator.py]"]
end

subgraph group_research["Research support"]
  node_configuration["Research configuration<br/>[config.py]"]
  node_quality_assessment["Quality assessment"]
  node_provenance["Provenance tracking<br/>[provenance.py]"]
end

node_sensor_data(("Sensor data"))
node_researcher(("Researcher"))

node_sensor_data -->|"provides sensor data"| node_harmonizer
node_sensor_data -->|"provides raw data"| node_behavioral_activation
node_sensor_data -->|"provides raw data"| node_avoidance
node_sensor_data -->|"provides raw data"| node_social_engagement
node_sensor_data -->|"provides raw data"| node_routine_stability
node_harmonizer -.->|"may standardize inputs"| node_behavioral_activation
node_harmonizer -.->|"may standardize inputs"| node_avoidance
node_harmonizer -.->|"may standardize inputs"| node_social_engagement
node_harmonizer -.->|"may standardize inputs"| node_routine_stability
node_behavioral_activation -->|"supplies extracted features"| node_aggregator
node_avoidance -->|"supplies extracted features"| node_aggregator
node_social_engagement -->|"supplies extracted features"| node_aggregator
node_routine_stability -->|"supplies extracted features"| node_aggregator
node_aggregator -->|"reads definitions"| node_registry_loader
node_registry_loader -->|"loads registry"| node_registry_data
node_aggregator -->|"produces scores"| node_construct_scores
node_researcher -.->|"supplies"| node_sensor_data
node_construct_scores -.->|"returns results"| node_researcher
node_configuration -.->|"may configure"| node_behavioral_activation
node_configuration -.->|"may configure"| node_avoidance
node_configuration -.->|"may configure"| node_social_engagement
node_configuration -.->|"may configure"| node_routine_stability
node_configuration -.->|"may configure"| node_aggregator
node_behavioral_activation -->|"records operations"| node_provenance
node_avoidance -->|"records operations"| node_provenance
node_social_engagement -->|"records operations"| node_provenance
node_routine_stability -->|"records operations"| node_provenance
node_aggregator -->|"tracks aggregation"| node_provenance
node_aggregator -.->|"assesses quality"| node_quality_assessment

click node_harmonizer "https://github.com/dhanumjayareddy/psyconstruct/blob/main/preprocessing/harmonization.py"
click node_behavioral_activation "https://github.com/dhanumjayareddy/psyconstruct/blob/main/features/behavioral_activation.py"
click node_avoidance "https://github.com/dhanumjayareddy/psyconstruct/blob/main/features/avoidance.py"
click node_social_engagement "https://github.com/dhanumjayareddy/psyconstruct/blob/main/features/social_engagement.py"
click node_routine_stability "https://github.com/dhanumjayareddy/psyconstruct/blob/main/features/routine_stability.py"
click node_registry_loader "https://github.com/dhanumjayareddy/psyconstruct/blob/main/constructs/registry.py"
click node_registry_data "https://github.com/dhanumjayareddy/psyconstruct/blob/main/constructs/registry.json"
click node_aggregator "https://github.com/dhanumjayareddy/psyconstruct/blob/main/constructs/aggregator.py"
click node_construct_scores "https://github.com/dhanumjayareddy/psyconstruct/blob/main/constructs/aggregator.py"
click node_configuration "https://github.com/dhanumjayareddy/psyconstruct/blob/main/config.py"
click node_quality_assessment "https://github.com/dhanumjayareddy/psyconstruct/blob/main/utils/adaptive_quality.py"
click node_provenance "https://github.com/dhanumjayareddy/psyconstruct/blob/main/utils/provenance.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_harmonizer toneBlue
class node_behavioral_activation,node_avoidance,node_social_engagement,node_routine_stability toneAmber
class node_registry_loader,node_registry_data,node_aggregator,node_construct_scores toneMint
class node_configuration,node_quality_assessment,node_provenance toneRose
class node_sensor_data,node_researcher toneIndigo
```

## Components

### Data preparation

- [Data harmonizer](https://github.com/dhanumjayareddy/psyconstruct/blob/main/preprocessing/harmonization.py): `preprocessing/harmonization.py`

### Feature extraction

- [Behavioral activation](https://github.com/dhanumjayareddy/psyconstruct/blob/main/features/behavioral_activation.py): `features/behavioral_activation.py`
- [Avoidance](https://github.com/dhanumjayareddy/psyconstruct/blob/main/features/avoidance.py): `features/avoidance.py`
- [Social engagement](https://github.com/dhanumjayareddy/psyconstruct/blob/main/features/social_engagement.py): `features/social_engagement.py`
- [Routine stability](https://github.com/dhanumjayareddy/psyconstruct/blob/main/features/routine_stability.py): `features/routine_stability.py`

### Construct scoring

- [Registry loader](https://github.com/dhanumjayareddy/psyconstruct/blob/main/constructs/registry.py): `constructs/registry.py`
- [Construct registry](https://github.com/dhanumjayareddy/psyconstruct/blob/main/constructs/registry.json): `constructs/registry.json`
- [Construct aggregator](https://github.com/dhanumjayareddy/psyconstruct/blob/main/constructs/aggregator.py): `constructs/aggregator.py`
- [Construct scores](https://github.com/dhanumjayareddy/psyconstruct/blob/main/constructs/aggregator.py): `constructs/aggregator.py`

### Research support

- [Research configuration](https://github.com/dhanumjayareddy/psyconstruct/blob/main/config.py): `config.py`
- [Quality assessment](https://github.com/dhanumjayareddy/psyconstruct/blob/main/utils/adaptive_quality.py): `utils/adaptive_quality.py`
- [Provenance tracking](https://github.com/dhanumjayareddy/psyconstruct/blob/main/utils/provenance.py): `utils/provenance.py`

### Other components

- **Sensor data**
- **Researcher**

## Connections

- Sensor data → Data harmonizer: provides sensor data (evidence: `preprocessing/harmonization.py`)
- Sensor data → Behavioral activation: provides raw data (evidence: `README.md`)
- Sensor data → Avoidance: provides raw data (evidence: `README.md`)
- Sensor data → Social engagement: provides raw data (evidence: `README.md`)
- Sensor data → Routine stability: provides raw data (evidence: `README.md`)
- Data harmonizer → Behavioral activation: may standardize inputs
- Data harmonizer → Avoidance: may standardize inputs
- Data harmonizer → Social engagement: may standardize inputs
- Data harmonizer → Routine stability: may standardize inputs
- Behavioral activation → Construct aggregator: supplies extracted features (evidence: `README.md`)
- Avoidance → Construct aggregator: supplies extracted features (evidence: `README.md`)
- Social engagement → Construct aggregator: supplies extracted features (evidence: `README.md`)
- Routine stability → Construct aggregator: supplies extracted features (evidence: `README.md`)
- Construct aggregator → Registry loader: reads definitions (evidence: `constructs/aggregator.py`)
- Registry loader → Construct registry: loads registry (evidence: `constructs/registry.py`)
- Construct aggregator → Construct scores: produces scores (evidence: `README.md`)
- Researcher → Sensor data: supplies
- Construct scores → Researcher: returns results
- Research configuration → Behavioral activation: may configure
- Research configuration → Avoidance: may configure
- Research configuration → Social engagement: may configure
- Research configuration → Routine stability: may configure
- Research configuration → Construct aggregator: may configure
- Behavioral activation → Provenance tracking: records operations (evidence: `features/behavioral_activation.py`)
- Avoidance → Provenance tracking: records operations (evidence: `features/avoidance.py`)
- Social engagement → Provenance tracking: records operations (evidence: `features/social_engagement.py`)
- Routine stability → Provenance tracking: records operations (evidence: `features/routine_stability.py`)
- Construct aggregator → Provenance tracking: tracks aggregation (evidence: `constructs/aggregator.py`)
- Construct aggregator → Quality assessment: assesses quality
