# raghuram1811/psychetrajectory architecture

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

- Interactive diagram: https://gitdiagram.com/raghuram1811/psychetrajectory
- Repository: https://github.com/raghuram1811/psychetrajectory
- Video tour (about a minute): https://gitdiagram.com/raghuram1811/psychetrajectory/video

## Overview

PsycheTrajectory combines an interactive wellbeing-pattern concept app with a Python research backend for simulated observations and exploratory trajectory modeling. The backend workflow generates or ingests observations, validates and aggregates them into daily features, trains an encoder, filters latent trajectories, and can evaluate or replay outputs. The README also describes shared human reflection and uncertainty as product goals; sampled app source confirms a front-end prototype, but not its internal UI stages. The app has no configured D1 tables. Backend relationships shown here are limited to caller references in the SOURCE INDEX and sampled excerpts.

Main entry points: [`backend/src/psychetrajectory/cli.py`](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/cli.py) (Research CLI), [`backend/src/psychetrajectory/pipeline.py`](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/pipeline.py) (Training and replay), [`backend/src/psychetrajectory/schema.py`](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/schema.py) (Data contracts), [`backend/src/psychetrajectory/heads.py`](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/heads.py) (Symptom heads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Concept app"]
  node_app["Interactive simulator<br/>[page.tsx]"]
  node_app_shell["App shell<br/>[layout.tsx]"]
  node_auth["ChatGPT auth<br/>[chatgpt-auth.ts]"]
  node_db_access["D1 access helper<br/>[index.ts]"]
  node_empty_schema["Empty app schema<br/>[schema.ts]"]
end

subgraph group_data["Observation pipeline"]
  node_synthetic["Synthetic signals<br/>[synthetic.py]"]
  node_io["Observation I/O<br/>[io.py]"]
  node_schema["Data contracts<br/>[schema.py]"]
  node_preprocessing["Daily features<br/>[preprocessing.py]"]
end

subgraph group_model["Trajectory modeling"]
  node_encoder["Masked encoder<br/>[encoder.py]"]
  node_kalman["Trend filter<br/>[kalman.py]"]
  node_inference["Window inference<br/>[inference.py]"]
  node_heads["Symptom heads<br/>[heads.py]"]
  node_api["Inference API<br/>[api.py]"]
end

subgraph group_research["Research workflows"]
  node_backend_cli["Research CLI<br/>[cli.py]"]
  node_splits["Subject splits<br/>[splits.py]"]
  node_pipeline["Training and replay<br/>[pipeline.py]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
end

node_person(("Person or clinician"))
node_d1[("Cloudflare D1")]

node_person -->|"explores patterns"| node_app
node_app_shell -.->|"renders"| node_app
node_backend_cli -->|"generates data"| node_synthetic
node_backend_cli -->|"reads and writes"| node_io
node_backend_cli -->|"trains or replays"| node_pipeline
node_backend_cli -->|"preprocesses"| node_preprocessing
node_backend_cli -->|"evaluates"| node_diagnostics
node_backend_cli -->|"trains heads"| node_heads
node_io -->|"uses types"| node_schema
node_synthetic -->|"creates observations"| node_schema
node_preprocessing -->|"uses types"| node_schema
node_pipeline -->|"aggregates features"| node_preprocessing
node_pipeline -->|"splits subjects"| node_splits
node_pipeline -->|"trains and embeds"| node_encoder
node_pipeline -->|"uses heads"| node_heads
node_pipeline -->|"filters latents"| node_kalman
node_heads -->|"uses labels"| node_schema
node_heads -->|"splits subjects"| node_splits
node_inference -->|"updates state"| node_kalman
node_inference -->|"returns result"| node_schema
node_api -->|"uses filter"| node_kalman
node_api -->|"uses contracts"| node_schema
node_db_access -->|"connects to"| node_d1
node_db_access -->|"configures ORM"| node_empty_schema

click node_app "https://github.com/raghuram1811/psychetrajectory/blob/main/app/page.tsx"
click node_app_shell "https://github.com/raghuram1811/psychetrajectory/blob/main/app/layout.tsx"
click node_auth "https://github.com/raghuram1811/psychetrajectory/blob/main/app/chatgpt-auth.ts"
click node_backend_cli "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/cli.py"
click node_synthetic "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/synthetic.py"
click node_io "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/io.py"
click node_schema "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/schema.py"
click node_preprocessing "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/preprocessing.py"
click node_splits "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/splits.py"
click node_pipeline "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/pipeline.py"
click node_encoder "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/encoder.py"
click node_kalman "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/kalman.py"
click node_inference "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/inference.py"
click node_heads "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/heads.py"
click node_diagnostics "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/diagnostics.py"
click node_api "https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/api.py"
click node_db_access "https://github.com/raghuram1811/psychetrajectory/blob/main/db/index.ts"
click node_empty_schema "https://github.com/raghuram1811/psychetrajectory/blob/main/db/schema.ts"

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,node_app_shell,node_auth,node_db_access,node_empty_schema toneBlue
class node_synthetic,node_io,node_schema,node_preprocessing,node_d1 toneAmber
class node_encoder,node_kalman,node_inference,node_heads,node_api toneMint
class node_backend_cli,node_splits,node_pipeline,node_diagnostics toneRose
class node_person toneIndigo
```

## Components

### Concept app

- [Interactive simulator](https://github.com/raghuram1811/psychetrajectory/blob/main/app/page.tsx): `app/page.tsx`
- [App shell](https://github.com/raghuram1811/psychetrajectory/blob/main/app/layout.tsx): `app/layout.tsx`
- [ChatGPT auth](https://github.com/raghuram1811/psychetrajectory/blob/main/app/chatgpt-auth.ts): `app/chatgpt-auth.ts`
- [D1 access helper](https://github.com/raghuram1811/psychetrajectory/blob/main/db/index.ts): `db/index.ts`
- [Empty app schema](https://github.com/raghuram1811/psychetrajectory/blob/main/db/schema.ts): `db/schema.ts`

### Observation pipeline

- [Synthetic signals](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/synthetic.py): `backend/src/psychetrajectory/synthetic.py`
- [Observation I/O](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/io.py): `backend/src/psychetrajectory/io.py`
- [Data contracts](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/schema.py): `backend/src/psychetrajectory/schema.py`
- [Daily features](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/preprocessing.py): `backend/src/psychetrajectory/preprocessing.py`

### Trajectory modeling

- [Masked encoder](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/encoder.py): `backend/src/psychetrajectory/encoder.py`
- [Trend filter](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/kalman.py): `backend/src/psychetrajectory/kalman.py`
- [Window inference](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/inference.py): `backend/src/psychetrajectory/inference.py`
- [Symptom heads](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/heads.py): `backend/src/psychetrajectory/heads.py`
- [Inference API](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/api.py): `backend/src/psychetrajectory/api.py`

### Research workflows

- [Research CLI](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/cli.py): `backend/src/psychetrajectory/cli.py`
- [Subject splits](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/splits.py): `backend/src/psychetrajectory/splits.py`
- [Training and replay](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/pipeline.py): `backend/src/psychetrajectory/pipeline.py`
- [Diagnostics](https://github.com/raghuram1811/psychetrajectory/blob/main/backend/src/psychetrajectory/diagnostics.py): `backend/src/psychetrajectory/diagnostics.py`

### Other components

- **Person or clinician**
- **Cloudflare D1**

## Connections

- Person or clinician → Interactive simulator: explores patterns (evidence: `README.md`)
- App shell → Interactive simulator: renders
- Research CLI → Synthetic signals: generates data (evidence: `backend/src/psychetrajectory/cli.py`)
- Research CLI → Observation I/O: reads and writes (evidence: `backend/src/psychetrajectory/cli.py`)
- Research CLI → Training and replay: trains or replays (evidence: `backend/src/psychetrajectory/cli.py`)
- Research CLI → Daily features: preprocesses (evidence: `backend/src/psychetrajectory/cli.py`)
- Research CLI → Diagnostics: evaluates (evidence: `backend/src/psychetrajectory/cli.py`)
- Research CLI → Symptom heads: trains heads (evidence: `backend/src/psychetrajectory/cli.py`)
- Observation I/O → Data contracts: uses types (evidence: `backend/src/psychetrajectory/io.py`)
- Synthetic signals → Data contracts: creates observations (evidence: `backend/src/psychetrajectory/synthetic.py`)
- Daily features → Data contracts: uses types (evidence: `backend/src/psychetrajectory/preprocessing.py`)
- Training and replay → Daily features: aggregates features (evidence: `backend/src/psychetrajectory/pipeline.py`)
- Training and replay → Subject splits: splits subjects (evidence: `backend/src/psychetrajectory/pipeline.py`)
- Training and replay → Masked encoder: trains and embeds (evidence: `backend/src/psychetrajectory/pipeline.py`)
- Training and replay → Symptom heads: uses heads (evidence: `backend/src/psychetrajectory/pipeline.py`)
- Training and replay → Trend filter: filters latents (evidence: `backend/src/psychetrajectory/pipeline.py`)
- Symptom heads → Data contracts: uses labels (evidence: `backend/src/psychetrajectory/heads.py`)
- Symptom heads → Subject splits: splits subjects (evidence: `backend/src/psychetrajectory/heads.py`)
- Window inference → Trend filter: updates state (evidence: `backend/src/psychetrajectory/inference.py`)
- Window inference → Data contracts: returns result (evidence: `backend/src/psychetrajectory/inference.py`)
- Inference API → Trend filter: uses filter (evidence: `backend/src/psychetrajectory/api.py`)
- Inference API → Data contracts: uses contracts (evidence: `backend/src/psychetrajectory/api.py`)
- D1 access helper → Cloudflare D1: connects to (evidence: `db/index.ts`)
- D1 access helper → Empty app schema: configures ORM (evidence: `db/index.ts`)
