# benjiesotelo-sudo/telos architecture

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

- Interactive diagram: https://gitdiagram.com/benjiesotelo-sudo/telos
- Repository: https://github.com/benjiesotelo-sudo/telos

## Overview

Telos is a browser-based statistical analysis app for thesis students: users upload a dataset, configure its variables, choose and configure tests, run analyses locally in WebR, then review and export results. The map highlights the guided screens, data and test-selection layers, registry-driven analysis, SEM/path-modeling capabilities, and reporting/export options. The README documents the overall workflow and capabilities; sampled source confirms key calls, but several screen and export internals were not inspected, so those links rely on README statements.

Main entry points: [`src/App.tsx`](https://github.com/benjiesotelo-sudo/telos/blob/main/src/App.tsx) (App router), [`src/components/screens/ResultsScreen.tsx`](https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/ResultsScreen.tsx) (Results screen), [`src/state/session.ts`](https://github.com/benjiesotelo-sudo/telos/blob/main/src/state/session.ts) (Session state), [`src/lib/stats/runCbSem.ts`](https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/stats/runCbSem.ts) (CB-SEM runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flow["Guided workflow"]
  node_app["App router<br/>[App.tsx]"]
  node_welcome["Welcome<br/>[WelcomeScreen.tsx]"]
  node_upload["Dataset upload<br/>[UploadScreen.tsx]"]
  node_guide["Terms guide<br/>[GuideScreen.tsx]"]
  node_configure["Configure data"]
  node_pick["Pick tests"]
  node_testconfig["Configure test"]
end

subgraph group_data["Data and selection"]
  node_session["Session state<br/>[session.ts]"]
  node_parsers["CSV and Excel parsing"]
  node_eligibility["Test eligibility<br/>[eligibility.ts]"]
end

subgraph group_analysis["Analysis runtime"]
  node_catalog["Test registry<br/>[catalog.ts]"]
  node_engine["WebR engine<br/>[engine.ts]"]
  node_runners["Statistical runners"]
  node_builders["Result builders<br/>[builders.ts]"]
end

subgraph group_sem["Latent modeling"]
  node_canvas["SEM model canvas<br/>[SemCanvas.tsx]"]
  node_semrunner["CB-SEM runner<br/>[runCbSem.ts]"]
  node_semhelpers["SEM helpers"]
  node_latentexport["Latent R emitter<br/>[latent.ts]"]
end

subgraph group_report["Results and export"]
  node_results["Results screen<br/>[ResultsScreen.tsx]"]
  node_preview["Result preview"]
  node_explainers["Method explainers<br/>[explainers.ts]"]
  node_citations["Method citations<br/>[citations.ts]"]
  node_export["Export bundle"]
end

node_student(("Thesis student"))

node_student -->|"uses"| node_app
node_app -->|"routes to"| node_welcome
node_app -->|"routes to"| node_upload
node_app -->|"routes to"| node_guide
node_app -->|"routes to"| node_configure
node_app -->|"routes to"| node_pick
node_app -->|"routes to"| node_testconfig
node_app -->|"routes to"| node_results
node_student -->|"advances workflow"| node_session
node_upload -->|"parses files"| node_parsers
node_session -->|"loads specs"| node_catalog
node_eligibility -->|"checks specs"| node_catalog
node_testconfig -->|"checks slots"| node_eligibility
node_session -->|"gets engine"| node_engine
node_session -->|"runs selected tests"| node_builders
node_builders -->|"dispatches tests"| node_runners
node_engine -.->|"executes R"| node_runners
node_canvas -->|"reads model state"| node_session
node_canvas -->|"uses SEM model"| node_semrunner
node_semrunner -->|"runs in"| node_engine
node_semrunner -->|"uses helpers"| node_semhelpers
node_latentexport -->|"uses model helpers"| node_semhelpers
node_results -->|"renders cards"| node_preview
node_preview -->|"builds card content"| node_builders
node_preview -->|"shows explanations"| node_explainers
node_results -->|"reads specs"| node_catalog
node_results -->|"adds citations"| node_citations
node_results -->|"creates downloads"| node_export

click node_app "https://github.com/benjiesotelo-sudo/telos/blob/main/src/App.tsx"
click node_welcome "https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/WelcomeScreen.tsx"
click node_upload "https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/UploadScreen.tsx"
click node_guide "https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/GuideScreen.tsx"
click node_configure "https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/ConfigureDataScreen.tsx"
click node_pick "https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/PickTestsScreen.tsx"
click node_testconfig "https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/TestConfigScreen.tsx"
click node_results "https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/ResultsScreen.tsx"
click node_session "https://github.com/benjiesotelo-sudo/telos/blob/main/src/state/session.ts"
click node_parsers "https://github.com/benjiesotelo-sudo/telos/tree/main/src/lib/data"
click node_eligibility "https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/eligibility/eligibility.ts"
click node_catalog "https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/registry/catalog.ts"
click node_engine "https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/webr/engine.ts"
click node_runners "https://github.com/benjiesotelo-sudo/telos/tree/main/src/lib/stats"
click node_builders "https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/results/builders.ts"
click node_canvas "https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/SemCanvas.tsx"
click node_semrunner "https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/stats/runCbSem.ts"
click node_semhelpers "https://github.com/benjiesotelo-sudo/telos/tree/main/src/lib/stats"
click node_latentexport "https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/export/rScript/emitters/latent.ts"
click node_preview "https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/ResultPreviewCard.tsx"
click node_explainers "https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/registry/explainers.ts"
click node_citations "https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/registry/citations.ts"
click node_export "https://github.com/benjiesotelo-sudo/telos/tree/main/src/lib/export"

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_welcome,node_upload,node_guide,node_configure,node_pick,node_testconfig toneBlue
class node_session,node_parsers,node_eligibility toneAmber
class node_catalog,node_engine,node_runners,node_builders toneMint
class node_canvas,node_semrunner,node_semhelpers,node_latentexport toneRose
class node_results,node_preview,node_explainers,node_citations,node_export,node_student toneIndigo
```

## Components

### Guided workflow

- [App router](https://github.com/benjiesotelo-sudo/telos/blob/main/src/App.tsx): `src/App.tsx`
- [Welcome](https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/WelcomeScreen.tsx): `src/components/screens/WelcomeScreen.tsx`
- [Dataset upload](https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/UploadScreen.tsx): `src/components/screens/UploadScreen.tsx`
- [Terms guide](https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/GuideScreen.tsx): `src/components/screens/GuideScreen.tsx`
- [Configure data](https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/ConfigureDataScreen.tsx): `src/components/screens/ConfigureDataScreen.tsx`
- [Pick tests](https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/PickTestsScreen.tsx): `src/components/screens/PickTestsScreen.tsx`
- [Configure test](https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/TestConfigScreen.tsx): `src/components/screens/TestConfigScreen.tsx`

### Data and selection

- [Session state](https://github.com/benjiesotelo-sudo/telos/blob/main/src/state/session.ts): `src/state/session.ts`
- [CSV and Excel parsing](https://github.com/benjiesotelo-sudo/telos/tree/main/src/lib/data): `src/lib/data`
- [Test eligibility](https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/eligibility/eligibility.ts): `src/lib/eligibility/eligibility.ts`

### Analysis runtime

- [Test registry](https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/registry/catalog.ts): `src/lib/registry/catalog.ts`
- [WebR engine](https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/webr/engine.ts): `src/lib/webr/engine.ts`
- [Statistical runners](https://github.com/benjiesotelo-sudo/telos/tree/main/src/lib/stats): `src/lib/stats`
- [Result builders](https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/results/builders.ts): `src/lib/results/builders.ts`

### Latent modeling

- [SEM model canvas](https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/SemCanvas.tsx): `src/components/SemCanvas.tsx`
- [CB-SEM runner](https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/stats/runCbSem.ts): `src/lib/stats/runCbSem.ts`
- [SEM helpers](https://github.com/benjiesotelo-sudo/telos/tree/main/src/lib/stats): `src/lib/stats`
- [Latent R emitter](https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/export/rScript/emitters/latent.ts): `src/lib/export/rScript/emitters/latent.ts`

### Results and export

- [Results screen](https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/screens/ResultsScreen.tsx): `src/components/screens/ResultsScreen.tsx`
- [Result preview](https://github.com/benjiesotelo-sudo/telos/blob/main/src/components/ResultPreviewCard.tsx): `src/components/ResultPreviewCard.tsx`
- [Method explainers](https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/registry/explainers.ts): `src/lib/registry/explainers.ts`
- [Method citations](https://github.com/benjiesotelo-sudo/telos/blob/main/src/lib/registry/citations.ts): `src/lib/registry/citations.ts`
- [Export bundle](https://github.com/benjiesotelo-sudo/telos/tree/main/src/lib/export): `src/lib/export`

### Other components

- **Thesis student**

## Connections

- Thesis student → App router: uses (evidence: `README.md`)
- App router → Welcome: routes to (evidence: `src/App.tsx`)
- App router → Dataset upload: routes to (evidence: `src/App.tsx`)
- App router → Terms guide: routes to (evidence: `src/App.tsx`)
- App router → Configure data: routes to (evidence: `src/App.tsx`)
- App router → Pick tests: routes to (evidence: `src/App.tsx`)
- App router → Configure test: routes to (evidence: `src/App.tsx`)
- App router → Results screen: routes to (evidence: `src/App.tsx`)
- Thesis student → Session state: advances workflow (evidence: `README.md`)
- Dataset upload → CSV and Excel parsing: parses files (evidence: `src/components/screens/UploadScreen.tsx`)
- Session state → Test registry: loads specs (evidence: `src/state/session.ts`)
- Test eligibility → Test registry: checks specs (evidence: `src/lib/eligibility/eligibility.ts`)
- Configure test → Test eligibility: checks slots (evidence: `README.md`)
- Session state → WebR engine: gets engine (evidence: `src/state/session.ts`)
- Session state → Result builders: runs selected tests (evidence: `src/state/session.ts`)
- Result builders → Statistical runners: dispatches tests (evidence: `src/lib/results/builders.ts`)
- WebR engine → Statistical runners: executes R (evidence: `src/lib/stats/runCbSem.ts`)
- SEM model canvas → Session state: reads model state (evidence: `src/components/SemCanvas.tsx`)
- SEM model canvas → CB-SEM runner: uses SEM model (evidence: `src/components/SemCanvas.tsx`)
- CB-SEM runner → WebR engine: runs in (evidence: `src/lib/stats/runCbSem.ts`)
- CB-SEM runner → SEM helpers: uses helpers (evidence: `src/lib/stats/runCbSem.ts`)
- Latent R emitter → SEM helpers: uses model helpers (evidence: `src/lib/export/rScript/emitters/latent.ts`)
- Results screen → Result preview: renders cards (evidence: `src/components/screens/ResultsScreen.tsx`)
- Result preview → Result builders: builds card content (evidence: `src/components/ResultPreviewCard.tsx`)
- Result preview → Method explainers: shows explanations (evidence: `src/components/ResultPreviewCard.tsx`)
- Results screen → Test registry: reads specs (evidence: `src/components/screens/ResultsScreen.tsx`)
- Results screen → Method citations: adds citations (evidence: `src/components/screens/ResultsScreen.tsx`)
- Results screen → Export bundle: creates downloads (evidence: `src/components/screens/ResultsScreen.tsx`)